forked from AuroraMiddleware/gtk
6c227b5a65
* tests/merge-2.ui: Use "position" instead of "pos". * gtk/gtkuimanager.c (start_element_handler): No need to be terse: Change the name of the "pos" attribute to "position". * gtk/tmpl/gtkuimanager.sgml: Change the name of the "pos" attribute to "position".
317 lines
7.3 KiB
Plaintext
317 lines
7.3 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GtkUIManager
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
constructing menus and toolbars from an XML description
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
A #GtkUIManager constructs a user interface (menus and toolbars) from
|
|
one or more UI definitions, which reference actions from one or more
|
|
action groups.
|
|
</para>
|
|
<refsect2 id="XML-UI"><title>UI Definitions</title>
|
|
<para>
|
|
The UI definitions are specified in an XML format which can be
|
|
roughly described by the following DTD.
|
|
<programlisting>
|
|
<!ELEMENT ui (menubar|toolbar|popup)* >
|
|
<!ELEMENT menubar (menuitem|separator|placeholder|menu)* >
|
|
<!ELEMENT menu (menuitem|separator|placeholder|menu)* >
|
|
<!ELEMENT popup (menuitem|separator|placeholder|menu)* >
|
|
<!ELEMENT toolbar (toolitem|separator|placeholder)* >
|
|
<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
|
|
<!ELEMENT menuitem EMPTY >
|
|
<!ELEMENT toolitem EMPTY >
|
|
<!ELEMENT separator EMPTY >
|
|
<!ATTLIST menubar name #IMPLIED >
|
|
<!ATTLIST toolbar name #IMPLIED >
|
|
<!ATTLIST popup name #IMPLIED >
|
|
<!ATTLIST placeholder name #IMPLIED >
|
|
<!ATTLIST menu name #IMPLIED
|
|
action #REQUIRED
|
|
position (top|bot) #IMPLIED >
|
|
<!ATTLIST menuitem name #IMPLIED
|
|
action #REQUIRED
|
|
position (top|bot) #IMPLIED >
|
|
<!ATTLIST toolitem name #IMPLIED
|
|
action #REQUIRED
|
|
position (top|bot) #IMPLIED >
|
|
</programlisting>
|
|
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.
|
|
</para>
|
|
<example>
|
|
<title>A UI definition</title>
|
|
<programlisting>
|
|
<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>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
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:
|
|
<variablelist>
|
|
<varlistentry><term>menubar</term>
|
|
<listitem><para>a #GtkMenuBar</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>toolbar</term>
|
|
<listitem><para>a #GtkToolbar</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>popup</term>
|
|
<listitem><para>a toplevel #GtkMenu</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>menu</term>
|
|
<listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>menuitem</term>
|
|
<listitem><para>a #GtkMenuItem subclass, the exact type depends on the
|
|
action</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>toolitem</term>
|
|
<listitem><para>a #GtkToolItem subclass, the exact type depends on the
|
|
action</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>separator</term>
|
|
<listitem><para>a #GtkSeparatorMenuItem or
|
|
#GtkSeparatorToolItem</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 id="UI-Merging">
|
|
<title>UI Merging</title>
|
|
<para>
|
|
The most remarkable feature of #GtkUIManager is that it can overlay a set
|
|
of menuitems and toolitems over another one, and demerge them later.
|
|
</para>
|
|
<para>
|
|
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 <literal>/ui/menubar/JustifyMenu/Left</literal> and the
|
|
toolitem with the same name has path
|
|
<literal>/ui/toolbar1/JustifyToolItems/Left</literal>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### STRUCT GtkUIManager ##### -->
|
|
<para>
|
|
The <structname>GtkUIManager</structname> struct contains only private
|
|
members and should not be accessed directly.
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@add_tearoffs:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@action_group:
|
|
@pos:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@action_group:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@path:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@path:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@buffer:
|
|
@length:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@filename:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@merge_id:
|
|
@path:
|
|
@name:
|
|
@action:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@merge_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@self:
|
|
|
|
|
|
<!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@uimanager: the object which received the signal.
|
|
@widget:
|
|
|
|
<!-- ##### SIGNAL GtkUIManager::changed ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@uimanager: the object which received the signal.
|
|
|
|
<!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|