gio/gmenumodel.c

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