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