From edd186e274eb9ed44a7c763f0a859c5ead637582 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Mon, 18 Apr 2011 18:53:30 +0100 Subject: [PATCH] Move documentation to inline comments: GtkUIManager --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtkuimanager.sgml | 508 ---------------------- gtk/gtkuimanager.c | 254 +++++++++++ gtk/gtkuimanager.h | 18 + 4 files changed, 273 insertions(+), 508 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkuimanager.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 997eb9e0f6..ac14a49130 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -140,5 +140,6 @@ gtktreestore.sgml gtktreeview.sgml gtktreeviewcolumn.sgml gtktypeutils.sgml +gtkuimanager.sgml gtkwindow.sgml gtkwindowgroup.sgml diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml deleted file mode 100644 index 721e444b89..0000000000 --- a/docs/reference/gtk/tmpl/gtkuimanager.sgml +++ /dev/null @@ -1,508 +0,0 @@ - -GtkUIManager - - -Constructing menus and toolbars from an XML description - - - -A #GtkUIManager constructs a user interface (menus and toolbars) from -one or more UI definitions, which reference actions from one or more -action groups. - -UI Definitions - -The UI definitions are specified in an XML format which can be -roughly described by the following DTD. - - -Do not confuse the GtkUIManager UI Definitions described here with -the similarly named GtkBuilder UI -Definitions. - - - - - - - - - - - - - - - - - - - - - -]]> -There are some additional restrictions beyond those specified in the -DTD, e.g. every toolitem must have a toolbar in its anchestry and -every menuitem must have a menubar or popup in its anchestry. Since -a #GMarkup parser is used to parse the UI description, it must not only -be valid XML, but valid #GMarkup. - - -If a name is not specified, it defaults to the action. If an action is -not specified either, the element name is used. The name and action -attributes must not contain '/' characters after parsing (since that -would mess up path lookup) and must be usable as XML attributes when -enclosed in doublequotes, thus they must not '"' characters or references -to the &quot; entity. - - -A UI definition - -<ui> - <menubar> - <menu name="FileMenu" action="FileMenuAction"> - <menuitem name="New" action="New2Action" /> - <placeholder name="FileMenuAdditions" /> - </menu> - <menu name="JustifyMenu" action="JustifyMenuAction"> - <menuitem name="Left" action="justify-left"/> - <menuitem name="Centre" action="justify-center"/> - <menuitem name="Right" action="justify-right"/> - <menuitem name="Fill" action="justify-fill"/> - </menu> - </menubar> - <toolbar action="toolbar1"> - <placeholder name="JustifyToolItems"> - <separator/> - <toolitem name="Left" action="justify-left"/> - <toolitem name="Centre" action="justify-center"/> - <toolitem name="Right" action="justify-right"/> - <toolitem name="Fill" action="justify-fill"/> - <separator/> - </placeholder> - </toolbar> -</ui> - - - -The constructed widget hierarchy is very similar to the element tree -of the XML, with the exception that placeholders are merged into their -parents. The correspondence of XML elements to widgets should be -almost obvious: - -menubar -a #GtkMenuBar - -toolbar -a #GtkToolbar - -popup -a toplevel #GtkMenu - -menu -a #GtkMenu attached to a menuitem - -menuitem -a #GtkMenuItem subclass, the exact type depends on the -action - -toolitem -a #GtkToolItem subclass, the exact type depends on the -action. Note that toolitem elements may contain a menu element, but only -if their associated action specifies a #GtkMenuToolButton as proxy. - -separator -a #GtkSeparatorMenuItem or -#GtkSeparatorToolItem - -accelerator -a keyboard accelerator - - - - -The "position" attribute determines where a constructed widget is positioned -wrt. to its siblings in the partially constructed tree. If it is -"top", the widget is prepended, otherwise it is appended. - - - -UI Merging - -The most remarkable feature of #GtkUIManager is that it can overlay a set -of menuitems and toolitems over another one, and demerge them later. - - -Merging is done based on the names of the XML elements. Each element is -identified by a path which consists of the names of its anchestors, separated -by slashes. For example, the menuitem named "Left" in the example above -has the path /ui/menubar/JustifyMenu/Left and the -toolitem with the same name has path -/ui/toolbar1/JustifyToolItems/Left. - - - -Accelerators - -Every action has an accelerator path. Accelerators are installed together with -menuitem proxies, but they can also be explicitly added with <accelerator> -elements in the UI definition. This makes it possible to have accelerators for -actions even if they have no visible proxies. - - - -Smart Separators - -The separators created by #GtkUIManager are "smart", i.e. they do not show up -in the UI unless they end up between two visible menu or tool items. Separators -which are located at the very beginning or end of the menu or toolbar -containing them, or multiple separators next to each other, are hidden. This -is a useful feature, since the merging of UI elements from multiple sources -can make it hard or impossible to determine in advance whether a separator -will end up in such an unfortunate position. - - - -For separators in toolbars, you can set expand="true" to -turn them from a small, visible separator to an expanding, invisible one. -Toolitems following an expanding separator are effectively right-aligned. - - - -Empty Menus - -Submenus pose similar problems to separators inconnection with merging. It is -impossible to know in advance whether they will end up empty after merging. -#GtkUIManager offers two ways to treat empty submenus: - -make them disappear by hiding the menu item they're attached to - -add an insensitive "Empty" item - - -The behaviour is chosen based on the "hide_if_empty" property of the action -to which the submenu is associated. - - - - -GtkUIManager as GtkBuildable - -The GtkUIManager implementation of the GtkBuildable interface accepts -GtkActionGroup objects as <child> elements in UI definitions. - - -A GtkUIManager UI definition as described above can be embedded in -an GtkUIManager <object> element in a GtkBuilder UI definition. - - -The widgets that are constructed by a GtkUIManager can be embedded in -other parts of the constructed user interface with the help of the -"constructor" attribute. See the example below. - - -An embedded GtkUIManager UI definition - - - - - - _File - - - - - - - - - - - - - - - - -]]> - - - - - -#GtkBuilder - - - - - - - - - - -The GtkUIManager struct contains only private -members and should not be accessed directly. - - - - - - - - -@uimanager: the object which received the signal. - - - - - - -@uimanager: the object which received the signal. -@widget: - - - - - - -@uimanager: the object which received the signal. -@arg1: -@widget: - - - - - - -@uimanager: the object which received the signal. -@arg1: -@widget: - - - - - - -@uimanager: the object which received the signal. -@arg1: - - - - - - -@uimanager: the object which received the signal. -@arg1: - - - - - - - - - - - - - - - - -@void: -@Returns: - - - - - - - -@manager: -@add_tearoffs: - - - - - - - -@manager: -@Returns: - - - - - - - -@manager: -@action_group: -@pos: - - - - - - - -@manager: -@action_group: - - - - - - - -@manager: -@Returns: - - - - - - - -@manager: -@Returns: - - - - - - - -@manager: -@path: -@Returns: - - - - - - - -@manager: -@types: -@Returns: - - - - - - - -@manager: -@path: -@Returns: - - - - - - - -@manager: -@buffer: -@length: -@error: -@Returns: - - - - - - - -@manager: -@filename: -@error: -@Returns: - - - - - - - -@manager: -@Returns: - - - - -These enumeration values are used by gtk_ui_manager_add_ui() to determine -what UI element to create. - - -@GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context. -@GTK_UI_MANAGER_MENUBAR: Create a menubar. -@GTK_UI_MANAGER_MENU: Create a menu. -@GTK_UI_MANAGER_TOOLBAR: Create a toolbar. -@GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder. -@GTK_UI_MANAGER_POPUP: Create a popup menu. -@GTK_UI_MANAGER_MENUITEM: Create a menuitem. -@GTK_UI_MANAGER_TOOLITEM: Create a toolitem. -@GTK_UI_MANAGER_SEPARATOR: Create a separator. -@GTK_UI_MANAGER_ACCELERATOR: Install an accelerator. -@GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the actions' accelerators are shown. - - - - - - -@manager: -@merge_id: -@path: -@name: -@action: -@type: -@top: - - - - - - - -@manager: -@merge_id: - - - - - - - -@manager: -@Returns: - - - - - - - -@manager: - - diff --git a/gtk/gtkuimanager.c b/gtk/gtkuimanager.c index e5e536a401..6f1c62598e 100644 --- a/gtk/gtkuimanager.c +++ b/gtk/gtkuimanager.c @@ -49,6 +49,260 @@ #include "gtkwindow.h" #include "gtkprivate.h" + +/** + * SECTION:gtkuimanager + * @Short_description: Constructing menus and toolbars from an XML description + * @Title: GtkUIManager + * @See_also:#GtkBuilder + * + * A #GtkUIManager constructs a user interface (menus and toolbars) from + * one or more UI definitions, which reference actions from one or more + * action groups. + * + * + * UI Definitions + * + * The UI definitions are specified in an XML format which can be + * roughly described by the following DTD. + * + * + * Do not confuse the GtkUIManager UI Definitions described here with + * the similarly named GtkBuilder UI + * Definitions. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ]]> + * + * There are some additional restrictions beyond those specified in the + * DTD, e.g. every toolitem must have a toolbar in its anchestry and + * every menuitem must have a menubar or popup in its anchestry. Since + * a #GMarkup parser is used to parse the UI description, it must not only + * be valid XML, but valid #GMarkup. + * + * If a name is not specified, it defaults to the action. If an action is + * not specified either, the element name is used. The name and action + * attributes must not contain '/' characters after parsing (since that + * would mess up path lookup) and must be usable as XML attributes when + * enclosed in doublequotes, thus they must not '"' characters or references + * to the " entity. + * + * + * A UI definition + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * The constructed widget hierarchy is very similar to the element tree + * of the XML, with the exception that placeholders are merged into their + * parents. The correspondence of XML elements to widgets should be + * almost obvious: + * + * + * menubar + * a #GtkMenuBar + * + * + * toolbar + * a #GtkToolbar + * + * + * popup + * a toplevel #GtkMenu + * + * + * menu + * a #GtkMenu attached to a menuitem + * + * + * menuitem + * a #GtkMenuItem subclass, the exact type depends on the + * action + * + * + * toolitem + * a #GtkToolItem subclass, the exact type depends on the + * action. Note that toolitem elements may contain a menu element, but only + * if their associated action specifies a #GtkMenuToolButton as proxy. + * + * + * separator + * a #GtkSeparatorMenuItem or + * #GtkSeparatorToolItem + * + * + * accelerator + * a keyboard accelerator + * + * + * + * The "position" attribute determines where a constructed widget is positioned + * wrt. to its siblings in the partially constructed tree. If it is + * "top", the widget is prepended, otherwise it is appended. + * + * + * + * UI Merging + * + * The most remarkable feature of #GtkUIManager is that it can overlay a set + * of menuitems and toolitems over another one, and demerge them later. + * + * Merging is done based on the names of the XML elements. Each element is + * identified by a path which consists of the names of its anchestors, separated + * by slashes. For example, the menuitem named "Left" in the example above + * has the path /ui/menubar/JustifyMenu/Left and the + * toolitem with the same name has path + * /ui/toolbar1/JustifyToolItems/Left. + * + * + * + * Accelerators + * + * Every action has an accelerator path. Accelerators are installed together with + * menuitem proxies, but they can also be explicitly added with <accelerator> + * elements in the UI definition. This makes it possible to have accelerators for + * actions even if they have no visible proxies. + * + * + * + * Smart Separators + * + * The separators created by #GtkUIManager are "smart", i.e. they do not show up + * in the UI unless they end up between two visible menu or tool items. Separators + * which are located at the very beginning or end of the menu or toolbar + * containing them, or multiple separators next to each other, are hidden. This + * is a useful feature, since the merging of UI elements from multiple sources + * can make it hard or impossible to determine in advance whether a separator + * will end up in such an unfortunate position. + * + * For separators in toolbars, you can set expand="true" to + * turn them from a small, visible separator to an expanding, invisible one. + * Toolitems following an expanding separator are effectively right-aligned. + * + * + * + * Empty Menus + * + * Submenus pose similar problems to separators inconnection with merging. It is + * impossible to know in advance whether they will end up empty after merging. + * #GtkUIManager offers two ways to treat empty submenus: + * + * + * make them disappear by hiding the menu item they're attached to + * + * + * add an insensitive "Empty" item + * + * + * The behaviour is chosen based on the "hide_if_empty" property of the action + * to which the submenu is associated. + * + * + * + * GtkUIManager as GtkBuildable + * + * The GtkUIManager implementation of the GtkBuildable interface accepts + * GtkActionGroup objects as <child> elements in UI definitions. + * + * A GtkUIManager UI definition as described above can be embedded in + * an GtkUIManager <object> element in a GtkBuilder UI definition. + * + * The widgets that are constructed by a GtkUIManager can be embedded in + * other parts of the constructed user interface with the help of the + * "constructor" attribute. See the example below. + * + * + * An embedded GtkUIManager UI definition + * + * + * + * + * + * _File + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ]]> + * + * + * + */ + + #undef DEBUG_UI_MANAGER typedef enum diff --git a/gtk/gtkuimanager.h b/gtk/gtkuimanager.h index 27cc84f5fc..8e8b618625 100644 --- a/gtk/gtkuimanager.h +++ b/gtk/gtkuimanager.h @@ -92,6 +92,24 @@ struct _GtkUIManagerClass { void (*_gtk_reserved4) (void); }; +/** + * GtkUIManagerItemType: + * @GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context. + * @GTK_UI_MANAGER_MENUBAR: Create a menubar. + * @GTK_UI_MANAGER_MENU: Create a menu. + * @GTK_UI_MANAGER_TOOLBAR: Create a toolbar. + * @GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder. + * @GTK_UI_MANAGER_POPUP: Create a popup menu. + * @GTK_UI_MANAGER_MENUITEM: Create a menuitem. + * @GTK_UI_MANAGER_TOOLITEM: Create a toolitem. + * @GTK_UI_MANAGER_SEPARATOR: Create a separator. + * @GTK_UI_MANAGER_ACCELERATOR: Install an accelerator. + * @GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the + * actions' accelerators are shown. + * + * These enumeration values are used by gtk_ui_manager_add_ui() to determine + * what UI element to create. + */ typedef enum { GTK_UI_MANAGER_AUTO = 0, GTK_UI_MANAGER_MENUBAR = 1 << 0,