Class MenuModel

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.MenuModel

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

DBusMenuModel, Menu, MenuModel.MenuModel$Impl

@Generated("org.javagi.JavaGI")
public abstract class MenuModel
extends GObject

GMenuModel 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 GMenuModel is hierarchical: sections and submenus are again represented by GMenuModels. Menus themselves do not define their own roles. Rather, the role of a particular GMenuModel 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

!Gio.ActionGroup and MenuModel. The client-side counterparts to make use of the exported information are DBusActionGroup and DBusMenuModel.

The API of GMenuModel is very generic, with iterators for the attributes and links of an item, see iterateItemAttributes(int) and iterateItemLinks(int). 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 GMenuModel 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 GtkApplication, 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.

Since:

2.32

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MenuModel.Builder<B extends MenuModel.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	MenuModel.ItemsChangedCallback	Functional interface declaration of the ItemsChangedCallback callback.
static class	MenuModel.MenuModel$Impl	The MenuModel$Impl type represents a native instance of the abstract MenuModel class.
static class	MenuModel.MenuModelClass

Nested classes/interfaces inherited from class GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
MenuModel()	Create a new MenuModel.
MenuModel(MemorySegment address)	Create a MenuModel instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected MenuModel	asParent()	Return this instance as if it were its parent type.
void	emitItemsChanged(int position, int removed, int added)	Emits the "items-changed" signal.
boolean	getItemAttribute(int itemIndex, String attribute, String formatString, Object... varargs)	Queries item at position itemIndex in this MenuModel for the attribute specified by attribute.
protected void	getItemAttributes(int itemIndex, Out<HashTable<String,Variant>> attributes)	Gets all the attributes associated with the item in the menu model.
@Nullable Variant	getItemAttributeValue(int itemIndex, String attribute, @Nullable VariantType expectedType)	Queries the item at position itemIndex in this MenuModel for the attribute specified by attribute.
@Nullable MenuModel	getItemLink(int itemIndex, String link)	Queries the item at position itemIndex in this MenuModel for the link specified by link.
protected void	getItemLinks(int itemIndex, Out<HashTable<String, MenuModel>> links)	Gets all the links associated with the item in the menu model.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
int	getNItems()	Query the number of items in model.
static @Nullable Type	getType()	Get the GType of the MenuModel class.
boolean	isMutable()	Queries if this MenuModel is mutable.
void	itemsChanged(int position, int removed, int added)	Requests emission of the GMenuModel::items-changed signal on model.
MenuAttributeIter	iterateItemAttributes(int itemIndex)	Creates a GMenuAttributeIter to iterate over the attributes of the item at position itemIndex in model.
MenuLinkIter	iterateItemLinks(int itemIndex)	Creates a GMenuLinkIter to iterate over the links of the item at position itemIndex in model.
SignalConnection<MenuModel.ItemsChangedCallback>	onItemsChanged(MenuModel.ItemsChangedCallback handler)	Emitted when a change has occurred to the menu.

Methods inherited from class GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, builder, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MenuModel

public MenuModel(MemorySegment address)

Create a MenuModel instance for the provided memory address.

Parameters:

address - the memory address of the native object

MenuModel

public MenuModel()

Create a new MenuModel.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the MenuModel class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected MenuModel asParent()

Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.

Overrides:

asParent in class GObject

Returns:

the instance as if it were its parent type

getItemAttribute

public boolean getItemAttribute(int itemIndex,
 String attribute,
 String formatString,
 Object... varargs)

Queries item at position itemIndex in this MenuModel for the attribute specified by attribute.

If the attribute exists and matches the GVariantType corresponding to formatString then formatString is used to deconstruct the value into the positional parameters and true is returned.

If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and false is returned.

This function is a mix of g_menu_model_get_item_attribute_value() and g_variant_get(), followed by a g_variant_unref(). As such, formatString must make a complete copy of the data (since the GVariant may go away after the call to g_variant_unref()). In particular, no '&' characters are allowed in formatString.

Parameters:

itemIndex - the index of the item

attribute - the attribute to query

formatString - a GVariant format string

varargs - positional parameters, as per formatString

Returns:

true if the named attribute was found with the expected type

Since:

2.32

getItemAttributeValue

public @Nullable Variant getItemAttributeValue(int itemIndex,
 String attribute,
 @Nullable VariantType expectedType)

Queries the item at position itemIndex in this MenuModel for the attribute specified by attribute.

If expectedType is non-null then it specifies the expected type of the attribute. If it is null then any type will be accepted.

If the attribute exists and matches expectedType (or if the expected type is unspecified) then the value is returned.

If the attribute does not exist, or does not match the expected type then null is returned.

Parameters:

itemIndex - the index of the item

attribute - the attribute to query

expectedType - the expected type of the attribute, or null

Returns:

the value of the attribute

Since:

2.32

getItemLink

public @Nullable MenuModel getItemLink(int itemIndex,
 String link)

Queries the item at position itemIndex in this MenuModel for the link specified by link.

If the link exists, the linked GMenuModel is returned. If the link does not exist, null is returned.

Parameters:

itemIndex - the index of the item

link - the link to query

Returns:

the linked GMenuModel, or null

Since:

2.32

getNItems

public int getNItems()

Query the number of items in model.

Returns:

the number of items

Since:

2.32

isMutable

public boolean isMutable()

Queries if this MenuModel is mutable.

An immutable GMenuModel will never emit the GMenuModel::items-changed signal. Consumers of the model may make optimisations accordingly.

Returns:

true if the model is mutable (ie: "items-changed" may be emitted).

Since:

2.32

itemsChanged

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

Requests emission of the GMenuModel::items-changed signal on model.

This function should never be called except by GMenuModel subclasses. Any other calls to this function will very likely lead to a violation of the interface of the model.

The implementation should update its internal representation of the menu before emitting the signal. The implementation should further expect to receive queries about the new state of the menu (and particularly added menu items) while signal handlers are running.

The implementation must dispatch this call directly from a mainloop entry and not in response to calls -- particularly those from the GMenuModel API. Said another way: the menu must not change while user code is running without returning to the mainloop.

Parameters:

position - the position of the change

removed - the number of items removed

added - the number of items added

Since:

2.32

iterateItemAttributes

public MenuAttributeIter iterateItemAttributes(int itemIndex)

Creates a GMenuAttributeIter to iterate over the attributes of the item at position itemIndex in model.

You must free the iterator with g_object_unref() when you are done.

Parameters:

itemIndex - the index of the item

Returns:

a new GMenuAttributeIter

Since:

2.32

iterateItemLinks

public MenuLinkIter iterateItemLinks(int itemIndex)

Creates a GMenuLinkIter to iterate over the links of the item at position itemIndex in model.

You must free the iterator with g_object_unref() when you are done.

Parameters:

itemIndex - the index of the item

Returns:

a new GMenuLinkIter

Since:

2.32

getItemAttributes

protected void getItemAttributes(int itemIndex,
 Out<HashTable<String,Variant>> attributes)

Gets all the attributes associated with the item in the menu model.

Parameters:

itemIndex - The GMenuItem to query

attributes - Attributes on the item

getItemLinks

protected void getItemLinks(int itemIndex,
 Out<HashTable<String, MenuModel>> links)

Gets all the links associated with the item in the menu model.

Parameters:

itemIndex - The GMenuItem to query

links - Links from the item

onItemsChanged

public SignalConnection<MenuModel.ItemsChangedCallback> onItemsChanged(MenuModel.ItemsChangedCallback handler)

Emitted when a change has occurred to the menu.

The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added back in the same location). This signal is capable of describing both of those changes (at the same time).

The signal means that starting at the index position, removed items were removed and added items were added in their place. If removed is zero then only items were added. If added is zero then only items were removed.

As an example, if the menu contains items a, b, c, d (in that order) and the signal (2, 1, 3) occurs then the new composition of the menu will be a, b, \, \, \_, d (with each _ representing some new item).

Signal handlers may query the model (particularly the added items) and expect to see the results of the modification that is being reported. The signal is emitted after the modification.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• MenuModel.ItemsChangedCallback.run(int, int, int)

emitItemsChanged

public void emitItemsChanged(int position,
 int removed,
 int added)

Emits the "items-changed" signal. See onItemsChanged(MenuModel.ItemsChangedCallback).