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