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, see <http://www.gnu.org/licenses/>.
17 * Author: Ryan Lortie <desrt@desrt.ca>
22 #include "gmenumodel.h"
27 * @short_description: An abstract class representing the contents of a menu
29 * @see_also: #GActionGroup
31 * #GMenuModel represents the contents of a menu -- an ordered list of
32 * menu items. The items are associated with actions, which can be
33 * activated through them. Items can be grouped in sections, and may
34 * have submenus associated with them. Both items and sections usually
35 * have some representation data, such as labels or icons. The type of
36 * the associated action (ie whether it is stateful, and what kind of
37 * state it has) can influence the representation of the item.
39 * The conceptual model of menus in #GMenuModel is hierarchical:
40 * sections and submenus are again represented by #GMenuModels.
41 * Menus themselves do not define their own roles. Rather, the role
42 * of a particular #GMenuModel is defined by the item that references
43 * it (or, in the case of the 'root' menu, is defined by the context
44 * in which it is used).
46 * As an example, consider the visible portions of the menu in
47 * <xref linkend="menu-example"/>.
49 * <figure id="menu-example">
50 * <title>An example menu</title>
51 * <graphic fileref="menu-example.png" format="PNG"></graphic>
54 * There are 8 "menus" visible in the screenshot: one menubar, two
55 * submenus and 5 sections:
57 * - the toplevel menubar (containing 4 items)
58 * - the View submenu (containing 3 sections)
59 * - the first section of the View submenu (containing 2 items)
60 * - the second section of the View submenu (containing 1 item)
61 * - the final section of the View submenu (containing 1 item)
62 * - the Highlight Mode submenu (containing 2 sections)
63 * - the Sources section (containing 2 items)
64 * - the Markup section (containing 2 items)
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.
71 * <figure id="menu-model">
72 * <title>A menu model</title>
73 * <graphic fileref="menu-model.png" format="PNG"></graphic>
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.
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
89 * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
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
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.
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.".
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
118 * - an action with no parameter type and no state
119 * - an action with no parameter type and boolean state
120 * - an action with string parameter type and string state
124 * A stateless action typically corresponds to an ordinary menu item.
126 * Selecting such a menu item will activate the action (with no parameter).
130 * An action with a boolean state will most typically be used with a "toggle"
131 * or "switch" menu item. The state can be set directly, but activating the
132 * action (with no parameter) results in the state being toggled.
134 * Selecting a toggle menu item will activate the action. The menu item should
135 * be rendered as "checked" when the state is true.
137 * ## String Parameter and State
139 * Actions with string parameters and state will most typically be used to
140 * represent an enumerated choice over the items available for a group of
141 * radio menu items. Activating the action with a string parameter is
142 * equivalent to setting that parameter as the state.
144 * Radio menu items, in addition to being associated with the action, will
145 * have a target value. Selecting that menu item will result in activation
146 * of the action with the target value as the parameter. The menu item should
147 * be rendered as "selected" when the state of the action is equal to the
148 * target value of the menu item.
154 * #GMenuModel is an opaque structure type. You must access it using the
161 * GMenuAttributeIter:
163 * #GMenuAttributeIter is an opaque structure type. You must access it
164 * using the functions below.
172 * #GMenuLinkIter is an opaque structure type. You must access it using
173 * the functions below.
180 GMenuLinkIter parent_instance;
185 typedef GMenuLinkIterClass GMenuLinkHashIterClass;
187 static GType g_menu_link_hash_iter_get_type (void);
189 G_DEFINE_TYPE (GMenuLinkHashIter, g_menu_link_hash_iter, G_TYPE_MENU_LINK_ITER)
192 g_menu_link_hash_iter_get_next (GMenuLinkIter *link_iter,
193 const gchar **out_name,
196 GMenuLinkHashIter *iter = (GMenuLinkHashIter *) link_iter;
197 gpointer keyptr, valueptr;
199 if (!g_hash_table_iter_next (&iter->iter, &keyptr, &valueptr))
203 *value = g_object_ref (valueptr);
209 g_menu_link_hash_iter_finalize (GObject *object)
211 GMenuLinkHashIter *iter = (GMenuLinkHashIter *) object;
213 g_hash_table_unref (iter->table);
215 G_OBJECT_CLASS (g_menu_link_hash_iter_parent_class)
220 g_menu_link_hash_iter_init (GMenuLinkHashIter *iter)
225 g_menu_link_hash_iter_class_init (GMenuLinkHashIterClass *class)
227 GObjectClass *object_class = G_OBJECT_CLASS (class);
229 object_class->finalize = g_menu_link_hash_iter_finalize;
230 class->get_next = g_menu_link_hash_iter_get_next;
236 GMenuAttributeIter parent_instance;
239 } GMenuAttributeHashIter;
241 typedef GMenuAttributeIterClass GMenuAttributeHashIterClass;
243 static GType g_menu_attribute_hash_iter_get_type (void);
245 G_DEFINE_TYPE (GMenuAttributeHashIter, g_menu_attribute_hash_iter, G_TYPE_MENU_ATTRIBUTE_ITER)
248 g_menu_attribute_hash_iter_get_next (GMenuAttributeIter *attr_iter,
252 GMenuAttributeHashIter *iter = (GMenuAttributeHashIter *) attr_iter;
253 gpointer keyptr, valueptr;
255 if (!g_hash_table_iter_next (&iter->iter, &keyptr, &valueptr))
260 *value = g_variant_ref (valueptr);
266 g_menu_attribute_hash_iter_finalize (GObject *object)
268 GMenuAttributeHashIter *iter = (GMenuAttributeHashIter *) object;
270 g_hash_table_unref (iter->table);
272 G_OBJECT_CLASS (g_menu_attribute_hash_iter_parent_class)
277 g_menu_attribute_hash_iter_init (GMenuAttributeHashIter *iter)
282 g_menu_attribute_hash_iter_class_init (GMenuAttributeHashIterClass *class)
284 GObjectClass *object_class = G_OBJECT_CLASS (class);
286 object_class->finalize = g_menu_attribute_hash_iter_finalize;
287 class->get_next = g_menu_attribute_hash_iter_get_next;
290 G_DEFINE_ABSTRACT_TYPE (GMenuModel, g_menu_model, G_TYPE_OBJECT)
293 static guint g_menu_model_items_changed_signal;
295 static GMenuAttributeIter *
296 g_menu_model_real_iterate_item_attributes (GMenuModel *model,
299 GHashTable *table = NULL;
300 GMenuAttributeIter *result;
302 G_MENU_MODEL_GET_CLASS (model)->get_item_attributes (model, item_index, &table);
306 GMenuAttributeHashIter *iter = g_object_new (g_menu_attribute_hash_iter_get_type (), NULL);
307 g_hash_table_iter_init (&iter->iter, table);
308 iter->table = g_hash_table_ref (table);
309 result = G_MENU_ATTRIBUTE_ITER (iter);
313 g_critical ("GMenuModel implementation '%s' doesn't override iterate_item_attributes() "
314 "and fails to return sane values from get_item_attributes()",
315 G_OBJECT_TYPE_NAME (model));
320 g_hash_table_unref (table);
326 g_menu_model_real_get_item_attribute_value (GMenuModel *model,
328 const gchar *attribute,
329 const GVariantType *expected_type)
331 GHashTable *table = NULL;
332 GVariant *value = NULL;
334 G_MENU_MODEL_GET_CLASS (model)
335 ->get_item_attributes (model, item_index, &table);
339 value = g_hash_table_lookup (table, attribute);
343 if (expected_type == NULL || g_variant_is_of_type (value, expected_type))
344 value = g_variant_ref (value);
350 g_assert_not_reached ();
353 g_hash_table_unref (table);
358 static GMenuLinkIter *
359 g_menu_model_real_iterate_item_links (GMenuModel *model,
362 GHashTable *table = NULL;
363 GMenuLinkIter *result;
365 G_MENU_MODEL_GET_CLASS (model)
366 ->get_item_links (model, item_index, &table);
370 GMenuLinkHashIter *iter = g_object_new (g_menu_link_hash_iter_get_type (), NULL);
371 g_hash_table_iter_init (&iter->iter, table);
372 iter->table = g_hash_table_ref (table);
373 result = G_MENU_LINK_ITER (iter);
377 g_critical ("GMenuModel implementation '%s' doesn't override iterate_item_links() "
378 "and fails to return sane values from get_item_links()",
379 G_OBJECT_TYPE_NAME (model));
384 g_hash_table_unref (table);
390 g_menu_model_real_get_item_link (GMenuModel *model,
394 GHashTable *table = NULL;
395 GMenuModel *value = NULL;
397 G_MENU_MODEL_GET_CLASS (model)
398 ->get_item_links (model, item_index, &table);
401 value = g_hash_table_lookup (table, link);
403 g_assert_not_reached ();
406 g_object_ref (value);
409 g_hash_table_unref (table);
415 g_menu_model_init (GMenuModel *model)
420 g_menu_model_class_init (GMenuModelClass *class)
422 class->iterate_item_attributes = g_menu_model_real_iterate_item_attributes;
423 class->get_item_attribute_value = g_menu_model_real_get_item_attribute_value;
424 class->iterate_item_links = g_menu_model_real_iterate_item_links;
425 class->get_item_link = g_menu_model_real_get_item_link;
428 * GMenuModel::items-changed:
429 * @model: the #GMenuModel that is changing
430 * @position: the position of the change
431 * @removed: the number of items removed
432 * @added: the number of items added
434 * Emitted when a change has occured to the menu.
436 * The only changes that can occur to a menu is that items are removed
437 * or added. Items may not change (except by being removed and added
438 * back in the same location). This signal is capable of describing
439 * both of those changes (at the same time).
441 * The signal means that starting at the index @position, @removed
442 * items were removed and @added items were added in their place. If
443 * @removed is zero then only items were added. If @added is zero
444 * then only items were removed.
446 * As an example, if the menu contains items a, b, c, d (in that
447 * order) and the signal (2, 1, 3) occurs then the new composition of
448 * the menu will be a, b, _, _, _, d (with each _ representing some
451 * Signal handlers may query the model (particularly the added items)
452 * and expect to see the results of the modification that is being
453 * reported. The signal is emitted after the modification.
455 g_menu_model_items_changed_signal =
456 g_signal_new ("items-changed", G_TYPE_MENU_MODEL,
457 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
458 g_cclosure_marshal_generic, G_TYPE_NONE,
459 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT);
463 * g_menu_model_is_mutable:
464 * @model: a #GMenuModel
466 * Queries if @model is mutable.
468 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
469 * signal. Consumers of the model may make optimisations accordingly.
471 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
477 g_menu_model_is_mutable (GMenuModel *model)
479 return G_MENU_MODEL_GET_CLASS (model)
480 ->is_mutable (model);
484 * g_menu_model_get_n_items:
485 * @model: a #GMenuModel
487 * Query the number of items in @model.
489 * Returns: the number of items
494 g_menu_model_get_n_items (GMenuModel *model)
496 return G_MENU_MODEL_GET_CLASS (model)
497 ->get_n_items (model);
501 * g_menu_model_iterate_item_attributes:
502 * @model: a #GMenuModel
503 * @item_index: the index of the item
505 * Creates a #GMenuAttributeIter to iterate over the attributes of
506 * the item at position @item_index in @model.
508 * You must free the iterator with g_object_unref() when you are done.
510 * Returns: (transfer full): a new #GMenuAttributeIter
515 g_menu_model_iterate_item_attributes (GMenuModel *model,
518 return G_MENU_MODEL_GET_CLASS (model)
519 ->iterate_item_attributes (model, item_index);
523 * g_menu_model_get_item_attribute_value:
524 * @model: a #GMenuModel
525 * @item_index: the index of the item
526 * @attribute: the attribute to query
527 * @expected_type: (allow-none): the expected type of the attribute, or
530 * Queries the item at position @item_index in @model for the attribute
531 * specified by @attribute.
533 * If @expected_type is non-%NULL then it specifies the expected type of
534 * the attribute. If it is %NULL then any type will be accepted.
536 * If the attribute exists and matches @expected_type (or if the
537 * expected type is unspecified) then the value is returned.
539 * If the attribute does not exist, or does not match the expected type
540 * then %NULL is returned.
542 * Returns: (transfer full): the value of the attribute
547 g_menu_model_get_item_attribute_value (GMenuModel *model,
549 const gchar *attribute,
550 const GVariantType *expected_type)
552 return G_MENU_MODEL_GET_CLASS (model)
553 ->get_item_attribute_value (model, item_index, attribute, expected_type);
557 * g_menu_model_get_item_attribute:
558 * @model: a #GMenuModel
559 * @item_index: the index of the item
560 * @attribute: the attribute to query
561 * @format_string: a #GVariant format string
562 * @...: positional parameters, as per @format_string
564 * Queries item at position @item_index in @model for the attribute
565 * specified by @attribute.
567 * If the attribute exists and matches the #GVariantType corresponding
568 * to @format_string then @format_string is used to deconstruct the
569 * value into the positional parameters and %TRUE is returned.
571 * If the attribute does not exist, or it does exist but has the wrong
572 * type, then the positional parameters are ignored and %FALSE is
575 * This function is a mix of g_menu_model_get_item_attribute_value() and
576 * g_variant_get(), followed by a g_variant_unref(). As such,
577 * @format_string must make a complete copy of the data (since the
578 * #GVariant may go away after the call to g_variant_unref()). In
579 * particular, no '&' characters are allowed in @format_string.
581 * Returns: %TRUE if the named attribute was found with the expected
587 g_menu_model_get_item_attribute (GMenuModel *model,
589 const gchar *attribute,
590 const gchar *format_string,
596 value = g_menu_model_get_item_attribute_value (model, item_index, attribute, NULL);
601 if (!g_variant_check_format_string (value, format_string, TRUE))
603 g_variant_unref (value);
607 va_start (ap, format_string);
608 g_variant_get_va (value, format_string, NULL, &ap);
609 g_variant_unref (value);
616 * g_menu_model_iterate_item_links:
617 * @model: a #GMenuModel
618 * @item_index: the index of the item
620 * Creates a #GMenuLinkIter to iterate over the links of the item at
621 * position @item_index in @model.
623 * You must free the iterator with g_object_unref() when you are done.
625 * Returns: (transfer full): a new #GMenuLinkIter
630 g_menu_model_iterate_item_links (GMenuModel *model,
633 return G_MENU_MODEL_GET_CLASS (model)
634 ->iterate_item_links (model, item_index);
638 * g_menu_model_get_item_link:
639 * @model: a #GMenuModel
640 * @item_index: the index of the item
641 * @link: the link to query
643 * Queries the item at position @item_index in @model for the link
644 * specified by @link.
646 * If the link exists, the linked #GMenuModel is returned. If the link
647 * does not exist, %NULL is returned.
649 * Returns: (transfer full): the linked #GMenuModel, or %NULL
654 g_menu_model_get_item_link (GMenuModel *model,
658 return G_MENU_MODEL_GET_CLASS (model)
659 ->get_item_link (model, item_index, link);
663 * g_menu_model_items_changed:
664 * @model: a #GMenuModel
665 * @position: the position of the change
666 * @removed: the number of items removed
667 * @added: the number of items added
669 * Requests emission of the #GMenuModel::items-changed signal on @model.
671 * This function should never be called except by #GMenuModel
672 * subclasses. Any other calls to this function will very likely lead
673 * to a violation of the interface of the model.
675 * The implementation should update its internal representation of the
676 * menu before emitting the signal. The implementation should further
677 * expect to receive queries about the new state of the menu (and
678 * particularly added menu items) while signal handlers are running.
680 * The implementation must dispatch this call directly from a mainloop
681 * entry and not in response to calls -- particularly those from the
682 * #GMenuModel API. Said another way: the menu must not change while
683 * user code is running without returning to the mainloop.
688 g_menu_model_items_changed (GMenuModel *model,
693 g_signal_emit (model, g_menu_model_items_changed_signal, 0, position, removed, added);
696 struct _GMenuAttributeIterPrivate
703 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuAttributeIter, g_menu_attribute_iter, G_TYPE_OBJECT)
706 * g_menu_attribute_iter_get_next:
707 * @iter: a #GMenuAttributeIter
708 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
709 * @value: (out) (allow-none) (transfer full): the attribute value
711 * This function combines g_menu_attribute_iter_next() with
712 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
714 * First the iterator is advanced to the next (possibly first) attribute.
715 * If that fails, then %FALSE is returned and there are no other
718 * If successful, @name and @value are set to the name and value of the
719 * attribute that has just been advanced to. At this point,
720 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
721 * return the same values again.
723 * The value returned in @name remains valid for as long as the iterator
724 * remains at the current position. The value returned in @value must
725 * be unreffed using g_variant_unref() when it is no longer in use.
727 * Returns: %TRUE on success, or %FALSE if there is no additional
733 g_menu_attribute_iter_get_next (GMenuAttributeIter *iter,
734 const gchar **out_name,
739 if (iter->priv->value)
741 g_variant_unref (iter->priv->value);
742 iter->priv->value = NULL;
745 iter->priv->valid = G_MENU_ATTRIBUTE_ITER_GET_CLASS (iter)
746 ->get_next (iter, &name, &iter->priv->value);
748 if (iter->priv->valid)
750 iter->priv->name = g_quark_from_string (name);
752 *out_name = g_quark_to_string (iter->priv->name);
755 *value = g_variant_ref (iter->priv->value);
758 return iter->priv->valid;
762 * g_menu_attribute_iter_next:
763 * @iter: a #GMenuAttributeIter
765 * Attempts to advance the iterator to the next (possibly first)
768 * %TRUE is returned on success, or %FALSE if there are no more
771 * You must call this function when you first acquire the iterator
772 * to advance it to the first attribute (and determine if the first
773 * attribute exists at all).
775 * Returns: %TRUE on success, or %FALSE when there are no more attributes
780 g_menu_attribute_iter_next (GMenuAttributeIter *iter)
782 return g_menu_attribute_iter_get_next (iter, NULL, NULL);
786 * g_menu_attribute_iter_get_name:
787 * @iter: a #GMenuAttributeIter
789 * Gets the name of the attribute at the current iterator position, as
792 * The iterator is not advanced.
794 * Returns: the name of the attribute
799 g_menu_attribute_iter_get_name (GMenuAttributeIter *iter)
801 g_return_val_if_fail (iter->priv->valid, 0);
803 return g_quark_to_string (iter->priv->name);
807 * g_menu_attribute_iter_get_value:
808 * @iter: a #GMenuAttributeIter
810 * Gets the value of the attribute at the current iterator position.
812 * The iterator is not advanced.
814 * Returns: (transfer full): the value of the current attribute
819 g_menu_attribute_iter_get_value (GMenuAttributeIter *iter)
821 g_return_val_if_fail (iter->priv->valid, NULL);
823 return g_variant_ref (iter->priv->value);
827 g_menu_attribute_iter_finalize (GObject *object)
829 GMenuAttributeIter *iter = G_MENU_ATTRIBUTE_ITER (object);
831 if (iter->priv->value)
832 g_variant_unref (iter->priv->value);
834 G_OBJECT_CLASS (g_menu_attribute_iter_parent_class)
839 g_menu_attribute_iter_init (GMenuAttributeIter *iter)
841 iter->priv = g_menu_attribute_iter_get_instance_private (iter);
845 g_menu_attribute_iter_class_init (GMenuAttributeIterClass *class)
847 GObjectClass *object_class = G_OBJECT_CLASS (class);
849 object_class->finalize = g_menu_attribute_iter_finalize;
852 struct _GMenuLinkIterPrivate
859 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuLinkIter, g_menu_link_iter, G_TYPE_OBJECT)
862 * g_menu_link_iter_get_next:
863 * @iter: a #GMenuLinkIter
864 * @out_link: (out) (allow-none) (transfer none): the name of the link
865 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
867 * This function combines g_menu_link_iter_next() with
868 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
870 * First the iterator is advanced to the next (possibly first) link.
871 * If that fails, then %FALSE is returned and there are no other effects.
873 * If successful, @out_link and @value are set to the name and #GMenuModel
874 * of the link that has just been advanced to. At this point,
875 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
878 * The value returned in @out_link remains valid for as long as the iterator
879 * remains at the current position. The value returned in @value must
880 * be unreffed using g_object_unref() when it is no longer in use.
882 * Returns: %TRUE on success, or %FALSE if there is no additional link
887 g_menu_link_iter_get_next (GMenuLinkIter *iter,
888 const gchar **out_link,
893 if (iter->priv->value)
895 g_object_unref (iter->priv->value);
896 iter->priv->value = NULL;
899 iter->priv->valid = G_MENU_LINK_ITER_GET_CLASS (iter)
900 ->get_next (iter, &name, &iter->priv->value);
902 if (iter->priv->valid)
904 g_assert (name != NULL);
906 iter->priv->name = g_quark_from_string (name);
908 *out_link = g_quark_to_string (iter->priv->name);
911 *value = g_object_ref (iter->priv->value);
914 return iter->priv->valid;
918 * g_menu_link_iter_next:
919 * @iter: a #GMenuLinkIter
921 * Attempts to advance the iterator to the next (possibly first)
924 * %TRUE is returned on success, or %FALSE if there are no more links.
926 * You must call this function when you first acquire the iterator to
927 * advance it to the first link (and determine if the first link exists
930 * Returns: %TRUE on success, or %FALSE when there are no more links
935 g_menu_link_iter_next (GMenuLinkIter *iter)
937 return g_menu_link_iter_get_next (iter, NULL, NULL);
941 * g_menu_link_iter_get_name:
942 * @iter: a #GMenuLinkIter
944 * Gets the name of the link at the current iterator position.
946 * The iterator is not advanced.
948 * Returns: the type of the link
953 g_menu_link_iter_get_name (GMenuLinkIter *iter)
955 g_return_val_if_fail (iter->priv->valid, 0);
957 return g_quark_to_string (iter->priv->name);
961 * g_menu_link_iter_get_value:
962 * @iter: a #GMenuLinkIter
964 * Gets the linked #GMenuModel at the current iterator position.
966 * The iterator is not advanced.
968 * Returns: (transfer full): the #GMenuModel that is linked to
973 g_menu_link_iter_get_value (GMenuLinkIter *iter)
975 g_return_val_if_fail (iter->priv->valid, NULL);
977 return g_object_ref (iter->priv->value);
981 g_menu_link_iter_finalize (GObject *object)
983 GMenuLinkIter *iter = G_MENU_LINK_ITER (object);
985 if (iter->priv->value)
986 g_object_unref (iter->priv->value);
988 G_OBJECT_CLASS (g_menu_link_iter_parent_class)
993 g_menu_link_iter_init (GMenuLinkIter *iter)
995 iter->priv = g_menu_link_iter_get_instance_private (iter);
999 g_menu_link_iter_class_init (GMenuLinkIterClass *class)
1001 GObjectClass *object_class = G_OBJECT_CLASS (class);
1003 object_class->finalize = g_menu_link_iter_finalize;