gio/gmenumodel.c

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