gio/gmenumodel.c

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