MenuModel

gio.menu_model.MenuModel represents the contents of a menu — an ordered list of menu items. The items are associated with actions, which can be activated through them. Items can be grouped in sections, and may have submenus associated with them. Both items and sections usually have some representation data, such as labels or icons. The type of the associated action (ie whether it is stateful, and what kind of state it has) can influence the representation of the item.

The conceptual model of menus in gio.menu_model.MenuModel is hierarchical: sections and submenus are again represented by gio.menu_model.MenuModels. Menus themselves do not define their own roles. Rather, the role of a particular gio.menu_model.MenuModel is defined by the item that references it (or, in the case of the ‘root’ menu, is defined by the context in which it is used).

As an example, consider the visible portions of this menu:

An example menu

There are 8 ‘menus’ visible in the screenshot: one menubar, two submenus and 5 sections:

the toplevel menubar (containing 4 items)
the View submenu (containing 3 sections)
the first section of the View submenu (containing 2 items)
the second section of the View submenu (containing 1 item)
the final section of the View submenu (containing 1 item)
the Highlight Mode submenu (containing 2 sections)
the Sources section (containing 2 items)
the Markup section (containing 2 items)

The example illustrates the conceptual connection between these 8 menus. Each large block in the figure represents a menu and the smaller blocks within the large block represent items in that menu. Some items contain references to other menus.

A menu example

Notice that the separators visible in the example appear nowhere in the menu model. This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, a display system may show a section header instead of a separator.

The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, dash boards, etc. To support such uses, it is necessary to ‘export’ information about actions and their representation in menus, which is exactly what the action group exporter and the menu model exporter do for gio.action_group.ActionGroup and gio.menu_model.MenuModel. The client-side counterparts to make use of the exported information are gio.dbus_action_group.DBusActionGroup and gio.dbus_menu_model.DBusMenuModel.

The API of gio.menu_model.MenuModel is very generic, with iterators for the attributes and links of an item, see gio.menu_model.MenuModel.iterateItemAttributes and gio.menu_model.MenuModel.iterateItemLinks. The ‘standard’ attributes and link types have predefined names: G_MENU_ATTRIBUTE_LABEL, G_MENU_ATTRIBUTE_ACTION, G_MENU_ATTRIBUTE_TARGET, G_MENU_LINK_SECTION and G_MENU_LINK_SUBMENU.

Items in a gio.menu_model.MenuModel represent active controls if they refer to an action that can get activated when the user interacts with the menu item. The reference to the action is encoded by the string ID in the G_MENU_ATTRIBUTE_ACTION attribute. An action ID uniquely identifies an action in an action group. Which action group(s) provide actions depends on the context in which the menu model is used. E.g. when the model is exported as the application menu of a [gtk.application.Application], actions can be application-wide or window-specific (and thus come from two different action groups). By convention, the application-wide actions have names that start with app., while the names of window-specific actions start with win..

While a wide variety of stateful actions is possible, the following is the minimum that is expected to be supported by all users of exported menu information:

an action with no parameter type and no state
an action with no parameter type and boolean state
an action with string parameter type and string state

Stateless

A stateless action typically corresponds to an ordinary menu item.

Selecting such a menu item will activate the action (with no parameter).

Boolean State

An action with a boolean state will most typically be used with a ‘toggle’ or ‘switch’ menu item. The state can be set directly, but activating the action (with no parameter) results in the state being toggled.

Selecting a toggle menu item will activate the action. The menu item should be rendered as ‘checked’ when the state is true.

String Parameter and State

Actions with string parameters and state will most typically be used to represent an enumerated choice over the items available for a group of radio menu items. Activating the action with a string parameter is equivalent to setting that parameter as the state.

Radio menu items, in addition to being associated with the action, will have a target value. Selecting that menu item will result in activation of the action with the target value as the parameter. The menu item should be rendered as ‘selected’ when the state of the action is equal to the target value of the menu item.

class MenuModel : ObjectG {

glib.variant.VariantG getItemAttributeValue(int itemIndex, string attribute, glib.variant_type.VariantType expectedType);

gio.menu_model.MenuModel getItemLink(int itemIndex, string link);

int getNItems();

bool isMutable();

void itemsChanged(int position, int removed, int added);

gio.menu_attribute_iter.MenuAttributeIter iterateItemAttributes(int itemIndex);

gio.menu_link_iter.MenuLinkIter iterateItemLinks(int itemIndex);

ulong connectItemsChanged(T callback, Flag!"After" after);

}

Members

Functions

connectItemsChanged ulong connectItemsChanged(T callback, Flag!"After" after): Connect to ItemsChanged signal.
getItemAttributeValue glib.variant.VariantG getItemAttributeValue(int itemIndex, string attribute, glib.variant_type.VariantType expectedType): Queries the item at position item_index in model for the attribute specified by attribute.
getItemLink gio.menu_model.MenuModel getItemLink(int itemIndex, string link): Queries the item at position item_index in model for the link specified by link.
getNItems int getNItems(): Query the number of items in model.
isMutable bool isMutable(): Queries if model is mutable.
itemsChanged void itemsChanged(int position, int removed, int added): Requests emission of the #GMenuModel::items-changed signal on model.
iterateItemAttributes gio.menu_attribute_iter.MenuAttributeIter iterateItemAttributes(int itemIndex): Creates a #GMenuAttributeIter to iterate over the attributes of the item at position item_index in model.
iterateItemLinks gio.menu_link_iter.MenuLinkIter iterateItemLinks(int itemIndex): Creates a #GMenuLinkIter to iterate over the links of the item at position item_index in model.

Inherited Members

From ObjectG

setGObject void setGObject(void* cObj, Flag!"Take" take): Set the GObject of a D ObjectG 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.
getType GType getType(): Get the GType of an object.
gType GType gType [@property getter]: GObject GType property.
self ObjectG 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 ulong 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.ObjectG 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.ObjectG 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.ObjectG.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.ObjectG.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.ObjectG.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.ObjectG 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.ObjectG.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.ObjectG.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.ObjectG.ref_ and gobject.object.ObjectG.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 ulong connectNotify(string detail, T callback, Flag!"After" after): Connect to Notify signal.

gio menu_model classes

MenuModel