docs/reference/gio/html/GMenuModel.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>GMenuModel</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="application.html" title="Application support">
   9 <link rel="prev" href="GDBusActionGroup.html" title="GDBusActionGroup">
  10 <link rel="next" href="GMenu.html" title="GMenu">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="GDBusActionGroup.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="application.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GIO Reference Manual</th>
  21 <td><a accesskey="n" href="GMenu.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#GMenuModel.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#GMenuModel.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#GMenuModel.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29                    |
  30                   <a href="#GMenuModel.signals" class="shortcut">Signals</a>
  31 </td></tr>
  32 </table>
  33 <div class="refentry">
  34 <a name="GMenuModel"></a><div class="titlepage"></div>
  35 <div class="refnamediv"><table width="100%"><tr>
  36 <td valign="top">
  37 <h2><span class="refentrytitle"><a name="GMenuModel.top_of_page"></a>GMenuModel</span></h2>
  38 <p>GMenuModel — An abstract class representing the contents of a menu</p>
  39 </td>
  40 <td valign="top" align="right"></td>
  41 </tr></table></div>
  42 <div class="refsynopsisdiv">
  43 <a name="GMenuModel.synopsis"></a><h2>Synopsis</h2>
  44 <a name="GMenuAttributeIter"></a><a name="GMenuLinkIter"></a><pre class="synopsis">                    <a class="link" href="GMenuModel.html#GMenuModel-struct" title="GMenuModel">GMenuModel</a>;
  45 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GMenuModel.html#g-menu-model-is-mutable" title="g_menu_model_is_mutable ()">g_menu_model_is_mutable</a>             (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>);
  46 <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a>                <a class="link" href="GMenuModel.html#g-menu-model-get-n-items" title="g_menu_model_get_n_items ()">g_menu_model_get_n_items</a>            (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>);
  47
  48 #define             <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-ACTION:CAPS" title="G_MENU_ATTRIBUTE_ACTION">G_MENU_ATTRIBUTE_ACTION</a>
  49 #define             <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-LABEL:CAPS" title="G_MENU_ATTRIBUTE_LABEL">G_MENU_ATTRIBUTE_LABEL</a>
  50 #define             <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-TARGET:CAPS" title="G_MENU_ATTRIBUTE_TARGET">G_MENU_ATTRIBUTE_TARGET</a>
  51 #define             <a class="link" href="GMenuModel.html#G-MENU-LINK-SECTION:CAPS" title="G_MENU_LINK_SECTION">G_MENU_LINK_SECTION</a>
  52 #define             <a class="link" href="GMenuModel.html#G-MENU-LINK-SUBMENU:CAPS" title="G_MENU_LINK_SUBMENU">G_MENU_LINK_SUBMENU</a>
  53
  54 <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="GMenuModel.html#g-menu-model-get-item-attribute-value" title="g_menu_model_get_item_attribute_value ()">g_menu_model_get_item_attribute_value</a>
  55                                                         (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
  56                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>,
  57                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *attribute</code></em>,
  58                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-GVariantType.html#GVariantType"><span class="type">GVariantType</span></a> *expected_type</code></em>);
  59 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GMenuModel.html#g-menu-model-get-item-attribute" title="g_menu_model_get_item_attribute ()">g_menu_model_get_item_attribute</a>     (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
  60                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>,
  61                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *attribute</code></em>,
  62                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *format_string</code></em>,
  63                                                          <em class="parameter"><code>...</code></em>);
  64 <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="returnvalue">GMenuModel</span></a> *        <a class="link" href="GMenuModel.html#g-menu-model-get-item-link" title="g_menu_model_get_item_link ()">g_menu_model_get_item_link</a>          (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
  65                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>,
  66                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *link</code></em>);
  67 <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="returnvalue">GMenuAttributeIter</span></a> * <a class="link" href="GMenuModel.html#g-menu-model-iterate-item-attributes" title="g_menu_model_iterate_item_attributes ()">g_menu_model_iterate_item_attributes</a>
  68                                                         (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
  69                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>);
  70 <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="returnvalue">GMenuLinkIter</span></a> *     <a class="link" href="GMenuModel.html#g-menu-model-iterate-item-links" title="g_menu_model_iterate_item_links ()">g_menu_model_iterate_item_links</a>     (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
  71                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>);
  72
  73 <span class="returnvalue">void</span>                <a class="link" href="GMenuModel.html#g-menu-model-items-changed" title="g_menu_model_items_changed ()">g_menu_model_items_changed</a>          (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
  74                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> position</code></em>,
  75                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> removed</code></em>,
  76                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> added</code></em>);
  77
  78 struct              <a class="link" href="GMenuModel.html#GMenuAttributeIter-struct" title="struct GMenuAttributeIter">GMenuAttributeIter</a>;
  79 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-next" title="g_menu_attribute_iter_get_next ()">g_menu_attribute_iter_get_next</a>      (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>,
  80                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **out_name</code></em>,
  81                                                          <em class="parameter"><code><a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> **value</code></em>);
  82 const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-name" title="g_menu_attribute_iter_get_name ()">g_menu_attribute_iter_get_name</a>      (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>);
  83 <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-value" title="g_menu_attribute_iter_get_value ()">g_menu_attribute_iter_get_value</a>     (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>);
  84 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GMenuModel.html#g-menu-attribute-iter-next" title="g_menu_attribute_iter_next ()">g_menu_attribute_iter_next</a>          (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>);
  85
  86 struct              <a class="link" href="GMenuModel.html#GMenuLinkIter-struct" title="struct GMenuLinkIter">GMenuLinkIter</a>;
  87 const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="GMenuModel.html#g-menu-link-iter-get-name" title="g_menu_link_iter_get_name ()">g_menu_link_iter_get_name</a>           (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>);
  88 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GMenuModel.html#g-menu-link-iter-get-next" title="g_menu_link_iter_get_next ()">g_menu_link_iter_get_next</a>           (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>,
  89                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **out_link</code></em>,
  90                                                          <em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> **value</code></em>);
  91 <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="returnvalue">GMenuModel</span></a> *        <a class="link" href="GMenuModel.html#g-menu-link-iter-get-value" title="g_menu_link_iter_get_value ()">g_menu_link_iter_get_value</a>          (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>);
  92 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GMenuModel.html#g-menu-link-iter-next" title="g_menu_link_iter_next ()">g_menu_link_iter_next</a>               (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>);
  93 </pre>
  94 </div>
  95 <div class="refsect1">
  96 <a name="GMenuModel.object-hierarchy"></a><h2>Object Hierarchy</h2>
  97 <pre class="synopsis">
  98   <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
  99    +----GMenuModel
 100          +----<a class="link" href="GDBusMenuModel.html" title="GDBusMenuModel">GDBusMenuModel</a>
 101          +----<a class="link" href="GMenu.html" title="GMenu">GMenu</a>
 102 </pre>
 103 <pre class="synopsis">
 104   <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
 105    +----GMenuAttributeIter
 106 </pre>
 107 <pre class="synopsis">
 108   <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
 109    +----GMenuLinkIter
 110 </pre>
 111 </div>
 112 <div class="refsect1">
 113 <a name="GMenuModel.signals"></a><h2>Signals</h2>
 114 <pre class="synopsis">
 115   "<a class="link" href="GMenuModel.html#GMenuModel-items-changed" title='The "items-changed" signal'>items-changed</a>"                                  : <a href="./../gobject/gobject/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS"><code class="literal">Run Last</code></a>
 116 </pre>
 117 </div>
 118 <div class="refsect1">
 119 <a name="GMenuModel.description"></a><h2>Description</h2>
 120 <p>
 121 <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> represents the contents of a menu -- an ordered list of
 122 menu items. The items are associated with actions, which can be
 123 activated through them. Items can be grouped in sections, and may
 124 have submenus associated with them. Both items and sections usually
 125 have some representation data, such as labels or icons. The type of
 126 the associated action (ie whether it is stateful, and what kind of
 127 state it has) can influence the representation of the item.
 128 </p>
 129 <p>
 130 The conceptual model of menus in <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> is hierarchical:
 131 sections and submenus are again represented by <a href="GMenuModel.html"><span class="type">GMenuModels</span></a>.
 132 Menus themselves do not define their own roles. Rather, the role
 133 of a particular <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> is defined by the item that references
 134 it (or, in the case of the 'root' menu, is defined by the context
 135 in which it is used).
 136 </p>
 137 <p>
 138 As an example, consider the visible portions of the menu in
 139 <a class="xref" href="GMenuModel.html#menu-example" title="Figure 2. An example menu">Figure 2, “An example menu”</a>.
 140 </p>
 141 <p>
 142 </p>
 143 <div class="figure">
 144 <a name="menu-example"></a><p class="title"><b>Figure 2. An example menu</b></p>
 145 <div class="figure-contents"><div><img src="menu-example.png" alt="An example menu"></div></div>
 146 </div>
 147 <p><br class="figure-break">
 148 </p>
 149 <p>
 150 There are 8 "menus" visible in the screenshot: one menubar, two
 151 submenus and 5 sections:
 152 </p>
 153 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 154 <li class="listitem">the toplevel menubar (containing 4 items)</li>
 155 <li class="listitem">the View submenu (containing 3 sections)</li>
 156 <li class="listitem">the first section of the View submenu (containing 2 items)</li>
 157 <li class="listitem">the second section of the View submenu (containing 1 item)</li>
 158 <li class="listitem">the final section of the View submenu (containing 1 item)</li>
 159 <li class="listitem">the Highlight Mode submenu (containing 2 sections)</li>
 160 <li class="listitem">the Sources section (containing 2 items)</li>
 161 <li class="listitem">the Markup section (containing 2 items)</li>
 162 </ul></div>
 163 <p>
 164 </p>
 165 <p>
 166 <a class="xref" href="GMenuModel.html#menu-model" title="Figure 3. A menu model">Figure 3, “A menu model”</a> illustrates the conceptual connection between
 167 these 8 menus. Each large block in the figure represents a menu and the
 168 smaller blocks within the large block represent items in that menu. Some
 169 items contain references to other menus.
 170 </p>
 171 <p>
 172 </p>
 173 <div class="figure">
 174 <a name="menu-model"></a><p class="title"><b>Figure 3. A menu model</b></p>
 175 <div class="figure-contents"><div><img src="menu-model.png" alt="A menu model"></div></div>
 176 </div>
 177 <p><br class="figure-break">
 178 </p>
 179 <p>
 180 Notice that the separators visible in <a class="xref" href="GMenuModel.html#menu-example" title="Figure 2. An example menu">Figure 2, “An example menu”</a>
 181 appear nowhere in <a class="xref" href="GMenuModel.html#menu-model" title="Figure 3. A menu model">Figure 3, “A menu model”</a>. This is because
 182 separators are not explicitly represented in the menu model. Instead,
 183 a separator is inserted between any two non-empty sections of a menu.
 184 Section items can have labels just like any other item. In that case,
 185 a display system may show a section header instead of a separator.
 186 </p>
 187 <p>
 188 The motivation for this abstract model of application controls is
 189 that modern user interfaces tend to make these controls available
 190 outside the application. Examples include global menus, jumplists,
 191 dash boards, etc. To support such uses, it is necessary to 'export'
 192 information about actions and their representation in menus, which
 193 is exactly what the
 194 <a class="link" href="gio-GActionGroup-exporter.html" title="GActionGroup exporter">GActionGroup exporter</a>
 195 and the
 196 <a class="link" href="gio-GMenuModel-exporter.html" title="GMenuModel exporter">GMenuModel exporter</a>
 197 do for <a class="link" href="GActionGroup.html" title="GActionGroup"><span class="type">GActionGroup</span></a> and <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>. The client-side counterparts
 198 to make use of the exported information are <a class="link" href="GDBusActionGroup.html" title="GDBusActionGroup"><span class="type">GDBusActionGroup</span></a> and
 199 <a class="link" href="GDBusMenuModel.html" title="GDBusMenuModel"><span class="type">GDBusMenuModel</span></a>.
 200 </p>
 201 <p>
 202 The API of <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> is very generic, with iterators for the
 203 attributes and links of an item, see <a class="link" href="GMenuModel.html#g-menu-model-iterate-item-attributes" title="g_menu_model_iterate_item_attributes ()"><code class="function">g_menu_model_iterate_item_attributes()</code></a>
 204 and <a class="link" href="GMenuModel.html#g-menu-model-iterate-item-links" title="g_menu_model_iterate_item_links ()"><code class="function">g_menu_model_iterate_item_links()</code></a>. The 'standard' attributes and
 205 link types have predefined names: <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-LABEL:CAPS" title="G_MENU_ATTRIBUTE_LABEL"><code class="literal">G_MENU_ATTRIBUTE_LABEL</code></a>,
 206 <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-ACTION:CAPS" title="G_MENU_ATTRIBUTE_ACTION"><code class="literal">G_MENU_ATTRIBUTE_ACTION</code></a>, <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-TARGET:CAPS" title="G_MENU_ATTRIBUTE_TARGET"><code class="literal">G_MENU_ATTRIBUTE_TARGET</code></a>, <a class="link" href="GMenuModel.html#G-MENU-LINK-SECTION:CAPS" title="G_MENU_LINK_SECTION"><code class="literal">G_MENU_LINK_SECTION</code></a>
 207 and <a class="link" href="GMenuModel.html#G-MENU-LINK-SUBMENU:CAPS" title="G_MENU_LINK_SUBMENU"><code class="literal">G_MENU_LINK_SUBMENU</code></a>.
 208 </p>
 209 <p>
 210 Items in a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> represent active controls if they refer to
 211 an action that can get activated when the user interacts with the
 212 menu item. The reference to the action is encoded by the string id
 213 in the <a class="link" href="GMenuModel.html#G-MENU-ATTRIBUTE-ACTION:CAPS" title="G_MENU_ATTRIBUTE_ACTION"><code class="literal">G_MENU_ATTRIBUTE_ACTION</code></a> attribute. An action id uniquely
 214 identifies an action in an action group. Which action group(s) provide
 215 actions depends on the context in which the menu model is used.
 216 E.g. when the model is exported as the application menu of a
 217 <a href="http://developer.gnome.org/devel/gtk/GtkApplication.html"><span class="type">GtkApplication</span></a>, actions can be application-wide or window-specific
 218 (and thus come from two different action groups). By convention, the
 219 application-wide actions have names that start with "app.", while the
 220 names of window-specific actions start with "win.".
 221 </p>
 222 <p>
 223 While a wide variety of stateful actions is possible, the following
 224 is the minimum that is expected to be supported by all users of exported
 225 menu information:
 226 </p>
 227 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 228 <li class="listitem">an action with no parameter type and no state</li>
 229 <li class="listitem">an action with no parameter type and boolean state</li>
 230 <li class="listitem">an action with string parameter type and string state</li>
 231 </ul></div>
 232 <p>
 233 </p>
 234 <p>
 235 </p>
 236 <p><b>Stateless. </b>
 237 A stateless action typically corresponds to an ordinary menu item.
 238
 239 Selecting such a menu item will activate the action (with no parameter).
 240 </p>
 241 <p>
 242 </p>
 243 <p>
 244 </p>
 245 <p><b>Boolean State. </b>
 246 An action with a boolean state will most typically be used with a "toggle"
 247 or "switch" menu item. The state can be set directly, but activating the
 248 action (with no parameter) results in the state being toggled.
 249
 250 Selecting a toggle menu item will activate the action. The menu item should
 251 be rendered as "checked" when the state is true.
 252 </p>
 253 <p>
 254 </p>
 255 <p>
 256 </p>
 257 <p><b>String Parameter and State. </b>
 258 Actions with string parameters and state will most typically be used to
 259 represent an enumerated choice over the items available for a group of
 260 radio menu items. Activating the action with a string parameter is
 261 equivalent to setting that parameter as the state.
 262
 263 Radio menu items, in addition to being associated with the action, will
 264 have a target value. Selecting that menu item will result in activation
 265 of the action with the target value as the parameter. The menu item should
 266 be rendered as "selected" when the state of the action is equal to the
 267 target value of the menu item.
 268 </p>
 269 <p>
 270 </p>
 271 </div>
 272 <div class="refsect1">
 273 <a name="GMenuModel.details"></a><h2>Details</h2>
 274 <div class="refsect2">
 275 <a name="GMenuModel-struct"></a><h3>GMenuModel</h3>
 276 <pre class="programlisting">typedef struct _GMenuModel GMenuModel;</pre>
 277 <p>
 278 <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> is an opaque structure type.  You must access it using the
 279 functions below.
 280 </p>
 281 <p class="since">Since 2.32</p>
 282 </div>
 283 <hr>
 284 <div class="refsect2">
 285 <a name="g-menu-model-is-mutable"></a><h3>g_menu_model_is_mutable ()</h3>
 286 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_menu_model_is_mutable             (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>);</pre>
 287 <p>
 288 Queries if <em class="parameter"><code>model</code></em> is mutable.
 289 </p>
 290 <p>
 291 An immutable <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> will never emit the <a class="link" href="GMenuModel.html#GMenuModel-items-changed" title='The "items-changed" signal'><span class="type">"items-changed"</span></a>
 292 signal. Consumers of the model may make optimisations accordingly.
 293 </p>
 294 <div class="variablelist"><table border="0">
 295 <col align="left" valign="top">
 296 <tbody>
 297 <tr>
 298 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 299 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 300 </td>
 301 </tr>
 302 <tr>
 303 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 304 <td>
 305 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the model is mutable (ie: "items-changed" may be
 306 emitted).</td>
 307 </tr>
 308 </tbody>
 309 </table></div>
 310 <p class="since">Since 2.32</p>
 311 </div>
 312 <hr>
 313 <div class="refsect2">
 314 <a name="g-menu-model-get-n-items"></a><h3>g_menu_model_get_n_items ()</h3>
 315 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a>                g_menu_model_get_n_items            (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>);</pre>
 316 <p>
 317 Query the number of items in <em class="parameter"><code>model</code></em>.
 318 </p>
 319 <div class="variablelist"><table border="0">
 320 <col align="left" valign="top">
 321 <tbody>
 322 <tr>
 323 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 324 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 325 </td>
 326 </tr>
 327 <tr>
 328 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 329 <td>the number of items</td>
 330 </tr>
 331 </tbody>
 332 </table></div>
 333 <p class="since">Since 2.32</p>
 334 </div>
 335 <hr>
 336 <div class="refsect2">
 337 <a name="G-MENU-ATTRIBUTE-ACTION:CAPS"></a><h3>G_MENU_ATTRIBUTE_ACTION</h3>
 338 <pre class="programlisting">#define G_MENU_ATTRIBUTE_ACTION "action"
 339 </pre>
 340 </div>
 341 <hr>
 342 <div class="refsect2">
 343 <a name="G-MENU-ATTRIBUTE-LABEL:CAPS"></a><h3>G_MENU_ATTRIBUTE_LABEL</h3>
 344 <pre class="programlisting">#define G_MENU_ATTRIBUTE_LABEL "label"
 345 </pre>
 346 </div>
 347 <hr>
 348 <div class="refsect2">
 349 <a name="G-MENU-ATTRIBUTE-TARGET:CAPS"></a><h3>G_MENU_ATTRIBUTE_TARGET</h3>
 350 <pre class="programlisting">#define G_MENU_ATTRIBUTE_TARGET "target"
 351 </pre>
 352 </div>
 353 <hr>
 354 <div class="refsect2">
 355 <a name="G-MENU-LINK-SECTION:CAPS"></a><h3>G_MENU_LINK_SECTION</h3>
 356 <pre class="programlisting">#define G_MENU_LINK_SECTION "section"
 357 </pre>
 358 </div>
 359 <hr>
 360 <div class="refsect2">
 361 <a name="G-MENU-LINK-SUBMENU:CAPS"></a><h3>G_MENU_LINK_SUBMENU</h3>
 362 <pre class="programlisting">#define G_MENU_LINK_SUBMENU "submenu"
 363 </pre>
 364 </div>
 365 <hr>
 366 <div class="refsect2">
 367 <a name="g-menu-model-get-item-attribute-value"></a><h3>g_menu_model_get_item_attribute_value ()</h3>
 368 <pre class="programlisting"><a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="returnvalue">GVariant</span></a> *          g_menu_model_get_item_attribute_value
 369                                                         (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
 370                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>,
 371                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *attribute</code></em>,
 372                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-GVariantType.html#GVariantType"><span class="type">GVariantType</span></a> *expected_type</code></em>);</pre>
 373 <p>
 374 Queries the item at position <em class="parameter"><code>item_index</code></em> in <em class="parameter"><code>model</code></em> for the attribute
 375 specified by <em class="parameter"><code>attribute</code></em>.
 376 </p>
 377 <p>
 378 If <em class="parameter"><code>expected_type</code></em> is non-<a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it specifies the expected type of
 379 the attribute.  If it is <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then any type will be accepted.
 380 </p>
 381 <p>
 382 If the attribute exists and matches <em class="parameter"><code>expected_type</code></em> (or if the
 383 expected type is unspecified) then the value is returned.
 384 </p>
 385 <p>
 386 If the attribute does not exist, or does not match the expected type
 387 then <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> is returned.
 388 </p>
 389 <div class="variablelist"><table border="0">
 390 <col align="left" valign="top">
 391 <tbody>
 392 <tr>
 393 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 394 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 395 </td>
 396 </tr>
 397 <tr>
 398 <td><p><span class="term"><em class="parameter"><code>item_index</code></em> :</span></p></td>
 399 <td>the index of the item</td>
 400 </tr>
 401 <tr>
 402 <td><p><span class="term"><em class="parameter"><code>attribute</code></em> :</span></p></td>
 403 <td>the attribute to query</td>
 404 </tr>
 405 <tr>
 406 <td><p><span class="term"><em class="parameter"><code>expected_type</code></em> :</span></p></td>
 407 <td>the expected type of the attribute, or
 408 <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 409 </td>
 410 </tr>
 411 <tr>
 412 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 413 <td>the value of the attribute. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 414 </td>
 415 </tr>
 416 </tbody>
 417 </table></div>
 418 <p class="since">Since 2.32</p>
 419 </div>
 420 <hr>
 421 <div class="refsect2">
 422 <a name="g-menu-model-get-item-attribute"></a><h3>g_menu_model_get_item_attribute ()</h3>
 423 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_menu_model_get_item_attribute     (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
 424                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>,
 425                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *attribute</code></em>,
 426                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *format_string</code></em>,
 427                                                          <em class="parameter"><code>...</code></em>);</pre>
 428 <p>
 429 Queries item at position <em class="parameter"><code>item_index</code></em> in <em class="parameter"><code>model</code></em> for the attribute
 430 specified by <em class="parameter"><code>attribute</code></em>.
 431 </p>
 432 <p>
 433 If the attribute exists and matches the <a href="./../glib/glib/glib-GVariantType.html#GVariantType"><span class="type">GVariantType</span></a> corresponding
 434 to <em class="parameter"><code>format_string</code></em> then <em class="parameter"><code>format_string</code></em> is used to deconstruct the
 435 value into the positional parameters and <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> is returned.
 436 </p>
 437 <p>
 438 If the attribute does not exist, or it does exist but has the wrong
 439 type, then the positional parameters are ignored and <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> is
 440 returned.
 441 </p>
 442 <div class="variablelist"><table border="0">
 443 <col align="left" valign="top">
 444 <tbody>
 445 <tr>
 446 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 447 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 448 </td>
 449 </tr>
 450 <tr>
 451 <td><p><span class="term"><em class="parameter"><code>item_index</code></em> :</span></p></td>
 452 <td>the index of the item</td>
 453 </tr>
 454 <tr>
 455 <td><p><span class="term"><em class="parameter"><code>attribute</code></em> :</span></p></td>
 456 <td>the attribute to query</td>
 457 </tr>
 458 <tr>
 459 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
 460 <td>a <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> format string</td>
 461 </tr>
 462 <tr>
 463 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 464 <td>positional parameters, as per <em class="parameter"><code>format_string</code></em>
 465 </td>
 466 </tr>
 467 <tr>
 468 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 469 <td>
 470 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the named attribute was found with the expected
 471 type</td>
 472 </tr>
 473 </tbody>
 474 </table></div>
 475 <p class="since">Since 2.32</p>
 476 </div>
 477 <hr>
 478 <div class="refsect2">
 479 <a name="g-menu-model-get-item-link"></a><h3>g_menu_model_get_item_link ()</h3>
 480 <pre class="programlisting"><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="returnvalue">GMenuModel</span></a> *        g_menu_model_get_item_link          (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
 481                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>,
 482                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *link</code></em>);</pre>
 483 <p>
 484 Queries the item at position <em class="parameter"><code>item_index</code></em> in <em class="parameter"><code>model</code></em> for the link
 485 specified by <em class="parameter"><code>link</code></em>.
 486 </p>
 487 <p>
 488 If the link exists, the linked <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> is returned.  If the link
 489 does not exist, <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> is returned.
 490 </p>
 491 <div class="variablelist"><table border="0">
 492 <col align="left" valign="top">
 493 <tbody>
 494 <tr>
 495 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 496 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 497 </td>
 498 </tr>
 499 <tr>
 500 <td><p><span class="term"><em class="parameter"><code>item_index</code></em> :</span></p></td>
 501 <td>the index of the item</td>
 502 </tr>
 503 <tr>
 504 <td><p><span class="term"><em class="parameter"><code>link</code></em> :</span></p></td>
 505 <td>the link to query</td>
 506 </tr>
 507 <tr>
 508 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 509 <td>the linked <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 510 </td>
 511 </tr>
 512 </tbody>
 513 </table></div>
 514 <p class="since">Since 2.32</p>
 515 </div>
 516 <hr>
 517 <div class="refsect2">
 518 <a name="g-menu-model-iterate-item-attributes"></a><h3>g_menu_model_iterate_item_attributes ()</h3>
 519 <pre class="programlisting"><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="returnvalue">GMenuAttributeIter</span></a> * g_menu_model_iterate_item_attributes
 520                                                         (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
 521                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>);</pre>
 522 <p>
 523 Creates a <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> to iterate over the attributes of
 524 the item at position <em class="parameter"><code>item_index</code></em> in <em class="parameter"><code>model</code></em>.
 525 </p>
 526 <p>
 527 You must free the iterator with <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> when you are done.
 528 </p>
 529 <div class="variablelist"><table border="0">
 530 <col align="left" valign="top">
 531 <tbody>
 532 <tr>
 533 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 534 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 535 </td>
 536 </tr>
 537 <tr>
 538 <td><p><span class="term"><em class="parameter"><code>item_index</code></em> :</span></p></td>
 539 <td>the index of the item</td>
 540 </tr>
 541 <tr>
 542 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 543 <td>a new <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 544 </td>
 545 </tr>
 546 </tbody>
 547 </table></div>
 548 <p class="since">Since 2.32</p>
 549 </div>
 550 <hr>
 551 <div class="refsect2">
 552 <a name="g-menu-model-iterate-item-links"></a><h3>g_menu_model_iterate_item_links ()</h3>
 553 <pre class="programlisting"><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="returnvalue">GMenuLinkIter</span></a> *     g_menu_model_iterate_item_links     (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
 554                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> item_index</code></em>);</pre>
 555 <p>
 556 Creates a <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> to iterate over the links of the item at
 557 position <em class="parameter"><code>item_index</code></em> in <em class="parameter"><code>model</code></em>.
 558 </p>
 559 <p>
 560 You must free the iterator with <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> when you are done.
 561 </p>
 562 <div class="variablelist"><table border="0">
 563 <col align="left" valign="top">
 564 <tbody>
 565 <tr>
 566 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 567 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 568 </td>
 569 </tr>
 570 <tr>
 571 <td><p><span class="term"><em class="parameter"><code>item_index</code></em> :</span></p></td>
 572 <td>the index of the item</td>
 573 </tr>
 574 <tr>
 575 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 576 <td>a new <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 577 </td>
 578 </tr>
 579 </tbody>
 580 </table></div>
 581 <p class="since">Since 2.32</p>
 582 </div>
 583 <hr>
 584 <div class="refsect2">
 585 <a name="g-menu-model-items-changed"></a><h3>g_menu_model_items_changed ()</h3>
 586 <pre class="programlisting"><span class="returnvalue">void</span>                g_menu_model_items_changed          (<em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model</code></em>,
 587                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> position</code></em>,
 588                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> removed</code></em>,
 589                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> added</code></em>);</pre>
 590 <p>
 591 Requests emission of the <a class="link" href="GMenuModel.html#GMenuModel-items-changed" title='The "items-changed" signal'><span class="type">"items-changed"</span></a> signal on <em class="parameter"><code>model</code></em>.
 592 </p>
 593 <p>
 594 This function should never be called except by <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 595 subclasses.  Any other calls to this function will very likely lead
 596 to a violation of the interface of the model.
 597 </p>
 598 <p>
 599 The implementation should update its internal representation of the
 600 menu before emitting the signal.  The implementation should further
 601 expect to receive queries about the new state of the menu (and
 602 particularly added menu items) while signal handlers are running.
 603 </p>
 604 <p>
 605 The implementation must dispatch this call directly from a mainloop
 606 entry and not in response to calls -- particularly those from the
 607 <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> API.  Said another way: the menu must not change while
 608 user code is running without returning to the mainloop.
 609 </p>
 610 <div class="variablelist"><table border="0">
 611 <col align="left" valign="top">
 612 <tbody>
 613 <tr>
 614 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 615 <td>a <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 616 </td>
 617 </tr>
 618 <tr>
 619 <td><p><span class="term"><em class="parameter"><code>position</code></em> :</span></p></td>
 620 <td>the position of the change</td>
 621 </tr>
 622 <tr>
 623 <td><p><span class="term"><em class="parameter"><code>removed</code></em> :</span></p></td>
 624 <td>the number of items removed</td>
 625 </tr>
 626 <tr>
 627 <td><p><span class="term"><em class="parameter"><code>added</code></em> :</span></p></td>
 628 <td>the number of items added</td>
 629 </tr>
 630 </tbody>
 631 </table></div>
 632 <p class="since">Since 2.32</p>
 633 </div>
 634 <hr>
 635 <div class="refsect2">
 636 <a name="GMenuAttributeIter-struct"></a><h3>struct GMenuAttributeIter</h3>
 637 <pre class="programlisting">struct GMenuAttributeIter;</pre>
 638 <p>
 639 <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> is an opaque structure type.  You must access it
 640 using the functions below.
 641 </p>
 642 <p class="since">Since 2.32</p>
 643 </div>
 644 <hr>
 645 <div class="refsect2">
 646 <a name="g-menu-attribute-iter-get-next"></a><h3>g_menu_attribute_iter_get_next ()</h3>
 647 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_menu_attribute_iter_get_next      (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>,
 648                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **out_name</code></em>,
 649                                                          <em class="parameter"><code><a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> **value</code></em>);</pre>
 650 <p>
 651 This function combines <a class="link" href="GMenuModel.html#g-menu-attribute-iter-next" title="g_menu_attribute_iter_next ()"><code class="function">g_menu_attribute_iter_next()</code></a> with
 652 <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-name" title="g_menu_attribute_iter_get_name ()"><code class="function">g_menu_attribute_iter_get_name()</code></a> and <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-value" title="g_menu_attribute_iter_get_value ()"><code class="function">g_menu_attribute_iter_get_value()</code></a>.
 653 </p>
 654 <p>
 655 First the iterator is advanced to the next (possibly first) attribute.
 656 If that fails, then <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> is returned and there are no other
 657 effects.
 658 </p>
 659 <p>
 660 If successful, <em class="parameter"><code>name</code></em> and <em class="parameter"><code>value</code></em> are set to the name and value of the
 661 attribute that has just been advanced to.  At this point,
 662 <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-name" title="g_menu_attribute_iter_get_name ()"><code class="function">g_menu_attribute_iter_get_name()</code></a> and <a class="link" href="GMenuModel.html#g-menu-attribute-iter-get-value" title="g_menu_attribute_iter_get_value ()"><code class="function">g_menu_attribute_iter_get_value()</code></a> will
 663 return the same values again.
 664 </p>
 665 <p>
 666 The value returned in <em class="parameter"><code>name</code></em> remains valid for as long as the iterator
 667 remains at the current position.  The value returned in <em class="parameter"><code>value</code></em> must
 668 be unreffed using <a href="./../glib/glib/glib-GVariant.html#g-variant-unref"><code class="function">g_variant_unref()</code></a> when it is no longer in use.
 669 </p>
 670 <div class="variablelist"><table border="0">
 671 <col align="left" valign="top">
 672 <tbody>
 673 <tr>
 674 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 675 <td>a <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a>
 676 </td>
 677 </tr>
 678 <tr>
 679 <td><p><span class="term"><em class="parameter"><code>out_name</code></em> :</span></p></td>
 680 <td>the type of the attribute. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 681 </td>
 682 </tr>
 683 <tr>
 684 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 685 <td>the attribute value. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 686 </td>
 687 </tr>
 688 <tr>
 689 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 690 <td>
 691 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, or <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if there is no additional
 692 attribute</td>
 693 </tr>
 694 </tbody>
 695 </table></div>
 696 <p class="since">Since 2.32</p>
 697 </div>
 698 <hr>
 699 <div class="refsect2">
 700 <a name="g-menu-attribute-iter-get-name"></a><h3>g_menu_attribute_iter_get_name ()</h3>
 701 <pre class="programlisting">const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *       g_menu_attribute_iter_get_name      (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>);</pre>
 702 <p>
 703 Gets the name of the attribute at the current iterator position, as
 704 a string.
 705 </p>
 706 <p>
 707 The iterator is not advanced.
 708 </p>
 709 <div class="variablelist"><table border="0">
 710 <col align="left" valign="top">
 711 <tbody>
 712 <tr>
 713 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 714 <td>a <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a>
 715 </td>
 716 </tr>
 717 <tr>
 718 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 719 <td>the name of the attribute</td>
 720 </tr>
 721 </tbody>
 722 </table></div>
 723 <p class="since">Since 2.32</p>
 724 </div>
 725 <hr>
 726 <div class="refsect2">
 727 <a name="g-menu-attribute-iter-get-value"></a><h3>g_menu_attribute_iter_get_value ()</h3>
 728 <pre class="programlisting"><a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="returnvalue">GVariant</span></a> *          g_menu_attribute_iter_get_value     (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>);</pre>
 729 <p>
 730 Gets the value of the attribute at the current iterator position.
 731 </p>
 732 <p>
 733 The iterator is not advanced.
 734 </p>
 735 <div class="variablelist"><table border="0">
 736 <col align="left" valign="top">
 737 <tbody>
 738 <tr>
 739 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 740 <td>a <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a>
 741 </td>
 742 </tr>
 743 <tr>
 744 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 745 <td>the value of the current attribute. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 746 </td>
 747 </tr>
 748 </tbody>
 749 </table></div>
 750 <p class="since">Since 2.32</p>
 751 </div>
 752 <hr>
 753 <div class="refsect2">
 754 <a name="g-menu-attribute-iter-next"></a><h3>g_menu_attribute_iter_next ()</h3>
 755 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_menu_attribute_iter_next          (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a> *iter</code></em>);</pre>
 756 <p>
 757 Attempts to advance the iterator to the next (possibly first)
 758 attribute.
 759 </p>
 760 <p>
 761 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> is returned on success, or <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if there are no more
 762 attributes.
 763 </p>
 764 <p>
 765 You must call this function when you first acquire the iterator
 766 to advance it to the first attribute (and determine if the first
 767 attribute exists at all).
 768 </p>
 769 <div class="variablelist"><table border="0">
 770 <col align="left" valign="top">
 771 <tbody>
 772 <tr>
 773 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 774 <td>a <a class="link" href="GMenuModel.html#GMenuAttributeIter"><span class="type">GMenuAttributeIter</span></a>
 775 </td>
 776 </tr>
 777 <tr>
 778 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 779 <td>
 780 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, or <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> when there are no more attributes</td>
 781 </tr>
 782 </tbody>
 783 </table></div>
 784 <p class="since">Since 2.32</p>
 785 </div>
 786 <hr>
 787 <div class="refsect2">
 788 <a name="GMenuLinkIter-struct"></a><h3>struct GMenuLinkIter</h3>
 789 <pre class="programlisting">struct GMenuLinkIter;</pre>
 790 <p>
 791 <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> is an opaque structure type.  You must access it using
 792 the functions below.
 793 </p>
 794 <p class="since">Since 2.32</p>
 795 </div>
 796 <hr>
 797 <div class="refsect2">
 798 <a name="g-menu-link-iter-get-name"></a><h3>g_menu_link_iter_get_name ()</h3>
 799 <pre class="programlisting">const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *       g_menu_link_iter_get_name           (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>);</pre>
 800 <p>
 801 Gets the name of the link at the current iterator position.
 802 </p>
 803 <p>
 804 The iterator is not advanced.
 805 </p>
 806 <div class="variablelist"><table border="0">
 807 <col align="left" valign="top">
 808 <tbody>
 809 <tr>
 810 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 811 <td>a <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a>
 812 </td>
 813 </tr>
 814 <tr>
 815 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 816 <td>the type of the link</td>
 817 </tr>
 818 </tbody>
 819 </table></div>
 820 <p class="since">Since 2.32</p>
 821 </div>
 822 <hr>
 823 <div class="refsect2">
 824 <a name="g-menu-link-iter-get-next"></a><h3>g_menu_link_iter_get_next ()</h3>
 825 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_menu_link_iter_get_next           (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>,
 826                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **out_link</code></em>,
 827                                                          <em class="parameter"><code><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> **value</code></em>);</pre>
 828 <p>
 829 This function combines <a class="link" href="GMenuModel.html#g-menu-link-iter-next" title="g_menu_link_iter_next ()"><code class="function">g_menu_link_iter_next()</code></a> with
 830 <a class="link" href="GMenuModel.html#g-menu-link-iter-get-name" title="g_menu_link_iter_get_name ()"><code class="function">g_menu_link_iter_get_name()</code></a> and <a class="link" href="GMenuModel.html#g-menu-link-iter-get-value" title="g_menu_link_iter_get_value ()"><code class="function">g_menu_link_iter_get_value()</code></a>.
 831 </p>
 832 <p>
 833 First the iterator is advanced to the next (possibly first) link.
 834 If that fails, then <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> is returned and there are no other effects.
 835 </p>
 836 <p>
 837 If successful, <em class="parameter"><code>out_link</code></em> and <em class="parameter"><code>value</code></em> are set to the name and <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>
 838 of the link that has just been advanced to.  At this point,
 839 <a class="link" href="GMenuModel.html#g-menu-link-iter-get-name" title="g_menu_link_iter_get_name ()"><code class="function">g_menu_link_iter_get_name()</code></a> and <a class="link" href="GMenuModel.html#g-menu-link-iter-get-value" title="g_menu_link_iter_get_value ()"><code class="function">g_menu_link_iter_get_value()</code></a> will return the
 840 same values again.
 841 </p>
 842 <p>
 843 The value returned in <em class="parameter"><code>out_link</code></em> remains valid for as long as the iterator
 844 remains at the current position.  The value returned in <em class="parameter"><code>value</code></em> must
 845 be unreffed using <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> when it is no longer in use.
 846 </p>
 847 <div class="variablelist"><table border="0">
 848 <col align="left" valign="top">
 849 <tbody>
 850 <tr>
 851 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 852 <td>a <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a>
 853 </td>
 854 </tr>
 855 <tr>
 856 <td><p><span class="term"><em class="parameter"><code>out_link</code></em> :</span></p></td>
 857 <td>the name of the link. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 858 </td>
 859 </tr>
 860 <tr>
 861 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 862 <td>the linked <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a>. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 863 </td>
 864 </tr>
 865 <tr>
 866 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 867 <td>
 868 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, or <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if there is no additional link</td>
 869 </tr>
 870 </tbody>
 871 </table></div>
 872 <p class="since">Since 2.32</p>
 873 </div>
 874 <hr>
 875 <div class="refsect2">
 876 <a name="g-menu-link-iter-get-value"></a><h3>g_menu_link_iter_get_value ()</h3>
 877 <pre class="programlisting"><a class="link" href="GMenuModel.html" title="GMenuModel"><span class="returnvalue">GMenuModel</span></a> *        g_menu_link_iter_get_value          (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>);</pre>
 878 <p>
 879 Gets the linked <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> at the current iterator position.
 880 </p>
 881 <p>
 882 The iterator is not advanced.
 883 </p>
 884 <div class="variablelist"><table border="0">
 885 <col align="left" valign="top">
 886 <tbody>
 887 <tr>
 888 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 889 <td>a <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a>
 890 </td>
 891 </tr>
 892 <tr>
 893 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 894 <td>the <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> that is linked to. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 895 </td>
 896 </tr>
 897 </tbody>
 898 </table></div>
 899 <p class="since">Since 2.32</p>
 900 </div>
 901 <hr>
 902 <div class="refsect2">
 903 <a name="g-menu-link-iter-next"></a><h3>g_menu_link_iter_next ()</h3>
 904 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_menu_link_iter_next               (<em class="parameter"><code><a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a> *iter</code></em>);</pre>
 905 <p>
 906 Attempts to advance the iterator to the next (possibly first)
 907 link.
 908 </p>
 909 <p>
 910 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> is returned on success, or <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if there are no more links.
 911 </p>
 912 <p>
 913 You must call this function when you first acquire the iterator to
 914 advance it to the first link (and determine if the first link exists
 915 at all).
 916 </p>
 917 <div class="variablelist"><table border="0">
 918 <col align="left" valign="top">
 919 <tbody>
 920 <tr>
 921 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
 922 <td>a <a class="link" href="GMenuModel.html#GMenuLinkIter"><span class="type">GMenuLinkIter</span></a>
 923 </td>
 924 </tr>
 925 <tr>
 926 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 927 <td>
 928 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, or <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> when there are no more links</td>
 929 </tr>
 930 </tbody>
 931 </table></div>
 932 <p class="since">Since 2.32</p>
 933 </div>
 934 </div>
 935 <div class="refsect1">
 936 <a name="GMenuModel.signal-details"></a><h2>Signal Details</h2>
 937 <div class="refsect2">
 938 <a name="GMenuModel-items-changed"></a><h3>The <code class="literal">"items-changed"</code> signal</h3>
 939 <pre class="programlisting"><span class="returnvalue">void</span>                user_function                      (<a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> *model,
 940                                                         <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a>        position,
 941                                                         <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a>        removed,
 942                                                         <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a>        added,
 943                                                         <a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>    user_data)      : <a href="./../gobject/gobject/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS"><code class="literal">Run Last</code></a></pre>
 944 <p>
 945 Emitted when a change has occured to the menu.
 946 </p>
 947 <p>
 948 The only changes that can occur to a menu is that items are removed
 949 or added.  Items may not change (except by being removed and added
 950 back in the same location).  This signal is capable of describing
 951 both of those changes (at the same time).
 952 </p>
 953 <p>
 954 The signal means that starting at the index <em class="parameter"><code>position</code></em>, <em class="parameter"><code>removed</code></em>
 955 items were removed and <em class="parameter"><code>added</code></em> items were added in their place.  If
 956 <em class="parameter"><code>removed</code></em> is zero then only items were added.  If <em class="parameter"><code>added</code></em> is zero
 957 then only items were removed.
 958 </p>
 959 <p>
 960 As an example, if the menu contains items a, b, c, d (in that
 961 order) and the signal (2, 1, 3) occurs then the new composition of
 962 the menu will be a, b, _, _, _, d (with each _ representing some
 963 new item).
 964 </p>
 965 <p>
 966 Signal handlers may query the model (particularly the added items)
 967 and expect to see the results of the modification that is being
 968 reported.  The signal is emitted after the modification.
 969 </p>
 970 <div class="variablelist"><table border="0">
 971 <col align="left" valign="top">
 972 <tbody>
 973 <tr>
 974 <td><p><span class="term"><em class="parameter"><code>model</code></em> :</span></p></td>
 975 <td>the <a class="link" href="GMenuModel.html" title="GMenuModel"><span class="type">GMenuModel</span></a> that is changing</td>
 976 </tr>
 977 <tr>
 978 <td><p><span class="term"><em class="parameter"><code>position</code></em> :</span></p></td>
 979 <td>the position of the change</td>
 980 </tr>
 981 <tr>
 982 <td><p><span class="term"><em class="parameter"><code>removed</code></em> :</span></p></td>
 983 <td>the number of items removed</td>
 984 </tr>
 985 <tr>
 986 <td><p><span class="term"><em class="parameter"><code>added</code></em> :</span></p></td>
 987 <td>the number of items added</td>
 988 </tr>
 989 <tr>
 990 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 991 <td>user data set when the signal handler was connected.</td>
 992 </tr>
 993 </tbody>
 994 </table></div>
 995 </div>
 996 </div>
 997 <div class="refsect1">
 998 <a name="GMenuModel.see-also"></a><h2>See Also</h2>
 999 <a class="link" href="GActionGroup.html" title="GActionGroup"><span class="type">GActionGroup</span></a>
1000 </div>
1001 </div>
1002 <div class="footer">
1003 <hr>
1004           Generated by GTK-Doc V1.18</div>
1005 </body>
1006 </html>