UIManager

A #GtkUIManager constructs a user interface (menus and toolbars) from one or more UI definitions, which reference actions from one or more action groups.

> GtkUIManager is deprecated since GTK+ 3.10. To construct user interfaces > from XML definitions, you should use #GtkBuilder, #GMenuModel, et al. To > work with actions, use #GAction, #GtkActionable et al. These newer classes > support richer functionality and integration with various desktop shells. > It should be possible to migrate most/all functionality from GtkUIManager.

UI Definitions # {#XML-UI}

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][BUILDER-UI].

<!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     (menu?) >
<!ELEMENT separator    EMPTY >
<!ELEMENT accelerator  EMPTY >
<!ATTLIST menubar      name                      #IMPLIED
                       action                    #IMPLIED >
<!ATTLIST toolbar      name                      #IMPLIED
                       action                    #IMPLIED >
<!ATTLIST popup        name                      #IMPLIED
                       action                    #IMPLIED
                       accelerators (true|false) #IMPLIED >
<!ATTLIST placeholder  name                      #IMPLIED
                       action                    #IMPLIED >
<!ATTLIST separator    name                      #IMPLIED
                       action                    #IMPLIED
                       expand       (true|false) #IMPLIED >
<!ATTLIST menu         name                      #IMPLIED
                       action                    #REQUIRED
                       position     (top|bot)    #IMPLIED >
<!ATTLIST menuitem     name                      #IMPLIED
                       action                    #REQUIRED
                       position     (top|bot)    #IMPLIED
                       always-show-image (true|false) #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 anchestry and every menuitem must have a menubar or popup in its anchestry. Since a #GMarkupParser is used to parse the UI description, it must not only be valid XML, but valid markup.

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 #

<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 # {#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 # {#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 # {#GtkUIManager-BUILDER-UI}

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

<object class="GtkUIManager" id="uiman">
  <child>
    <object class="GtkActionGroup" id="actiongroup">
      <child>
        <object class="GtkAction" id="file">
          <property name="label">_File</property>
        </object>
      </child>
    </object>
  </child>
  <ui>
    <menubar name="menubar1">
      <menu action="file">
      </menu>
    </menubar>
  </ui>
</object>
<object class="GtkWindow" id="main-window">
  <child>
    <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
  </child>
</object>

class UIManager : ObjectWrap , Buildable {

this(void* ptr, Flag!"Take" take);

static GType _getGType();

GType _gType [@property getter];

UIManager self();

static UIManagerGidBuilder builder();

bool addTearoffs [@property getter];

bool addTearoffs [@property setter];

string ui [@property getter];

this();

void addUi(uint mergeId, string path, string name, string action, gtk.types.UIManagerItemType type, bool top);

uint addUiFromFile(string filename);

uint addUiFromResource(string resourcePath);

uint addUiFromString(string buffer);

void ensureUpdate();

gtk.accel_group.AccelGroup getAccelGroup();

gtk.action.Action getAction(string path);

gtk.action_group.ActionGroup[] getActionGroups();

bool getAddTearoffs();

gtk.widget.Widget[] getToplevels(gtk.types.UIManagerItemType types);

string getUi();

gtk.widget.Widget getWidget(string path);

void insertActionGroup(gtk.action_group.ActionGroup actionGroup, int pos);

uint newMergeId();

void removeActionGroup(gtk.action_group.ActionGroup actionGroup);

void removeUi(uint mergeId);

void setAddTearoffs(bool addTearoffs);

gulong connectActionsChanged(T callback, Flag!"After" after);

gulong connectAddWidget(T callback, Flag!"After" after);

gulong connectConnectProxy(T callback, Flag!"After" after);

gulong connectDisconnectProxy(T callback, Flag!"After" after);

gulong connectPostActivate(T callback, Flag!"After" after);

gulong connectPreActivate(T callback, Flag!"After" after);

}

Constructors

this this(void* ptr, Flag!"Take" take)
this this(): Creates a new ui manager object.

Members

Functions

addUi void addUi(uint mergeId, string path, string name, string action, gtk.types.UIManagerItemType type, bool top): Adds a UI element to the current contents of manager.
addUiFromFile uint addUiFromFile(string filename): Parses a file containing a [UI definition][XML-UI] and merges it with the current contents of manager.
addUiFromResource uint addUiFromResource(string resourcePath): Parses a resource file containing a [UI definition][XML-UI] and merges it with the current contents of manager.
addUiFromString uint addUiFromString(string buffer): Parses a string containing a [UI definition][XML-UI] and merges it with the current contents of manager. An enclosing <ui> element is added if it is missing.
connectActionsChanged gulong connectActionsChanged(T callback, Flag!"After" after): Connect to ActionsChanged signal.
connectAddWidget gulong connectAddWidget(T callback, Flag!"After" after): Connect to AddWidget signal.
connectConnectProxy gulong connectConnectProxy(T callback, Flag!"After" after): Connect to ConnectProxy signal.
connectDisconnectProxy gulong connectDisconnectProxy(T callback, Flag!"After" after): Connect to DisconnectProxy signal.
connectPostActivate gulong connectPostActivate(T callback, Flag!"After" after): Connect to PostActivate signal.
connectPreActivate gulong connectPreActivate(T callback, Flag!"After" after): Connect to PreActivate signal.
ensureUpdate void ensureUpdate(): Makes sure that all pending updates to the UI have been completed.
getAccelGroup gtk.accel_group.AccelGroup getAccelGroup(): Returns the #GtkAccelGroup associated with manager.
getAction gtk.action.Action getAction(string path): Looks up an action by following a path. See gtk.uimanager.UIManager.getWidget for more information about paths.
getActionGroups gtk.action_group.ActionGroup[] getActionGroups(): Returns the list of action groups associated with manager.
getAddTearoffs bool getAddTearoffs(): Returns whether menus generated by this #GtkUIManager will have tearoff menu items.
getToplevels gtk.widget.Widget[] getToplevels(gtk.types.UIManagerItemType types): Obtains a list of all toplevel widgets of the requested types.
getUi string getUi(): Creates a [UI definition][XML-UI] of the merged UI.
getWidget gtk.widget.Widget getWidget(string path): Looks up a widget by following a path. The path consists of the names specified in the XML description of the UI. separated by “/”. Elements which 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.
insertActionGroup void insertActionGroup(gtk.action_group.ActionGroup actionGroup, int pos): Inserts an action group into the list of action groups associated with manager. Actions in earlier groups hide actions with the same name in later groups.
newMergeId uint newMergeId(): Returns an unused merge id, suitable for use with gtk.uimanager.UIManager.addUi.
removeActionGroup void removeActionGroup(gtk.action_group.ActionGroup actionGroup): Removes an action group from the list of action groups associated with manager.
removeUi void removeUi(uint mergeId): Unmerges the part of manager's content identified by merge_id.
self UIManager self(): Returns this, for use in with statements.
setAddTearoffs void setAddTearoffs(bool addTearoffs): Sets the “add_tearoffs” property, which controls whether menus generated by this #GtkUIManager will have tearoff menu items.

Properties

_gType GType _gType [@property getter]
addTearoffs bool addTearoffs [@property getter]: Get addTearoffs property.
addTearoffs bool addTearoffs [@property setter]: Set addTearoffs property.
ui string ui [@property getter]

Static functions

_getGType GType _getGType()
builder UIManagerGidBuilder builder(): Get builder for gtk.uimanager.UIManager

Mixed In Members

From `mixin BuildableT!()`

addChild void addChild(gtk.builder.Builder builder, gobject.object.ObjectWrap child, string type): Adds a child to buildable. type is an optional string describing how the child should be added.
constructChild gobject.object.ObjectWrap constructChild(gtk.builder.Builder builder, string name): Constructs a child of buildable with the name name.
customFinished void customFinished(gtk.builder.Builder builder, gobject.object.ObjectWrap child, string tagname, void* data): This is similar to gtk.buildable.Buildable.parserFinished but is called once for each custom tag handled by the buildable.
customTagStart bool customTagStart(gtk.builder.Builder builder, gobject.object.ObjectWrap child, string tagname, glib.types.MarkupParser parser, void* data): This is called for each unknown element under <child>.
getInternalChild gobject.object.ObjectWrap getInternalChild(gtk.builder.Builder builder, string childname): Get the internal child called childname of the buildable object.
getName string getName(): Gets the name of the buildable object.
parserFinished void parserFinished(gtk.builder.Builder builder): Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk.builder.Builder.addFromFile or gtk.builder.Builder.addFromString is called on a builder.
setBuildableProperty void setBuildableProperty(gtk.builder.Builder builder, string name, gobject.value.Value value): Sets the property name name to value on the buildable object.
setName void setName(string name): Sets the name of the buildable object.

Inherited Members

From ObjectWrap

_setGObject void _setGObject(void* cObj, Flag!"Take" take): Set the GObject of a D ObjectWrap wrapper.
_cPtr void* _cPtr(Flag!"Dup" dup): Get a pointer to the underlying C object.
_ref void* _ref(void* gObj): Calls g_object_ref() on a GObject.
_unref _unref(void* gObj): Calls g_object_unref() on a GObject.
_getGType GType _getGType(): Get the GType of an object.
_gType GType _gType [@property getter]: GObject GType property.
self ObjectWrap self(): Convenience method to return this cast to a type. For use in D with statements.
_getDObject T _getDObject(void* cptr, Flag!"Take" take): Template to get the D object from a C GObject and cast it to the given D object type.
connectSignalClosure gulong connectSignalClosure(string signalDetail, DClosure closure, Flag!"After" after): Connect a D closure to an object signal.
setProperty void setProperty(string propertyName, T val): Template for setting a GObject property.
getProperty T getProperty(string propertyName): Template for getting a GObject property.
compatControl size_t compatControl(size_t what, void* data)
bindProperty gobject.binding.Binding bindProperty(string sourceProperty, gobject.object.ObjectWrap target, string targetProperty, gobject.types.BindingFlags flags): Creates a binding between source_property on source and target_property on target.
bindPropertyFull gobject.binding.Binding bindPropertyFull(string sourceProperty, gobject.object.ObjectWrap target, string targetProperty, gobject.types.BindingFlags flags, gobject.closure.Closure transformTo, gobject.closure.Closure transformFrom): Creates a binding between source_property on source and target_property on target, allowing you to set the transformation functions to be used by the binding.
forceFloating void forceFloating(): This function is intended for #GObject implementations to re-enforce a floating[floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling gobject.object.ObjectWrap.refSink.
freezeNotify void freezeNotify(): Increases the freeze count on object. If the freeze count is non-zero, the emission of "notify" signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one #GObject::notify signal is emitted for each property modified while the object is frozen.
getData void* getData(string key): Gets a named field from the objects table of associations (see gobject.object.ObjectWrap.setData).
getProperty void getProperty(string propertyName, gobject.value.Value value): Gets a property of an object.
getQdata void* getQdata(glib.types.Quark quark): This function gets back user data pointers stored via gobject.object.ObjectWrap.setQdata.
getv void getv(string[] names, gobject.value.Value[] values): Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.
isFloating bool isFloating(): Checks whether object has a floating[floating-ref] reference.
notify void notify(string propertyName): Emits a "notify" signal for the property property_name on object.
notifyByPspec void notifyByPspec(gobject.param_spec.ParamSpec pspec): Emits a "notify" signal for the property specified by pspec on object.
refSink gobject.object.ObjectWrap refSink(): Increase the reference count of object, and possibly remove the floating[floating-ref] reference, if object has a floating reference.
runDispose void runDispose(): Releases all references to other objects. This can be used to break reference cycles.
setData void setData(string key, void* data): Each object carries around a table of associations from strings to pointers. This function lets you set an association.
setProperty void setProperty(string propertyName, gobject.value.Value value): Sets a property on an object.
stealData void* stealData(string key): Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
stealQdata void* stealQdata(glib.types.Quark quark): This function gets back user data pointers stored via gobject.object.ObjectWrap.setQdata and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example:
thawNotify void thawNotify(): Reverts the effect of a previous call to gobject.object.ObjectWrap.freezeNotify. The freeze count is decreased on object and when it reaches zero, queued "notify" signals are emitted.
watchClosure void watchClosure(gobject.closure.Closure closure): This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling gobject.closure.Closure.invalidate on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, gobject.object.ObjectWrap.ref_ and gobject.object.ObjectWrap.unref are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.
connectNotify gulong connectNotify(string detail, T callback, Flag!"After" after): Connect to Notify signal.

From Buildable

_getGType GType _getGType()
addChild void addChild(gtk.builder.Builder builder, gobject.object.ObjectWrap child, string type): Adds a child to buildable. type is an optional string describing how the child should be added.
constructChild gobject.object.ObjectWrap constructChild(gtk.builder.Builder builder, string name): Constructs a child of buildable with the name name.
customFinished void customFinished(gtk.builder.Builder builder, gobject.object.ObjectWrap child, string tagname, void* data): This is similar to gtk.buildable.Buildable.parserFinished but is called once for each custom tag handled by the buildable.
customTagStart bool customTagStart(gtk.builder.Builder builder, gobject.object.ObjectWrap child, string tagname, glib.types.MarkupParser parser, void* data): This is called for each unknown element under <child>.
getInternalChild gobject.object.ObjectWrap getInternalChild(gtk.builder.Builder builder, string childname): Get the internal child called childname of the buildable object.
getName string getName(): Gets the name of the buildable object.
parserFinished void parserFinished(gtk.builder.Builder builder): Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk.builder.Builder.addFromFile or gtk.builder.Builder.addFromString is called on a builder.
setBuildableProperty void setBuildableProperty(gtk.builder.Builder builder, string name, gobject.value.Value value): Sets the property name name to value on the buildable object.
setName void setName(string name): Sets the name of the buildable object.

gtk uimanager classes