GMenuModel

This page documents the specification of GMenuModel: which attributes and links are defined and what they mean.

https://developer.gnome.org/gio/unstable/GMenuModel.html#GMenuModel.description is a good resource as well.

If you think you need this format extended, please file a bug against GApplication.

Links

A link on an item in a GMenuModel is a link to another GMenuModel.

Links have a special relationship with the 'action-namespace' attribute. See below.

There are two supported link types: section and submenu. You may not use both on the same item.

Sections

A 'section' link on a GMenuModel includes the contents of another GMenuModel directly into the menu in which the section is defined. This works recursively (so sections may contain sections).

Strictly speaking, there is no relationship between sections and the insertion of separators, but separators are inserted between each toplevel item in a menu, and typically the toplevel items will be sections. This means that nominally, separators are inserted between each non-empty toplevel section in a menu. Separators are not inserted between nested sections.

An item that declares a 'section' link may also define a label attribute which will then be used as a section heading. action-namespace is also supported. Other attributes are not supported on items that define section links (eg: no icons in section headers).

Submenus

A 'submenu' link on a GMenuModel is used on a menu item that represents a submenu. The linked GMenuModel is the contents of the submenu.

When using the 'submenu' link, it may be interesting to use the 'submenu-action' attribute as well (see below).

Attributes

An attribute on an item in a GMenuModel is a named GVariant value.

This is the primary way of defining information about menu items.

There are a number of standard attributes that are supported on menu items. This page is the "official list" but you may define any attributes you like. Implementations may choose to interpret attributes not on this list as they like, but using some sort of "x-corpname-" sort of prefixing for the attribute name is recommended.

label

Type: s

This is the string that is used for the label of the menu item.

icon

Type: any

This is the serialised version of the noun icon used in the menu item.

The value of this attribute is the GVariant that was returned by g_icon_serialize(). The value should be passed directly to g_icon_deserialize() without any other sort of variant wrapping or unwrapping.

action

Type: s

The action attribute is the name of the action that the menu item activates and visualises the state of. In most cases this should be a fully-namespaced action name (such as 'app.quit') but the action-namespace attribute provides another alternative.

This is largely equivalent to the action_name property on GtkActionable

target

Type: any

This is largely equivalent to the action_target property on GtkActionable

accel

Type: s

This is the keyboard accelerator that should be rendered in the accel label of the menu item. It should be a string of the form "F11" or "<Primary>q".

If an accel is given in this way then it will be the accel that is shown. If an accel property equal to the empty string is given then no accel label will be shown.

If no accel property is given then the front-end implementation may use some method of attempting to guess the appropriate label to use based on the action and target.

action-namespace

Type: s

This is the action namespace to apply to all actions mentioned in GMenuModels linked to from this item. For example, if a submenu link existed on an item with the action-namespace attribute of "app" and the submenu had an item with an action attribute of "quit" then the effective action name would be "app.quit".

Action namespaces are properly recursive: if the menu in the example above were further to be referred to from a menuitem that had the action namespace "foo" then the effective action name would be "foo.app.quit".

Note that action-namespace does not apply to actions defined on the menu item itself. If a submenu item has an action-namespace and a submenu-action then the action-namespace is *not* applied to the submenu-action.

submenu-action

Type: s

Defined on submenu items, this attribute names an action used to signal when the menu is shown or not. The named action is in the same namespace as is normal for action attributes and the usual action-namespace rules apply.

The named action should have a boolean state. When the submenu is shown, the front-end will change the boolean state of the action to true. When the menu is hidden again, it will set it to false. The application signals when the menu is ready to be shown by changing the state to true.

This provides a means by which applications that sync the contents of their menus with some external source can turn off the syncing while the menu is closed (a menu listing wifi hotspots, for example).

Front-ends that use this feature should always change the action state to true when a menu is requested to be opened, even if the action state is already true. This avoids races with other (theoretical) consumers of the menu which may just be closing it. Front-ends should also monitor for state changes back to false and force the state back to true in the event that they are still showing the menu. This avoids the menu getting stale if another consumer of the menu closes it.

Applications can use the action in two ways. In the most common case, in response to receiving a state change request to 'true', they can perform some immediate updates (synchronously) and set the state right away and also possibly begin monitoring for changes and updating the content of the menu. On receiving a state change to 'false', they can stop monitoring for and pushing updates. This should cover almost all cases and is the encouraged mode of interaction because it gets the menu on the screen as quickly as possible (even if the contents may be refreshed while it is showing).

Applications that need to perform asynchronous IO in order to determine the set of items visible when the menu is first shown must engage in a much more complicated protocol. This is discouraged, but if it is done it must be done in this way to avoid races. During the time between when the menu is requested shown and when the asynchronous operation completes, the application must count the number of requests to change the state to true and the requests to change the state to false. The asynchronous operation should only be cancelled if an equal number of 'false' requests are received to 'true' requests (ie: all 'true' requests must have been cancelled). This ensures that if two clients request a menu to show at the same time and then one of them cancels the request, the menu will still be shown. Additionally, if starting again to monitor for changes is expensive or if the contents of the menu would be made invalid as a result of the menu being closed, it is recommended that a short timeout is used after publicly changing the state to false before performing 'destructive' operations (~5sec). This gives a second client with an open menu a chance to respond to the state change notification to force the state back to true.

In any case, applications may wish to use a timeout to change the state back to false after some length of time in case a client with an open menu has crashed or otherwise leaked the open state. If the menu is still legitimately open then the consumer will respond by forcing the state back to true again.