gtk.UIManagerconstruct menus and toolbars from an XML
description (new in PyGTK 2.4)Synopsisgtk.UIManagergobject.GObjectgtk.UIManagerset_add_tearoffsadd_tearoffsget_add_tearoffsinsert_action_groupaction_grouppos-1remove_action_groupaction_groupget_action_groupsget_accel_groupget_widgetpathget_toplevelstypesget_actionpathadd_ui_from_stringbufferadd_ui_from_filefilenameadd_uimerge_idpathnameactiontypetopremove_uimerge_idget_uiensure_updatenew_merge_idAncestry+-- gobject.GObject
+-- gtk.UIManager
Implemented Interfacesgtk.UIManager
implements
gtk.Buildablegtk.UIManager Properties
"add-tearoffs"Read-WriteIf True, regular menus have tearoff
menu items. Note that this only affects regular menus. Generated popup menus
never have tearoff menu items. Available in GTK+ 2.4 and
above."ui"Read-WriteAn XML string describing the merged UI.
gtk.UIManager Signal Prototypesgobject.GObject Signal Prototypes"actions-changed"callbackuimanageruser_param1..."add-widget"callbackuimanagerwidgetuser_param1..."connect-proxy"callbackuimanageractionwidgetuser_param1..."disconnect-proxy"callbackuimanageractionwidgetuser_param1..."post-activate"callbackuimanageractionuser_param1..."pre-activate"callbackuimanageractionuser_param1...DescriptionThis object is available in PyGTK 2.4 and above.A gtk.UIManager
constructs a user interface (menus and toolbars) from one or more UI
definitions, which reference actions from one or more action groups.UI DefinitionsThe UI definitions are specified in an XML format which can be
roughly described by the following DTD.
<!ELEMENT ui (menubar|toolbar|popup|accelerator)* >
<!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 >
<!ELEMENT accelerator 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 >
<!ATTLIST accelerator name #IMPLIED
action #REQUIRED >
There are some additional restrictions beyond those specified in
the DTD, e.g. every toolitem must have a toolbar in its ancestry and every
menuitem must have a menubar or popup in its ancestry. 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
<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:menubara gtk.MenuBartoolbara gtk.Toolbarpopupa toplevel gtk.Menumenua gtk.Menu
attached to a menuitemmenuitema gtk.MenuItem
subclass, the exact type depends on the actiontoolitema gtk.ToolItem
subclass, the exact type depends on the actionseparatora gtk.SeparatorMenuItem
or gtk.SeparatorToolItemacceleratora keyboard acceleratorThe "position" attribute determines where a constructed widget
is positioned with respect to its siblings in the partially constructed
tree. If it is "top", the widget is prepended, otherwise it is
appended.UI MergingThe most remarkable feature of gtk.UIManager 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
ancestors, 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.AcceleratorsEvery 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 SeparatorsThe separators created by gtk.UIManager 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.Empty MenusSubmenus pose similar problems to separators in connection with
merging. It is impossible to know in advance whether they will end up empty
after merging. gtk.UIManager
offers two ways to treat empty submenus:make them disappear by hiding the menu item they're
attached toadd an insensitive "Empty" itemThe behavior is chosen based on the "is_important" property of
the action to which the submenu is associated.Constructorgtk.UIManagerReturns :a new ui manager object.This constructor is available in PyGTK 2.4 and above.Creates a new gtk.UIManager
object.Methodsgtk.UIManager.set_add_tearoffsset_add_tearoffsadd_tearoffsadd_tearoffs :True if tearoff menu items
are added to regular menusThis method is available in PyGTK 2.4 and above.The add_tearoffs() method sets the
"add_tearoffs" property to the value of
add_tearoffs. If add_tearoffs
is True regular menus generated by this gtk.UIManager
will have tearoff menu items.Note that this only affects regular menus. Generated popup menus
never have tearoff menu items.gtk.UIManager.get_add_tearoffsget_add_tearoffsReturns :True if tearoff menu items
are addedThis method is available in PyGTK 2.4 and above.The get_add_tearoffs() method returns
the value of the "add-tearoffs" property. If "add-tearoffs" is
True regular menus generated will have tearoff menu
items.gtk.UIManager.insert_action_groupinsert_action_groupaction_grouppos-1action_group :the action group to be
insertedpos :the position at which the group will be
inserted. If pos is negative
action_group is inserted at the end of the
list.This method is available in PyGTK 2.4 and above.pos has default value since PyGTK 2.12.The insert_action_group() method
inserts the gtk.ActionGroup
specified by action_group into the list of associated
action groups at the position specified by
pos. If pos is negative, new
action group is inserted at the end of the list. Actions in earlier groups
hide actions with the same name in later groups.gtk.UIManager.remove_action_groupremove_action_groupaction_groupaction_group :the action group to be
removedThis method is available in PyGTK 2.4 and above.The remove_action_group() method
removes the gtk.ActionGroup
specified by action_group from the list of
associated action groups.gtk.UIManager.get_action_groupsget_action_groupsReturns :a list of associated action
groups.This method is available in PyGTK 2.4 and above.The get_action_groups() method returns
the list of associated gtk.ActionGroup
objects.gtk.UIManager.get_accel_groupget_accel_groupReturns :the gtk.AccelGroup.This method is available in PyGTK 2.4 and above.The get_accel_group() method returns
the associated gtk.AccelGroup.gtk.UIManager.get_widgetget_widgetpathpath :a pathReturns :the widget found by following the path, or
None if no widget was
found.This method is available in PyGTK 2.4 and above.The get_widget() method looks up a
widget by following the path specified by path. The
path consists of the names specified in the XML description of the UI.
separated by '/'. Elements that don't have a name or action attribute in
the XML (e.g. <popup>) can be addressed by their XML element name
(e.g. "popup"). The root element ("/ui") can be omitted in the path.gtk.UIManager.get_toplevelsget_toplevelstypestypes :specifies the types of toplevel widgets to
include. Allowed types are
gtk.UI_MANAGER_MENUBAR,
gtk.UI_MANAGER_TOOLBAR and
gtk.UI_MANAGER_POPUP.Returns :a list of all toplevel widgets of the requested
types.This method is available in PyGTK 2.4 and above.The get_toplevels() method returns a
list of all toplevel widgets of the types specified by
types.gtk.UIManager.get_actionget_actionpathpath :a pathReturns :the action whose proxy widget is found by
following the path, or None if no widget was
found.This method is available in PyGTK 2.4 and above.The get_action() method looks up a
gtk.Action by
following a path. See the get_widget()
method for more information about paths.gtk.UIManager.add_ui_from_stringadd_ui_from_stringbufferbuffer :the string to parseReturns :The merge id for the merged UI. The merge id
can be used to unmerge the UI with the remove_ui()
method.This method is available in PyGTK 2.4 and above.The add_ui_from_string() method parses
the string specified by buffer that contains a UI definition and merges it with the current
contents of the ui manager. An enclosing <ui> element is added if it
is missing.This method raise the GError exception if an error occurs during
the parsing of the string.gtk.UIManager.add_ui_from_fileadd_ui_from_filefilenamefilename :the name of the file to parseReturns :The merge id for the merged UI. The merge id
can be used to unmerge the UI with the gtk.UIManager.remove_ui()
method.This method is available in PyGTK 2.4 and above.The add_ui_from_file() method parses
the file specified by filename that contains a UI definition and merges it with the current
contents of the ui manager.This method raise the GError exception if an error occurs during
the parsing of the file.gtk.UIManager.add_uiadd_uimerge_idpathnameactiontypetopmerge_id :the merge id for the merged UI, see new_merge_id()path :a path where the element should be
addedname :the name for the added UI
elementaction :the name of the action to be proxied, or
None to add a separatortype :the type of UI element to
add.top :if True, the UI element is
added before its siblings, otherwise it is added after its
siblings.This method is available in PyGTK 2.4 and above.The add_ui() method adds a UI element
of the type specified by type to the current contents
of the ui manager at the location specified by
path. Note that path must not start with "/ui" though
"ui" is acceptable. For example "/menubar" or "ui/menubar" is acceptable but
"/ui/menubar" is not. type must be one of:gtk.UI_MANAGER_AUTOThe type of the UI element (menuitem, toolitem or
separator) is set according to the context.gtk.UI_MANAGER_MENUBARA menubar. gtk.UI_MANAGER_MENUA menu.gtk.UI_MANAGER_TOOLBARA toolbar.gtk.UI_MANAGER_PLACEHOLDERA placeholder.gtk.UI_MANAGER_POPUPA popup menu.gtk.UI_MANAGER_MENUITEMA menuitem.gtk.UI_MANAGER_TOOLITEMA toolitem.gtk.UI_MANAGER_SEPARATORA separator.gtk.UI_MANAGER_ACCELERATORAn accelerator.gtk.UIManager.remove_uiremove_uimerge_idmerge_id :a merge idThis method is available in PyGTK 2.4 and above.The remove_ui() method unmerges the
part of the ui manager content identified by
merge_id.gtk.UIManager.get_uiget_uiReturns :A string containing an XML representation of
the merged UI.This method is available in PyGTK 2.4 and above.The get_ui() method creates a UI definition of the merged UI.gtk.UIManager.ensure_updateensure_updateThis method is available in PyGTK 2.4 and above.The ensure_update() method makes sure
that all pending updates to the UI have been completed. This may
occasionally be necessary, since gtk.UIManager
updates the UI in an idle function. A typical example where this method is
useful is to enforce that the menubar and toolbar have been added to the
main window before showing it:
window.add(vbox)
merge.connect("add_widget", add_widget, vbox)
merge.add_ui_from_file("my-menus")
merge.add_ui_from_file("my-toolbars")
merge.ensure_update()
window.show()
gtk.UIManager.new_merge_idnew_merge_idReturns :an unused merge id.This method is available in PyGTK 2.4 and above.The new_merge_id() method returns an
unused merge id, suitable for use with the add_ui()
method. The returned merge ids are monotonically increasing integer
values.SignalsThe "actions-changed" gtk.UIManager Signalcallbackuimanageruser_param1...uimanager :the uimanager that received the
signaluser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)This signal is available in GTK+ 2.4 and above.The "actions-changed" signal is emitted when the set of actions
changes.The "add-widget" gtk.UIManager Signalcallbackuimanagerwidgetuser_param1...uimanager :the uimanager that received the
signalwidget :the added widgetuser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)This signal is available in GTK+ 2.4 and above.The "add-widget" signal is emitted for each generated menubar
and toolbar. The added widget is specified by
widget. It is not emitted for generated popup menus,
which can be retrieved by the get_widget()
method.The "connect-proxy" gtk.UIManager Signalcallbackuimanageractionwidgetuser_param1...uimanager :the uimanager that received the
signalaction :the actionwidget :the proxy widgetuser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)This signal is available in GTK+ 2.4 and above.The "connect-proxy" signal is emitted after connecting the proxy
widget specified by widget to the gtk.Action specified
by action in the group. This is intended for simple
customizations for which a custom action class would be too clumsy,
e.g. showing tooltips for menuitems in the statusbar.The "disconnect-proxy" gtk.UIManager Signalcallbackuimanageractionwidgetuser_param1...uimanager :the uimanager that received the
signalaction :the actionwidget :the proxy widgetuser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)This signal is available in GTK+ 2.4 and above.The "disconnect-proxy" signal is emitted when
widget is disconnected from
action.The "post-activate" gtk.UIManager Signalcallbackuimanageractionuser_param1...uimanager :the uimanager that received the
signalaction :the actionuser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)This signal is available in GTK+ 2.4 and above.The "post-activate" signal is emitted after
action is activated. This signal is intended for
applications to get notification after any action is activated.The "pre-activate" gtk.UIManager Signalcallbackuimanageractionuser_param1...uimanager :the uimanager that received the
signalaction :the actionuser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)This signal is available in GTK+ 2.4 and above.The "pre-activate" signal is emitted before
action is activated. This signal is intended for
applications to get notification before any action is activated.