diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 2c06f57bbe..3eb5fcda3d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,8 @@ 2003-09-02 Matthias Clasen + * gtk/tmpl/gtkactiongroup.sgml: + * gtk/tmpl/gtkuimanager.sgml: Additions. + * gtk/gtk-sections.txt: Add gtk_ui_manager_new_merge_id and gtk_ui_manager_add_ui. diff --git a/docs/reference/gtk/tmpl/gtkactiongroup.sgml b/docs/reference/gtk/tmpl/gtkactiongroup.sgml index 04addcf0d1..da03365b6e 100644 --- a/docs/reference/gtk/tmpl/gtkactiongroup.sgml +++ b/docs/reference/gtk/tmpl/gtkactiongroup.sgml @@ -15,10 +15,18 @@ should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most nontrivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions -(eg. quit, about, new), and one group per document holding actions that +(e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window's menus would be constructed from a combination of two action groups. + +Accelerators are handled by the GTK+ accelerator map. All actions are +assigned an accelerator path of the form +<Actions>/group-name/action-name when they are added to an action group, +and a shortcut is associated with this accelerator path. All menuitems and +toolitems take on this accelerator path. The GTK+ accelerator map code makes +sure that the correct shortcut is displayed next to the menu item. + @@ -27,8 +35,8 @@ would be constructed from a combination of two action groups. -The GtkActionGroup struct contains only private members -and should not be accessed directly. +The GtkActionGroup struct contains only private +members and should not be accessed directly. @@ -44,10 +52,11 @@ gtk_action_group_add_actions() to construct actions. translation, see gtk_action_group_set_translation_domain(). @accelerator: The accelerator for the action, in the format understood by gtk_accelerator_parse(). -@tooltip: The tooltip for the action. This field should typically be marked for - translation, see gtk_action_group_set_translation_domain(). +@tooltip: The tooltip for the action. This field should typically be marked + for translation, see gtk_action_group_set_translation_domain(). @callback: The function to call when the action is activated. -@is_toggle: If this is %TRUE, a #GtkToggleAction is constructed, else a #GtkAction. +@is_toggle: If this is %TRUE, a #GtkToggleAction is constructed, else a + #GtkAction. diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml index dbcf7fb562..5d845fea1c 100644 --- a/docs/reference/gtk/tmpl/gtkuimanager.sgml +++ b/docs/reference/gtk/tmpl/gtkuimanager.sgml @@ -7,13 +7,13 @@ 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 ore -action groups. +one or more UI definitions, which reference actions from one or more +action groups. UI Definitions -The UI definitions are specified in a #GMarkup format which can be -roughly described by the following XML DTD. +The UI definitions are specified in an XML format which can be +roughly described by the following DTD. <!ELEMENT ui (menubar|toolbar|popup)* > <!ELEMENT menubar (menuitem|separator|placeholder|menu)* > @@ -40,9 +40,11 @@ roughly described by the following XML DTD. 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. If a name -is not specified, it defaults to the action. If an action is not specified -either, the element name is used. +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. A UI definition @@ -111,6 +113,21 @@ 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 name 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. + + @@ -119,7 +136,8 @@ wrt. to its siblings in the partially constructed tree. If it is - +The GtkUIManager struct contains only private +members and should not be accessed directly. @@ -229,6 +247,27 @@ wrt. to its siblings in the partially constructed tree. If it is @Returns: + + + + + +@self: +@Returns: + + + + + + + +@self: +@merge_id: +@path: +@name: +@action: + +