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
 159 /**
 160  * GMenuAttributeIter:
 161  *
 162  * #GMenuAttributeIter is an opaque structure type.  You must access it
 163  * using the functions below.
 164  **/
 165
 166 /**
 167  * GMenuLinkIter:
 168  *
 169  * #GMenuLinkIter is an opaque structure type.  You must access it using
 170  * the functions below.
 171  **/
 172
 173 typedef struct
 174 {
 175   GMenuLinkIter parent_instance;
 176   GHashTableIter iter;
 177   GHashTable *table;
 178 } GMenuLinkHashIter;
 179
 180 typedef GMenuLinkIterClass GMenuLinkHashIterClass;
 181
 182 G_DEFINE_TYPE (GMenuLinkHashIter, g_menu_link_hash_iter, G_TYPE_MENU_LINK_ITER)
 183
 184 static gboolean
 185 g_menu_link_hash_iter_get_next (GMenuLinkIter  *link_iter,
 186                                 const gchar   **out_name,
 187                                 GMenuModel    **value)
 188 {
 189   GMenuLinkHashIter *iter = (GMenuLinkHashIter *) link_iter;
 190   gpointer keyptr, valueptr;
 191
 192   if (!g_hash_table_iter_next (&iter->iter, &keyptr, &valueptr))
 193     return FALSE;
 194
 195   *out_name = keyptr;
 196   *value = g_object_ref (valueptr);
 197
 198   return TRUE;
 199 }
 200
 201 static void
 202 g_menu_link_hash_iter_finalize (GObject *object)
 203 {
 204   GMenuLinkHashIter *iter = (GMenuLinkHashIter *) object;
 205
 206   g_hash_table_unref (iter->table);
 207
 208   G_OBJECT_CLASS (g_menu_link_hash_iter_parent_class)
 209     ->finalize (object);
 210 }
 211
 212 static void
 213 g_menu_link_hash_iter_init (GMenuLinkHashIter *iter)
 214 {
 215 }
 216
 217 static void
 218 g_menu_link_hash_iter_class_init (GMenuLinkHashIterClass *class)
 219 {
 220   GObjectClass *object_class = G_OBJECT_CLASS (class);
 221
 222   object_class->finalize = g_menu_link_hash_iter_finalize;
 223   class->get_next = g_menu_link_hash_iter_get_next;
 224 }
 225
 226
 227 typedef struct
 228 {
 229   GMenuAttributeIter parent_instance;
 230   GHashTableIter iter;
 231   GHashTable *table;
 232 } GMenuAttributeHashIter;
 233
 234 typedef GMenuAttributeIterClass GMenuAttributeHashIterClass;
 235
 236 G_DEFINE_TYPE (GMenuAttributeHashIter, g_menu_attribute_hash_iter, G_TYPE_MENU_ATTRIBUTE_ITER)
 237
 238 static gboolean
 239 g_menu_attribute_hash_iter_get_next (GMenuAttributeIter  *attr_iter,
 240                                      const gchar        **name,
 241                                      GVariant           **value)
 242 {
 243   GMenuAttributeHashIter *iter = (GMenuAttributeHashIter *) attr_iter;
 244   gpointer keyptr, valueptr;
 245
 246   if (!g_hash_table_iter_next (&iter->iter, &keyptr, &valueptr))
 247     return FALSE;
 248
 249   *name = keyptr;
 250
 251   *value = g_variant_ref (valueptr);
 252
 253   return TRUE;
 254 }
 255
 256 static void
 257 g_menu_attribute_hash_iter_finalize (GObject *object)
 258 {
 259   GMenuAttributeHashIter *iter = (GMenuAttributeHashIter *) object;
 260
 261   g_hash_table_unref (iter->table);
 262
 263   G_OBJECT_CLASS (g_menu_attribute_hash_iter_parent_class)
 264     ->finalize (object);
 265 }
 266
 267 static void
 268 g_menu_attribute_hash_iter_init (GMenuAttributeHashIter *iter)
 269 {
 270 }
 271
 272 static void
 273 g_menu_attribute_hash_iter_class_init (GMenuAttributeHashIterClass *class)
 274 {
 275   GObjectClass *object_class = G_OBJECT_CLASS (class);
 276
 277   object_class->finalize = g_menu_attribute_hash_iter_finalize;
 278   class->get_next = g_menu_attribute_hash_iter_get_next;
 279 }
 280
 281 G_DEFINE_ABSTRACT_TYPE (GMenuModel, g_menu_model, G_TYPE_OBJECT)
 282
 283
 284 guint g_menu_model_items_changed_signal;
 285
 286 static GMenuAttributeIter *
 287 g_menu_model_real_iterate_item_attributes (GMenuModel *model,
 288                                            gint        item_index)
 289 {
 290   GHashTable *table = NULL;
 291   GMenuAttributeIter *result;
 292
 293   G_MENU_MODEL_GET_CLASS (model)->get_item_attributes (model, item_index, &table);
 294
 295   if (table)
 296     {
 297       GMenuAttributeHashIter *iter = g_object_new (g_menu_attribute_hash_iter_get_type (), NULL);
 298       g_hash_table_iter_init (&iter->iter, table);
 299       iter->table = g_hash_table_ref (table);
 300       result = G_MENU_ATTRIBUTE_ITER (iter);
 301     }
 302   else
 303     {
 304       g_critical ("GMenuModel implementation '%s' doesn't override iterate_item_attributes() "
 305                   "and fails to return sane values from get_item_attributes()",
 306                   G_OBJECT_TYPE_NAME (model));
 307       result = NULL;
 308     }
 309
 310   if (table != NULL)
 311     g_hash_table_unref (table);
 312
 313   return result;
 314 }
 315
 316 static GVariant *
 317 g_menu_model_real_get_item_attribute_value (GMenuModel         *model,
 318                                             gint                item_index,
 319                                             const gchar        *attribute,
 320                                             const GVariantType *expected_type)
 321 {
 322   GHashTable *table = NULL;
 323   GVariant *value = NULL;
 324
 325   G_MENU_MODEL_GET_CLASS (model)
 326     ->get_item_attributes (model, item_index, &table);
 327
 328   if (table != NULL)
 329     {
 330       value = g_hash_table_lookup (table, attribute);
 331
 332       if (value != NULL)
 333         {
 334           if (expected_type == NULL || g_variant_is_of_type (value, expected_type))
 335             value = g_variant_ref (value);
 336           else
 337             value = NULL;
 338         }
 339     }
 340   else
 341     g_assert_not_reached ();
 342
 343   if (table != NULL)
 344     g_hash_table_unref (table);
 345
 346   return value;
 347 }
 348
 349 static GMenuLinkIter *
 350 g_menu_model_real_iterate_item_links (GMenuModel *model,
 351                                       gint        item_index)
 352 {
 353   GHashTable *table = NULL;
 354   GMenuLinkIter *result;
 355
 356   G_MENU_MODEL_GET_CLASS (model)
 357     ->get_item_links (model, item_index, &table);
 358
 359   if (table)
 360     {
 361       GMenuLinkHashIter *iter = g_object_new (g_menu_link_hash_iter_get_type (), NULL);
 362       g_hash_table_iter_init (&iter->iter, table);
 363       iter->table = g_hash_table_ref (table);
 364       result = G_MENU_LINK_ITER (iter);
 365     }
 366   else
 367     {
 368       g_critical ("GMenuModel implementation '%s' doesn't override iterate_item_links() "
 369                   "and fails to return sane values from get_item_links()",
 370                   G_OBJECT_TYPE_NAME (model));
 371       result = NULL;
 372     }
 373
 374   if (table != NULL)
 375     g_hash_table_unref (table);
 376
 377   return result;
 378 }
 379
 380 static GMenuModel *
 381 g_menu_model_real_get_item_link (GMenuModel  *model,
 382                                  gint         item_index,
 383                                  const gchar *link)
 384 {
 385   GHashTable *table = NULL;
 386   GMenuModel *value = NULL;
 387
 388   G_MENU_MODEL_GET_CLASS (model)
 389     ->get_item_links (model, item_index, &table);
 390
 391   if (table != NULL)
 392     value = g_hash_table_lookup (table, link);
 393   else
 394     g_assert_not_reached ();
 395
 396   if (value != NULL)
 397     g_object_ref (value);
 398
 399   if (table != NULL)
 400     g_hash_table_unref (table);
 401
 402   return value;
 403 }
 404
 405 static void
 406 g_menu_model_init (GMenuModel *model)
 407 {
 408 }
 409
 410 static void
 411 g_menu_model_class_init (GMenuModelClass *class)
 412 {
 413   class->iterate_item_attributes = g_menu_model_real_iterate_item_attributes;
 414   class->get_item_attribute_value = g_menu_model_real_get_item_attribute_value;
 415   class->iterate_item_links = g_menu_model_real_iterate_item_links;
 416   class->get_item_link = g_menu_model_real_get_item_link;
 417
 418   /**
 419    * GMenuModel::items-changed:
 420    * @model: the #GMenuModel that is changing
 421    * @position: the position of the change
 422    * @removed: the number of items removed
 423    * @added: the number of items added
 424    *
 425    * Emitted when a change has occured to the menu.
 426    *
 427    * The only changes that can occur to a menu is that items are removed
 428    * or added.  Items may not change (except by being removed and added
 429    * back in the same location).  This signal is capable of describing
 430    * both of those changes (at the same time).
 431    *
 432    * The signal means that starting at the index @position, @removed
 433    * items were removed and @added items were added in their place.  If
 434    * @removed is zero then only items were added.  If @added is zero
 435    * then only items were removed.
 436    *
 437    * As an example, if the menu contains items a, b, c, d (in that
 438    * order) and the signal (2, 1, 3) occurs then the new composition of
 439    * the menu will be a, b, _, _, _, d (with each _ representing some
 440    * new item).
 441    *
 442    * Signal handlers may query the model (particularly the added items)
 443    * and expect to see the results of the modification that is being
 444    * reported.  The signal is emitted after the modification.
 445    **/
 446   g_menu_model_items_changed_signal =
 447     g_signal_new ("items-changed", G_TYPE_MENU_MODEL,
 448                   G_SIGNAL_RUN_LAST, 0, NULL, NULL,
 449                   g_cclosure_marshal_generic, G_TYPE_NONE,
 450                   3, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT);
 451 }
 452
 453 /**
 454  * g_menu_model_is_mutable:
 455  * @model: a #GMenuModel
 456  *
 457  * Queries if @model is mutable.
 458  *
 459  * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
 460  * signal. Consumers of the model may make optimisations accordingly.
 461  *
 462  * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
 463  *     emitted).
 464  *
 465  * Since: 2.32
 466  */
 467 gboolean
 468 g_menu_model_is_mutable (GMenuModel *model)
 469 {
 470   return G_MENU_MODEL_GET_CLASS (model)
 471     ->is_mutable (model);
 472 }
 473
 474 /**
 475  * g_menu_model_get_n_items:
 476  * @model: a #GMenuModel
 477  *
 478  * Query the number of items in @model.
 479  *
 480  * Returns: the number of items
 481  *
 482  * Since: 2.32
 483  */
 484 gint
 485 g_menu_model_get_n_items (GMenuModel *model)
 486 {
 487   return G_MENU_MODEL_GET_CLASS (model)
 488     ->get_n_items (model);
 489 }
 490
 491 /**
 492  * g_menu_model_iterate_item_attributes:
 493  * @model: a #GMenuModel
 494  * @item_index: the index of the item
 495  *
 496  * Creates a #GMenuAttributeIter to iterate over the attributes of
 497  * the item at position @item_index in @model.
 498  *
 499  * You must free the iterator with g_object_unref() when you are done.
 500  *
 501  * Returns: (transfer full): a new #GMenuAttributeIter
 502  *
 503  * Since: 2.32
 504  */
 505 GMenuAttributeIter *
 506 g_menu_model_iterate_item_attributes (GMenuModel *model,
 507                                       gint        item_index)
 508 {
 509   return G_MENU_MODEL_GET_CLASS (model)
 510     ->iterate_item_attributes (model, item_index);
 511 }
 512
 513 /**
 514  * g_menu_model_get_item_attribute_value:
 515  * @model: a #GMenuModel
 516  * @item_index: the index of the item
 517  * @attribute: the attribute to query
 518  * @expected_type: (allow-none): the expected type of the attribute, or
 519  *     %NULL
 520  *
 521  * Queries the item at position @item_index in @model for the attribute
 522  * specified by @attribute.
 523  *
 524  * If @expected_type is non-%NULL then it specifies the expected type of
 525  * the attribute.  If it is %NULL then any type will be accepted.
 526  *
 527  * If the attribute exists and matches @expected_type (or if the
 528  * expected type is unspecified) then the value is returned.
 529  *
 530  * If the attribute does not exist, or does not match the expected type
 531  * then %NULL is returned.
 532  *
 533  * Returns: (transfer full): the value of the attribute
 534  *
 535  * Since: 2.32
 536  */
 537 GVariant *
 538 g_menu_model_get_item_attribute_value (GMenuModel         *model,
 539                                        gint                item_index,
 540                                        const gchar        *attribute,
 541                                        const GVariantType *expected_type)
 542 {
 543   return G_MENU_MODEL_GET_CLASS (model)
 544     ->get_item_attribute_value (model, item_index, attribute, expected_type);
 545 }
 546
 547 /**
 548  * g_menu_model_get_item_attribute:
 549  * @model: a #GMenuModel
 550  * @item_index: the index of the item
 551  * @attribute: the attribute to query
 552  * @format_string: a #GVariant format string
 553  * @...: positional parameters, as per @format_string
 554  *
 555  * Queries item at position @item_index in @model for the attribute
 556  * specified by @attribute.
 557  *
 558  * If the attribute exists and matches the #GVariantType corresponding
 559  * to @format_string then @format_string is used to deconstruct the
 560  * value into the positional parameters and %TRUE is returned.
 561  *
 562  * If the attribute does not exist, or it does exist but has the wrong
 563  * type, then the positional parameters are ignored and %FALSE is
 564  * returned.
 565  *
 566  * Returns: %TRUE if the named attribute was found with the expected
 567  *     type
 568  *
 569  * Since: 2.32
 570  */
 571 gboolean
 572 g_menu_model_get_item_attribute (GMenuModel  *model,
 573                                  gint         item_index,
 574                                  const gchar *attribute,
 575                                  const gchar *format_string,
 576                                  ...)
 577 {
 578   const GVariantType *expected_type;
 579   GVariant *value;
 580   va_list ap;
 581
 582   expected_type = NULL; /* XXX devine the type, ensure no '&' */
 583
 584   value = g_menu_model_get_item_attribute_value (model, item_index, attribute, expected_type);
 585   if (value == NULL)
 586     return FALSE;
 587
 588   va_start (ap, format_string);
 589   g_variant_get_va (value, format_string, NULL, &ap);
 590   g_variant_unref (value);
 591   va_end (ap);
 592
 593   return TRUE;
 594 }
 595
 596 /**
 597  * g_menu_model_iterate_item_links:
 598  * @model: a #GMenuModel
 599  * @item_index: the index of the item
 600  *
 601  * Creates a #GMenuLinkIter to iterate over the links of the item at
 602  * position @item_index in @model.
 603  *
 604  * You must free the iterator with g_object_unref() when you are done.
 605  *
 606  * Returns: (transfer full): a new #GMenuLinkIter
 607  *
 608  * Since: 2.32
 609  */
 610 GMenuLinkIter *
 611 g_menu_model_iterate_item_links (GMenuModel *model,
 612                                  gint        item_index)
 613 {
 614   return G_MENU_MODEL_GET_CLASS (model)
 615     ->iterate_item_links (model, item_index);
 616 }
 617
 618 /**
 619  * g_menu_model_get_item_link:
 620  * @model: a #GMenuModel
 621  * @item_index: the index of the item
 622  * @link: the link to query
 623  *
 624  * Queries the item at position @item_index in @model for the link
 625  * specified by @link.
 626  *
 627  * If the link exists, the linked #GMenuModel is returned.  If the link
 628  * does not exist, %NULL is returned.
 629  *
 630  * Returns: (transfer full): the linked #GMenuModel, or %NULL
 631  *
 632  * Since: 2.32
 633  */
 634 GMenuModel *
 635 g_menu_model_get_item_link (GMenuModel *model,
 636                             gint        item_index,
 637                             const gchar *link)
 638 {
 639   return G_MENU_MODEL_GET_CLASS (model)
 640     ->get_item_link (model, item_index, link);
 641 }
 642
 643 /**
 644  * g_menu_model_items_changed:
 645  * @model: a #GMenuModel
 646  * @position: the position of the change
 647  * @removed: the number of items removed
 648  * @added: the number of items added
 649  *
 650  * Requests emission of the #GMenuModel::items-changed signal on @model.
 651  *
 652  * This function should never be called except by #GMenuModel
 653  * subclasses.  Any other calls to this function will very likely lead
 654  * to a violation of the interface of the model.
 655  *
 656  * The implementation should update its internal representation of the
 657  * menu before emitting the signal.  The implementation should further
 658  * expect to receive queries about the new state of the menu (and
 659  * particularly added menu items) while signal handlers are running.
 660  *
 661  * The implementation must dispatch this call directly from a mainloop
 662  * entry and not in response to calls -- particularly those from the
 663  * #GMenuModel API.  Said another way: the menu must not change while
 664  * user code is running without returning to the mainloop.
 665  *
 666  * Since: 2.32
 667  */
 668 void
 669 g_menu_model_items_changed (GMenuModel *model,
 670                             gint        position,
 671                             gint        removed,
 672                             gint        added)
 673 {
 674   g_signal_emit (model, g_menu_model_items_changed_signal, 0, position, removed, added);
 675 }
 676
 677 G_DEFINE_ABSTRACT_TYPE (GMenuAttributeIter, g_menu_attribute_iter, G_TYPE_OBJECT)
 678
 679 struct _GMenuAttributeIterPrivate
 680 {
 681   GQuark name;
 682   GVariant *value;
 683   gboolean valid;
 684 };
 685
 686 /**
 687  * g_menu_attribute_iter_get_next:
 688  * @iter: a #GMenuAttributeIter
 689  * @out_name: (out) (allow-none) (transfer none): the type of the attribute
 690  * @value: (out) (allow-none) (transfer full): the attribute value
 691  *
 692  * This function combines g_menu_attribute_iter_next() with
 693  * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
 694  *
 695  * First the iterator is advanced to the next (possibly first) attribute.
 696  * If that fails, then %FALSE is returned and there are no other
 697  * effects.
 698  *
 699  * If successful, @name and @value are set to the name and value of the
 700  * attribute that has just been advanced to.  At this point,
 701  * g_menu_item_get_name() and g_menu_item_get_value() will return the
 702  * same values again.
 703  *
 704  * The value returned in @name remains valid for as long as the iterator
 705  * remains at the current position.  The value returned in @value must
 706  * be unreffed using g_variant_unref() when it is no longer in use.
 707  *
 708  * Returns: %TRUE on success, or %FALSE if there is no additional
 709  *     attribute
 710  *
 711  * Since: 2.32
 712  */
 713 gboolean
 714 g_menu_attribute_iter_get_next (GMenuAttributeIter  *iter,
 715                                 const gchar        **out_name,
 716                                 GVariant           **value)
 717 {
 718   const gchar *name;
 719
 720   if (iter->priv->value)
 721     {
 722       g_variant_unref (iter->priv->value);
 723       iter->priv->value = NULL;
 724     }
 725
 726   iter->priv->valid = G_MENU_ATTRIBUTE_ITER_GET_CLASS (iter)
 727     ->get_next (iter, &name, &iter->priv->value);
 728
 729   if (iter->priv->valid)
 730     {
 731       iter->priv->name = g_quark_from_string (name);
 732       if (out_name)
 733         *out_name = g_quark_to_string (iter->priv->name);
 734
 735       if (value)
 736         *value = g_variant_ref (iter->priv->value);
 737     }
 738
 739   return iter->priv->valid;
 740 }
 741
 742 /**
 743  * g_menu_attribute_iter_next:
 744  * @iter: a #GMenuAttributeIter
 745  *
 746  * Attempts to advance the iterator to the next (possibly first)
 747  * attribute.
 748  *
 749  * %TRUE is returned on success, or %FALSE if there are no more
 750  * attributes.
 751  *
 752  * You must call this function when you first acquire the iterator
 753  * to advance it to the first attribute (and determine if the first
 754  * attribute exists at all).
 755  *
 756  * Returns: %TRUE on success, or %FALSE when there are no more attributes
 757  *
 758  * Since: 2.32
 759  */
 760 gboolean
 761 g_menu_attribute_iter_next (GMenuAttributeIter *iter)
 762 {
 763   return g_menu_attribute_iter_get_next (iter, NULL, NULL);
 764 }
 765
 766 /**
 767  * g_menu_attribute_iter_get_name:
 768  * @iter: a #GMenuAttributeIter
 769  *
 770  * Gets the name of the attribute at the current iterator position, as
 771  * a string.
 772  *
 773  * The iterator is not advanced.
 774  *
 775  * Returns: the name of the attribute
 776  *
 777  * Since: 2.32
 778  */
 779 const gchar *
 780 g_menu_attribute_iter_get_name (GMenuAttributeIter *iter)
 781 {
 782   g_return_val_if_fail (iter->priv->valid, 0);
 783
 784   return g_quark_to_string (iter->priv->name);
 785 }
 786
 787 /**
 788  * g_menu_attribute_iter_get_value:
 789  * @iter: a #GMenuAttributeIter
 790  *
 791  * Gets the value of the attribute at the current iterator position.
 792  *
 793  * The iterator is not advanced.
 794  *
 795  * Returns: (transfer full): the value of the current attribute
 796  *
 797  * Since: 2.32
 798  */
 799 GVariant *
 800 g_menu_attribute_iter_get_value (GMenuAttributeIter *iter)
 801 {
 802   g_return_val_if_fail (iter->priv->valid, NULL);
 803
 804   return g_variant_ref (iter->priv->value);
 805 }
 806
 807 static void
 808 g_menu_attribute_iter_finalize (GObject *object)
 809 {
 810   GMenuAttributeIter *iter = G_MENU_ATTRIBUTE_ITER (object);
 811
 812   if (iter->priv->value)
 813     g_variant_unref (iter->priv->value);
 814
 815   G_OBJECT_CLASS (g_menu_attribute_iter_parent_class)
 816     ->finalize (object);
 817 }
 818
 819 static void
 820 g_menu_attribute_iter_init (GMenuAttributeIter *iter)
 821 {
 822   iter->priv = G_TYPE_INSTANCE_GET_PRIVATE (iter, G_TYPE_MENU_ATTRIBUTE_ITER, GMenuAttributeIterPrivate);
 823 }
 824
 825 static void
 826 g_menu_attribute_iter_class_init (GMenuAttributeIterClass *class)
 827 {
 828   GObjectClass *object_class = G_OBJECT_CLASS (class);
 829
 830   object_class->finalize = g_menu_attribute_iter_finalize;
 831
 832   g_type_class_add_private (class, sizeof (GMenuAttributeIterPrivate));
 833 }
 834
 835 G_DEFINE_ABSTRACT_TYPE (GMenuLinkIter, g_menu_link_iter, G_TYPE_OBJECT)
 836
 837 struct _GMenuLinkIterPrivate
 838 {
 839   GQuark name;
 840   GMenuModel *value;
 841   gboolean valid;
 842 };
 843
 844 /**
 845  * g_menu_link_iter_get_next:
 846  * @iter: a #GMenuLinkIter
 847  * @out_link: (out) (allow-none) (transfer none): the name of the link
 848  * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
 849  *
 850  * This function combines g_menu_link_iter_next() with
 851  * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
 852  *
 853  * First the iterator is advanced to the next (possibly first) link.
 854  * If that fails, then %FALSE is returned and there are no other effects.
 855  *
 856  * If successful, @out_link and @value are set to the name and #GMenuModel
 857  * of the link that has just been advanced to.  At this point,
 858  * g_menu_item_get_name() and g_menu_item_get_value() will return the
 859  * same values again.
 860  *
 861  * The value returned in @out_link remains valid for as long as the iterator
 862  * remains at the current position.  The value returned in @value must
 863  * be unreffed using g_object_unref() when it is no longer in use.
 864  *
 865  * Returns: %TRUE on success, or %FALSE if there is no additional link
 866  *
 867  * Since: 2.32
 868  */
 869 gboolean
 870 g_menu_link_iter_get_next (GMenuLinkIter  *iter,
 871                            const gchar   **out_link,
 872                            GMenuModel    **value)
 873 {
 874   const gchar *name;
 875
 876   if (iter->priv->value)
 877     {
 878       g_object_unref (iter->priv->value);
 879       iter->priv->value = NULL;
 880     }
 881
 882   iter->priv->valid = G_MENU_LINK_ITER_GET_CLASS (iter)
 883     ->get_next (iter, &name, &iter->priv->value);
 884
 885   if (iter->priv->valid)
 886     {
 887       g_assert (name != NULL);
 888
 889       iter->priv->name = g_quark_from_string (name);
 890       if (out_link)
 891         *out_link = g_quark_to_string (iter->priv->name);
 892
 893       if (value)
 894         *value = g_object_ref (iter->priv->value);
 895     }
 896
 897   return iter->priv->valid;
 898 }
 899
 900 /**
 901  * g_menu_link_iter_next:
 902  * @iter: a #GMenuLinkIter
 903  *
 904  * Attempts to advance the iterator to the next (possibly first)
 905  * link.
 906  *
 907  * %TRUE is returned on success, or %FALSE if there are no more links.
 908  *
 909  * You must call this function when you first acquire the iterator to
 910  * advance it to the first link (and determine if the first link exists
 911  * at all).
 912  *
 913  * Returns: %TRUE on success, or %FALSE when there are no more links
 914  *
 915  * Since: 2.32
 916  */
 917 gboolean
 918 g_menu_link_iter_next (GMenuLinkIter *iter)
 919 {
 920   return g_menu_link_iter_get_next (iter, NULL, NULL);
 921 }
 922
 923 /**
 924  * g_menu_link_iter_get_name:
 925  * @iter: a #GMenuLinkIter
 926  *
 927  * Gets the name of the link at the current iterator position.
 928  *
 929  * The iterator is not advanced.
 930  *
 931  * Returns: the type of the link
 932  *
 933  * Since: 2.32
 934  */
 935 const gchar *
 936 g_menu_link_iter_get_name (GMenuLinkIter *iter)
 937 {
 938   g_return_val_if_fail (iter->priv->valid, 0);
 939
 940   return g_quark_to_string (iter->priv->name);
 941 }
 942
 943 /**
 944  * g_menu_link_iter_get_value:
 945  * @iter: a #GMenuLinkIter
 946  *
 947  * Gets the linked #GMenuModel at the current iterator position.
 948  *
 949  * The iterator is not advanced.
 950  *
 951  * Returns: (transfer full): the #GMenuModel that is linked to
 952  *
 953  * Since: 2.32
 954  */
 955 GMenuModel *
 956 g_menu_link_iter_get_value (GMenuLinkIter *iter)
 957 {
 958   g_return_val_if_fail (iter->priv->valid, NULL);
 959
 960   return g_object_ref (iter->priv->value);
 961 }
 962
 963 static void
 964 g_menu_link_iter_finalize (GObject *object)
 965 {
 966   GMenuLinkIter *iter = G_MENU_LINK_ITER (object);
 967
 968   if (iter->priv->value)
 969     g_object_unref (iter->priv->value);
 970
 971   G_OBJECT_CLASS (g_menu_link_iter_parent_class)
 972     ->finalize (object);
 973 }
 974
 975 static void
 976 g_menu_link_iter_init (GMenuLinkIter *iter)
 977 {
 978   iter->priv = G_TYPE_INSTANCE_GET_PRIVATE (iter, G_TYPE_MENU_LINK_ITER, GMenuLinkIterPrivate);
 979 }
 980
 981 static void
 982 g_menu_link_iter_class_init (GMenuLinkIterClass *class)
 983 {
 984   GObjectClass *object_class = G_OBJECT_CLASS (class);
 985
 986   object_class->finalize = g_menu_link_iter_finalize;
 987
 988   g_type_class_add_private (class, sizeof (GMenuLinkIterPrivate));
 989 }