luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GMenuModel SECTION

Browse Source 
Move it to the struct docs.

Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-10-23 13:42:33 +01:00
parent 5ce7e8c4f9
commit c5fb817b02
1 changed files with 35 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
gio/gmenumodel.c
View File

@ -27,13 +27,9 @@
#include "gmarshal-internal.h"
/**
* SECTION:gmenumodel
* @title: GMenuModel
* @short_description: An abstract class representing the contents of a menu
* @include: gio/gio.h
* @see_also: #GActionGroup
* GMenuModel:
*
* #GMenuModel represents the contents of a menu -- an ordered list of
* `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
@ -41,20 +37,20 @@
* 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.
* The conceptual model of menus in `GMenuModel` is hierarchical:
* sections and submenus are again represented by `GMenuModel`s.
* 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
* 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 # {#menu-example}
* ## An example menu
*
* ![](menu-example.png)
*
* There are 8 "menus" visible in the screenshot: one menubar, two
* There are 8 ‘menus’ visible in the screenshot: one menubar, two
* submenus and 5 sections:
*
* - the toplevel menubar (containing 4 items)
@ -66,17 +62,17 @@
* - the Sources section (containing 2 items)
* - the Markup section (containing 2 items)
*
* The [example][menu-model] illustrates the conceptual connection between
* The [example](#a-menu-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 # {#menu-model}
* ## A menu example
*
* ![](menu-model.png)
*
* Notice that the separators visible in the [example][menu-example]
* appear nowhere in the [menu model][menu-model]. This is because
* Notice that the separators visible in the [example](#an-example-menu)
* appear nowhere in the [menu model](#a-menu-example). 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,
@ -85,32 +81,32 @@
* 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'
* 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 [GActionGroup exporter][gio-GActionGroup-exporter]
* and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
* #GActionGroup and #GMenuModel. The client-side counterparts to
* make use of the exported information are #GDBusActionGroup and
* #GDBusMenuModel.
* is exactly what the action group exporter and the menu model exporter do for
* [iface@Gio.ActionGroup] and [class@Gio.MenuModel]. The client-side
* counterparts to make use of the exported information are
* [class@Gio.DBusActionGroup] and [class@Gio.DBusMenuModel].
*
* The API of #GMenuModel is very generic, with iterators for the
* attributes and links of an item, see g_menu_model_iterate_item_attributes()
* and g_menu_model_iterate_item_links(). 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.
* The API of `GMenuModel` is very generic, with iterators for the
* attributes and links of an item, see
* [method@Gio.MenuModel.iterate_item_attributes] and
* [method@Gio.MenuModel.iterate_item_links]. 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
* 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
* 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
* [class@Gtk.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.".
* 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
@ -119,7 +115,7 @@
* - an action with no parameter type and boolean state
* - an action with string parameter type and string state
*
* ## Stateless
* ## Stateless
*
* A stateless action typically corresponds to an ordinary menu item.
*
@ -127,12 +123,12 @@
*
* ## 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
* 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.
* be rendered as ‘checked’ when the state is true.
*
* ## String Parameter and State
*
@ -144,15 +140,8 @@
* 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
* be rendered as ‘selected’ when the state of the action is equal to the
* target value of the menu item.
*/
/**
* GMenuModel:
*
* #GMenuModel is an opaque structure type. You must access it using the
* functions below.
*
* Since: 2.32
*/