2 * Copyright © 2011 Canonical Ltd.
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.
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.
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,
19 * Author: Ryan Lortie <desrt@desrt.ca>
24 #include "gmenumodel.h"
29 * @short_description: An abstract class representing the contents of a menu
30 * @see_also: #GActionGroup
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.
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).
47 * As an example, consider the visible portions of the menu in
48 * <xref linkend="menu-example"/>.
50 * <figure id="menu-example">
51 * <title>An example menu</title>
52 * <graphic fileref="menu-example.png" format="PNG"></graphic>
55 * There are 8 "menus" visible in the screenshot: one menubar, two
56 * submenus and 5 sections:
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>
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.
73 * <figure id="menu-model">
74 * <title>A menu model</title>
75 * <graphic fileref="menu-model.png" format="PNG"></graphic>
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.
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
91 * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
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
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.
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.".
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
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>
126 * <formalpara><title>Stateless</title>
128 * A stateless action typically corresponds to an ordinary menu item.
131 * Selecting such a menu item will activate the action (with no parameter).
135 * <formalpara><title>Boolean State</title>
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.
142 * Selecting a toggle menu item will activate the action. The menu item should
143 * be rendered as "checked" when the state is true.
147 * <formalpara><title>String Parameter and State</title>
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.
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.
167 * #GMenuModel is an opaque structure type. You must access it using the
174 * GMenuAttributeIter:
176 * #GMenuAttributeIter is an opaque structure type. You must access it
177 * using the functions below.
185 * #GMenuLinkIter is an opaque structure type. You must access it using
186 * the functions below.
193 GMenuLinkIter parent_instance
;
198 typedef GMenuLinkIterClass GMenuLinkHashIterClass
;
200 static GType
g_menu_link_hash_iter_get_type (void);
202 G_DEFINE_TYPE (GMenuLinkHashIter
, g_menu_link_hash_iter
, G_TYPE_MENU_LINK_ITER
)
205 g_menu_link_hash_iter_get_next (GMenuLinkIter
*link_iter
,
206 const gchar
**out_name
,
209 GMenuLinkHashIter
*iter
= (GMenuLinkHashIter
*) link_iter
;
210 gpointer keyptr
, valueptr
;
212 if (!g_hash_table_iter_next (&iter
->iter
, &keyptr
, &valueptr
))
216 *value
= g_object_ref (valueptr
);
222 g_menu_link_hash_iter_finalize (GObject
*object
)
224 GMenuLinkHashIter
*iter
= (GMenuLinkHashIter
*) object
;
226 g_hash_table_unref (iter
->table
);
228 G_OBJECT_CLASS (g_menu_link_hash_iter_parent_class
)
233 g_menu_link_hash_iter_init (GMenuLinkHashIter
*iter
)
238 g_menu_link_hash_iter_class_init (GMenuLinkHashIterClass
*class)
240 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
242 object_class
->finalize
= g_menu_link_hash_iter_finalize
;
243 class->get_next
= g_menu_link_hash_iter_get_next
;
249 GMenuAttributeIter parent_instance
;
252 } GMenuAttributeHashIter
;
254 typedef GMenuAttributeIterClass GMenuAttributeHashIterClass
;
256 static GType
g_menu_attribute_hash_iter_get_type (void);
258 G_DEFINE_TYPE (GMenuAttributeHashIter
, g_menu_attribute_hash_iter
, G_TYPE_MENU_ATTRIBUTE_ITER
)
261 g_menu_attribute_hash_iter_get_next (GMenuAttributeIter
*attr_iter
,
265 GMenuAttributeHashIter
*iter
= (GMenuAttributeHashIter
*) attr_iter
;
266 gpointer keyptr
, valueptr
;
268 if (!g_hash_table_iter_next (&iter
->iter
, &keyptr
, &valueptr
))
273 *value
= g_variant_ref (valueptr
);
279 g_menu_attribute_hash_iter_finalize (GObject
*object
)
281 GMenuAttributeHashIter
*iter
= (GMenuAttributeHashIter
*) object
;
283 g_hash_table_unref (iter
->table
);
285 G_OBJECT_CLASS (g_menu_attribute_hash_iter_parent_class
)
290 g_menu_attribute_hash_iter_init (GMenuAttributeHashIter
*iter
)
295 g_menu_attribute_hash_iter_class_init (GMenuAttributeHashIterClass
*class)
297 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
299 object_class
->finalize
= g_menu_attribute_hash_iter_finalize
;
300 class->get_next
= g_menu_attribute_hash_iter_get_next
;
303 G_DEFINE_ABSTRACT_TYPE (GMenuModel
, g_menu_model
, G_TYPE_OBJECT
)
306 static guint g_menu_model_items_changed_signal
;
308 static GMenuAttributeIter
*
309 g_menu_model_real_iterate_item_attributes (GMenuModel
*model
,
312 GHashTable
*table
= NULL
;
313 GMenuAttributeIter
*result
;
315 G_MENU_MODEL_GET_CLASS (model
)->get_item_attributes (model
, item_index
, &table
);
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
);
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
));
333 g_hash_table_unref (table
);
339 g_menu_model_real_get_item_attribute_value (GMenuModel
*model
,
341 const gchar
*attribute
,
342 const GVariantType
*expected_type
)
344 GHashTable
*table
= NULL
;
345 GVariant
*value
= NULL
;
347 G_MENU_MODEL_GET_CLASS (model
)
348 ->get_item_attributes (model
, item_index
, &table
);
352 value
= g_hash_table_lookup (table
, attribute
);
356 if (expected_type
== NULL
|| g_variant_is_of_type (value
, expected_type
))
357 value
= g_variant_ref (value
);
363 g_assert_not_reached ();
366 g_hash_table_unref (table
);
371 static GMenuLinkIter
*
372 g_menu_model_real_iterate_item_links (GMenuModel
*model
,
375 GHashTable
*table
= NULL
;
376 GMenuLinkIter
*result
;
378 G_MENU_MODEL_GET_CLASS (model
)
379 ->get_item_links (model
, item_index
, &table
);
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
);
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
));
397 g_hash_table_unref (table
);
403 g_menu_model_real_get_item_link (GMenuModel
*model
,
407 GHashTable
*table
= NULL
;
408 GMenuModel
*value
= NULL
;
410 G_MENU_MODEL_GET_CLASS (model
)
411 ->get_item_links (model
, item_index
, &table
);
414 value
= g_hash_table_lookup (table
, link
);
416 g_assert_not_reached ();
419 g_object_ref (value
);
422 g_hash_table_unref (table
);
428 g_menu_model_init (GMenuModel
*model
)
433 g_menu_model_class_init (GMenuModelClass
*class)
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
;
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
447 * Emitted when a change has occured to the menu.
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).
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.
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
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.
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
);
476 * g_menu_model_is_mutable:
477 * @model: a #GMenuModel
479 * Queries if @model is mutable.
481 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
482 * signal. Consumers of the model may make optimisations accordingly.
484 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
490 g_menu_model_is_mutable (GMenuModel
*model
)
492 return G_MENU_MODEL_GET_CLASS (model
)
493 ->is_mutable (model
);
497 * g_menu_model_get_n_items:
498 * @model: a #GMenuModel
500 * Query the number of items in @model.
502 * Returns: the number of items
507 g_menu_model_get_n_items (GMenuModel
*model
)
509 return G_MENU_MODEL_GET_CLASS (model
)
510 ->get_n_items (model
);
514 * g_menu_model_iterate_item_attributes:
515 * @model: a #GMenuModel
516 * @item_index: the index of the item
518 * Creates a #GMenuAttributeIter to iterate over the attributes of
519 * the item at position @item_index in @model.
521 * You must free the iterator with g_object_unref() when you are done.
523 * Returns: (transfer full): a new #GMenuAttributeIter
528 g_menu_model_iterate_item_attributes (GMenuModel
*model
,
531 return G_MENU_MODEL_GET_CLASS (model
)
532 ->iterate_item_attributes (model
, item_index
);
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
543 * Queries the item at position @item_index in @model for the attribute
544 * specified by @attribute.
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.
549 * If the attribute exists and matches @expected_type (or if the
550 * expected type is unspecified) then the value is returned.
552 * If the attribute does not exist, or does not match the expected type
553 * then %NULL is returned.
555 * Returns: (transfer full): the value of the attribute
560 g_menu_model_get_item_attribute_value (GMenuModel
*model
,
562 const gchar
*attribute
,
563 const GVariantType
*expected_type
)
565 return G_MENU_MODEL_GET_CLASS (model
)
566 ->get_item_attribute_value (model
, item_index
, attribute
, expected_type
);
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
577 * Queries item at position @item_index in @model for the attribute
578 * specified by @attribute.
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.
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
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 '&' characters are allowed in @format_string.
594 * Returns: %TRUE if the named attribute was found with the expected
600 g_menu_model_get_item_attribute (GMenuModel
*model
,
602 const gchar
*attribute
,
603 const gchar
*format_string
,
609 value
= g_menu_model_get_item_attribute_value (model
, item_index
, attribute
, NULL
);
614 if (!g_variant_check_format_string (value
, format_string
, TRUE
))
616 g_variant_unref (value
);
620 va_start (ap
, format_string
);
621 g_variant_get_va (value
, format_string
, NULL
, &ap
);
622 g_variant_unref (value
);
629 * g_menu_model_iterate_item_links:
630 * @model: a #GMenuModel
631 * @item_index: the index of the item
633 * Creates a #GMenuLinkIter to iterate over the links of the item at
634 * position @item_index in @model.
636 * You must free the iterator with g_object_unref() when you are done.
638 * Returns: (transfer full): a new #GMenuLinkIter
643 g_menu_model_iterate_item_links (GMenuModel
*model
,
646 return G_MENU_MODEL_GET_CLASS (model
)
647 ->iterate_item_links (model
, item_index
);
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
656 * Queries the item at position @item_index in @model for the link
657 * specified by @link.
659 * If the link exists, the linked #GMenuModel is returned. If the link
660 * does not exist, %NULL is returned.
662 * Returns: (transfer full): the linked #GMenuModel, or %NULL
667 g_menu_model_get_item_link (GMenuModel
*model
,
671 return G_MENU_MODEL_GET_CLASS (model
)
672 ->get_item_link (model
, item_index
, link
);
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
682 * Requests emission of the #GMenuModel::items-changed signal on @model.
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.
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.
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.
701 g_menu_model_items_changed (GMenuModel
*model
,
706 g_signal_emit (model
, g_menu_model_items_changed_signal
, 0, position
, removed
, added
);
709 struct _GMenuAttributeIterPrivate
716 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuAttributeIter
, g_menu_attribute_iter
, G_TYPE_OBJECT
)
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
724 * This function combines g_menu_attribute_iter_next() with
725 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
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
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.
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.
740 * Returns: %TRUE on success, or %FALSE if there is no additional
746 g_menu_attribute_iter_get_next (GMenuAttributeIter
*iter
,
747 const gchar
**out_name
,
752 if (iter
->priv
->value
)
754 g_variant_unref (iter
->priv
->value
);
755 iter
->priv
->value
= NULL
;
758 iter
->priv
->valid
= G_MENU_ATTRIBUTE_ITER_GET_CLASS (iter
)
759 ->get_next (iter
, &name
, &iter
->priv
->value
);
761 if (iter
->priv
->valid
)
763 iter
->priv
->name
= g_quark_from_string (name
);
765 *out_name
= g_quark_to_string (iter
->priv
->name
);
768 *value
= g_variant_ref (iter
->priv
->value
);
771 return iter
->priv
->valid
;
775 * g_menu_attribute_iter_next:
776 * @iter: a #GMenuAttributeIter
778 * Attempts to advance the iterator to the next (possibly first)
781 * %TRUE is returned on success, or %FALSE if there are no more
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).
788 * Returns: %TRUE on success, or %FALSE when there are no more attributes
793 g_menu_attribute_iter_next (GMenuAttributeIter
*iter
)
795 return g_menu_attribute_iter_get_next (iter
, NULL
, NULL
);
799 * g_menu_attribute_iter_get_name:
800 * @iter: a #GMenuAttributeIter
802 * Gets the name of the attribute at the current iterator position, as
805 * The iterator is not advanced.
807 * Returns: the name of the attribute
812 g_menu_attribute_iter_get_name (GMenuAttributeIter
*iter
)
814 g_return_val_if_fail (iter
->priv
->valid
, 0);
816 return g_quark_to_string (iter
->priv
->name
);
820 * g_menu_attribute_iter_get_value:
821 * @iter: a #GMenuAttributeIter
823 * Gets the value of the attribute at the current iterator position.
825 * The iterator is not advanced.
827 * Returns: (transfer full): the value of the current attribute
832 g_menu_attribute_iter_get_value (GMenuAttributeIter
*iter
)
834 g_return_val_if_fail (iter
->priv
->valid
, NULL
);
836 return g_variant_ref (iter
->priv
->value
);
840 g_menu_attribute_iter_finalize (GObject
*object
)
842 GMenuAttributeIter
*iter
= G_MENU_ATTRIBUTE_ITER (object
);
844 if (iter
->priv
->value
)
845 g_variant_unref (iter
->priv
->value
);
847 G_OBJECT_CLASS (g_menu_attribute_iter_parent_class
)
852 g_menu_attribute_iter_init (GMenuAttributeIter
*iter
)
854 iter
->priv
= g_menu_attribute_iter_get_instance_private (iter
);
858 g_menu_attribute_iter_class_init (GMenuAttributeIterClass
*class)
860 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
862 object_class
->finalize
= g_menu_attribute_iter_finalize
;
865 struct _GMenuLinkIterPrivate
872 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuLinkIter
, g_menu_link_iter
, G_TYPE_OBJECT
)
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
880 * This function combines g_menu_link_iter_next() with
881 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
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.
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
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.
895 * Returns: %TRUE on success, or %FALSE if there is no additional link
900 g_menu_link_iter_get_next (GMenuLinkIter
*iter
,
901 const gchar
**out_link
,
906 if (iter
->priv
->value
)
908 g_object_unref (iter
->priv
->value
);
909 iter
->priv
->value
= NULL
;
912 iter
->priv
->valid
= G_MENU_LINK_ITER_GET_CLASS (iter
)
913 ->get_next (iter
, &name
, &iter
->priv
->value
);
915 if (iter
->priv
->valid
)
917 g_assert (name
!= NULL
);
919 iter
->priv
->name
= g_quark_from_string (name
);
921 *out_link
= g_quark_to_string (iter
->priv
->name
);
924 *value
= g_object_ref (iter
->priv
->value
);
927 return iter
->priv
->valid
;
931 * g_menu_link_iter_next:
932 * @iter: a #GMenuLinkIter
934 * Attempts to advance the iterator to the next (possibly first)
937 * %TRUE is returned on success, or %FALSE if there are no more links.
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
943 * Returns: %TRUE on success, or %FALSE when there are no more links
948 g_menu_link_iter_next (GMenuLinkIter
*iter
)
950 return g_menu_link_iter_get_next (iter
, NULL
, NULL
);
954 * g_menu_link_iter_get_name:
955 * @iter: a #GMenuLinkIter
957 * Gets the name of the link at the current iterator position.
959 * The iterator is not advanced.
961 * Returns: the type of the link
966 g_menu_link_iter_get_name (GMenuLinkIter
*iter
)
968 g_return_val_if_fail (iter
->priv
->valid
, 0);
970 return g_quark_to_string (iter
->priv
->name
);
974 * g_menu_link_iter_get_value:
975 * @iter: a #GMenuLinkIter
977 * Gets the linked #GMenuModel at the current iterator position.
979 * The iterator is not advanced.
981 * Returns: (transfer full): the #GMenuModel that is linked to
986 g_menu_link_iter_get_value (GMenuLinkIter
*iter
)
988 g_return_val_if_fail (iter
->priv
->valid
, NULL
);
990 return g_object_ref (iter
->priv
->value
);
994 g_menu_link_iter_finalize (GObject
*object
)
996 GMenuLinkIter
*iter
= G_MENU_LINK_ITER (object
);
998 if (iter
->priv
->value
)
999 g_object_unref (iter
->priv
->value
);
1001 G_OBJECT_CLASS (g_menu_link_iter_parent_class
)
1002 ->finalize (object
);
1006 g_menu_link_iter_init (GMenuLinkIter
*iter
)
1008 iter
->priv
= g_menu_link_iter_get_instance_private (iter
);
1012 g_menu_link_iter_class_init (GMenuLinkIterClass
*class)
1014 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
1016 object_class
->finalize
= g_menu_link_iter_finalize
;