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