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
31 * @see_also: #GActionGroup
33 * #GMenuModel represents the contents of a menu -- an ordered list of
34 * menu items. The items are associated with actions, which can be
35 * activated through them. Items can be grouped in sections, and may
36 * have submenus associated with them. Both items and sections usually
37 * have some representation data, such as labels or icons. The type of
38 * the associated action (ie whether it is stateful, and what kind of
39 * state it has) can influence the representation of the item.
41 * The conceptual model of menus in #GMenuModel is hierarchical:
42 * sections and submenus are again represented by #GMenuModels.
43 * Menus themselves do not define their own roles. Rather, the role
44 * of a particular #GMenuModel is defined by the item that references
45 * it (or, in the case of the 'root' menu, is defined by the context
46 * in which it is used).
48 * As an example, consider the visible portions of the menu in
49 * <xref linkend="menu-example"/>.
51 * <figure id="menu-example">
52 * <title>An example menu</title>
53 * <graphic fileref="menu-example.png" format="PNG"></graphic>
56 * There are 8 "menus" visible in the screenshot: one menubar, two
57 * submenus and 5 sections:
59 * <listitem>the toplevel menubar (containing 4 items)</listitem>
60 * <listitem>the View submenu (containing 3 sections)</listitem>
61 * <listitem>the first section of the View submenu (containing 2 items)</listitem>
62 * <listitem>the second section of the View submenu (containing 1 item)</listitem>
63 * <listitem>the final section of the View submenu (containing 1 item)</listitem>
64 * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
65 * <listitem>the Sources section (containing 2 items)</listitem>
66 * <listitem>the Markup section (containing 2 items)</listitem>
69 * <xref linkend="menu-model"/> illustrates the conceptual connection between
70 * these 8 menus. Each large block in the figure represents a menu and the
71 * smaller blocks within the large block represent items in that menu. Some
72 * items contain references to other menus.
74 * <figure id="menu-model">
75 * <title>A menu model</title>
76 * <graphic fileref="menu-model.png" format="PNG"></graphic>
79 * Notice that the separators visible in <xref linkend="menu-example"/>
80 * appear nowhere in <xref linkend="menu-model"/>. This is because
81 * separators are not explicitly represented in the menu model. Instead,
82 * a separator is inserted between any two non-empty sections of a menu.
83 * Section items can have labels just like any other item. In that case,
84 * a display system may show a section header instead of a separator.
86 * The motivation for this abstract model of application controls is
87 * that modern user interfaces tend to make these controls available
88 * outside the application. Examples include global menus, jumplists,
89 * dash boards, etc. To support such uses, it is necessary to 'export'
90 * information about actions and their representation in menus, which
92 * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
94 * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
95 * do for #GActionGroup and #GMenuModel. The client-side counterparts
96 * to make use of the exported information are #GDBusActionGroup and
99 * The API of #GMenuModel is very generic, with iterators for the
100 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
101 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
102 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
103 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
104 * and %G_MENU_LINK_SUBMENU.
106 * Items in a #GMenuModel represent active controls if they refer to
107 * an action that can get activated when the user interacts with the
108 * menu item. The reference to the action is encoded by the string id
109 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
110 * identifies an action in an action group. Which action group(s) provide
111 * actions depends on the context in which the menu model is used.
112 * E.g. when the model is exported as the application menu of a
113 * #GtkApplication, actions can be application-wide or window-specific
114 * (and thus come from two different action groups). By convention, the
115 * application-wide actions have names that start with "app.", while the
116 * names of window-specific actions start with "win.".
118 * While a wide variety of stateful actions is possible, the following
119 * is the minimum that is expected to be supported by all users of exported
122 * <listitem>an action with no parameter type and no state</listitem>
123 * <listitem>an action with no parameter type and boolean state</listitem>
124 * <listitem>an action with string parameter type and string state</listitem>
127 * <formalpara><title>Stateless</title>
129 * A stateless action typically corresponds to an ordinary menu item.
132 * Selecting such a menu item will activate the action (with no parameter).
136 * <formalpara><title>Boolean State</title>
138 * An action with a boolean state will most typically be used with a "toggle"
139 * or "switch" menu item. The state can be set directly, but activating the
140 * action (with no parameter) results in the state being toggled.
143 * Selecting a toggle menu item will activate the action. The menu item should
144 * be rendered as "checked" when the state is true.
148 * <formalpara><title>String Parameter and State</title>
150 * Actions with string parameters and state will most typically be used to
151 * represent an enumerated choice over the items available for a group of
152 * radio menu items. Activating the action with a string parameter is
153 * equivalent to setting that parameter as the state.
156 * Radio menu items, in addition to being associated with the action, will
157 * have a target value. Selecting that menu item will result in activation
158 * of the action with the target value as the parameter. The menu item should
159 * be rendered as "selected" when the state of the action is equal to the
160 * target value of the menu item.
168 * #GMenuModel is an opaque structure type. You must access it using the
175 * GMenuAttributeIter:
177 * #GMenuAttributeIter is an opaque structure type. You must access it
178 * using the functions below.
186 * #GMenuLinkIter is an opaque structure type. You must access it using
187 * the functions below.
194 GMenuLinkIter parent_instance;
199 typedef GMenuLinkIterClass GMenuLinkHashIterClass;
201 static GType g_menu_link_hash_iter_get_type (void);
203 G_DEFINE_TYPE (GMenuLinkHashIter, g_menu_link_hash_iter, G_TYPE_MENU_LINK_ITER)
206 g_menu_link_hash_iter_get_next (GMenuLinkIter *link_iter,
207 const gchar **out_name,
210 GMenuLinkHashIter *iter = (GMenuLinkHashIter *) link_iter;
211 gpointer keyptr, valueptr;
213 if (!g_hash_table_iter_next (&iter->iter, &keyptr, &valueptr))
217 *value = g_object_ref (valueptr);
223 g_menu_link_hash_iter_finalize (GObject *object)
225 GMenuLinkHashIter *iter = (GMenuLinkHashIter *) object;
227 g_hash_table_unref (iter->table);
229 G_OBJECT_CLASS (g_menu_link_hash_iter_parent_class)
234 g_menu_link_hash_iter_init (GMenuLinkHashIter *iter)
239 g_menu_link_hash_iter_class_init (GMenuLinkHashIterClass *class)
241 GObjectClass *object_class = G_OBJECT_CLASS (class);
243 object_class->finalize = g_menu_link_hash_iter_finalize;
244 class->get_next = g_menu_link_hash_iter_get_next;
250 GMenuAttributeIter parent_instance;
253 } GMenuAttributeHashIter;
255 typedef GMenuAttributeIterClass GMenuAttributeHashIterClass;
257 static GType g_menu_attribute_hash_iter_get_type (void);
259 G_DEFINE_TYPE (GMenuAttributeHashIter, g_menu_attribute_hash_iter, G_TYPE_MENU_ATTRIBUTE_ITER)
262 g_menu_attribute_hash_iter_get_next (GMenuAttributeIter *attr_iter,
266 GMenuAttributeHashIter *iter = (GMenuAttributeHashIter *) attr_iter;
267 gpointer keyptr, valueptr;
269 if (!g_hash_table_iter_next (&iter->iter, &keyptr, &valueptr))
274 *value = g_variant_ref (valueptr);
280 g_menu_attribute_hash_iter_finalize (GObject *object)
282 GMenuAttributeHashIter *iter = (GMenuAttributeHashIter *) object;
284 g_hash_table_unref (iter->table);
286 G_OBJECT_CLASS (g_menu_attribute_hash_iter_parent_class)
291 g_menu_attribute_hash_iter_init (GMenuAttributeHashIter *iter)
296 g_menu_attribute_hash_iter_class_init (GMenuAttributeHashIterClass *class)
298 GObjectClass *object_class = G_OBJECT_CLASS (class);
300 object_class->finalize = g_menu_attribute_hash_iter_finalize;
301 class->get_next = g_menu_attribute_hash_iter_get_next;
304 G_DEFINE_ABSTRACT_TYPE (GMenuModel, g_menu_model, G_TYPE_OBJECT)
307 static guint g_menu_model_items_changed_signal;
309 static GMenuAttributeIter *
310 g_menu_model_real_iterate_item_attributes (GMenuModel *model,
313 GHashTable *table = NULL;
314 GMenuAttributeIter *result;
316 G_MENU_MODEL_GET_CLASS (model)->get_item_attributes (model, item_index, &table);
320 GMenuAttributeHashIter *iter = g_object_new (g_menu_attribute_hash_iter_get_type (), NULL);
321 g_hash_table_iter_init (&iter->iter, table);
322 iter->table = g_hash_table_ref (table);
323 result = G_MENU_ATTRIBUTE_ITER (iter);
327 g_critical ("GMenuModel implementation '%s' doesn't override iterate_item_attributes() "
328 "and fails to return sane values from get_item_attributes()",
329 G_OBJECT_TYPE_NAME (model));
334 g_hash_table_unref (table);
340 g_menu_model_real_get_item_attribute_value (GMenuModel *model,
342 const gchar *attribute,
343 const GVariantType *expected_type)
345 GHashTable *table = NULL;
346 GVariant *value = NULL;
348 G_MENU_MODEL_GET_CLASS (model)
349 ->get_item_attributes (model, item_index, &table);
353 value = g_hash_table_lookup (table, attribute);
357 if (expected_type == NULL || g_variant_is_of_type (value, expected_type))
358 value = g_variant_ref (value);
364 g_assert_not_reached ();
367 g_hash_table_unref (table);
372 static GMenuLinkIter *
373 g_menu_model_real_iterate_item_links (GMenuModel *model,
376 GHashTable *table = NULL;
377 GMenuLinkIter *result;
379 G_MENU_MODEL_GET_CLASS (model)
380 ->get_item_links (model, item_index, &table);
384 GMenuLinkHashIter *iter = g_object_new (g_menu_link_hash_iter_get_type (), NULL);
385 g_hash_table_iter_init (&iter->iter, table);
386 iter->table = g_hash_table_ref (table);
387 result = G_MENU_LINK_ITER (iter);
391 g_critical ("GMenuModel implementation '%s' doesn't override iterate_item_links() "
392 "and fails to return sane values from get_item_links()",
393 G_OBJECT_TYPE_NAME (model));
398 g_hash_table_unref (table);
404 g_menu_model_real_get_item_link (GMenuModel *model,
408 GHashTable *table = NULL;
409 GMenuModel *value = NULL;
411 G_MENU_MODEL_GET_CLASS (model)
412 ->get_item_links (model, item_index, &table);
415 value = g_hash_table_lookup (table, link);
417 g_assert_not_reached ();
420 g_object_ref (value);
423 g_hash_table_unref (table);
429 g_menu_model_init (GMenuModel *model)
434 g_menu_model_class_init (GMenuModelClass *class)
436 class->iterate_item_attributes = g_menu_model_real_iterate_item_attributes;
437 class->get_item_attribute_value = g_menu_model_real_get_item_attribute_value;
438 class->iterate_item_links = g_menu_model_real_iterate_item_links;
439 class->get_item_link = g_menu_model_real_get_item_link;
442 * GMenuModel::items-changed:
443 * @model: the #GMenuModel that is changing
444 * @position: the position of the change
445 * @removed: the number of items removed
446 * @added: the number of items added
448 * Emitted when a change has occured to the menu.
450 * The only changes that can occur to a menu is that items are removed
451 * or added. Items may not change (except by being removed and added
452 * back in the same location). This signal is capable of describing
453 * both of those changes (at the same time).
455 * The signal means that starting at the index @position, @removed
456 * items were removed and @added items were added in their place. If
457 * @removed is zero then only items were added. If @added is zero
458 * then only items were removed.
460 * As an example, if the menu contains items a, b, c, d (in that
461 * order) and the signal (2, 1, 3) occurs then the new composition of
462 * the menu will be a, b, _, _, _, d (with each _ representing some
465 * Signal handlers may query the model (particularly the added items)
466 * and expect to see the results of the modification that is being
467 * reported. The signal is emitted after the modification.
469 g_menu_model_items_changed_signal =
470 g_signal_new ("items-changed", G_TYPE_MENU_MODEL,
471 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
472 g_cclosure_marshal_generic, G_TYPE_NONE,
473 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT);
477 * g_menu_model_is_mutable:
478 * @model: a #GMenuModel
480 * Queries if @model is mutable.
482 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
483 * signal. Consumers of the model may make optimisations accordingly.
485 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
491 g_menu_model_is_mutable (GMenuModel *model)
493 return G_MENU_MODEL_GET_CLASS (model)
494 ->is_mutable (model);
498 * g_menu_model_get_n_items:
499 * @model: a #GMenuModel
501 * Query the number of items in @model.
503 * Returns: the number of items
508 g_menu_model_get_n_items (GMenuModel *model)
510 return G_MENU_MODEL_GET_CLASS (model)
511 ->get_n_items (model);
515 * g_menu_model_iterate_item_attributes:
516 * @model: a #GMenuModel
517 * @item_index: the index of the item
519 * Creates a #GMenuAttributeIter to iterate over the attributes of
520 * the item at position @item_index in @model.
522 * You must free the iterator with g_object_unref() when you are done.
524 * Returns: (transfer full): a new #GMenuAttributeIter
529 g_menu_model_iterate_item_attributes (GMenuModel *model,
532 return G_MENU_MODEL_GET_CLASS (model)
533 ->iterate_item_attributes (model, item_index);
537 * g_menu_model_get_item_attribute_value:
538 * @model: a #GMenuModel
539 * @item_index: the index of the item
540 * @attribute: the attribute to query
541 * @expected_type: (allow-none): the expected type of the attribute, or
544 * Queries the item at position @item_index in @model for the attribute
545 * specified by @attribute.
547 * If @expected_type is non-%NULL then it specifies the expected type of
548 * the attribute. If it is %NULL then any type will be accepted.
550 * If the attribute exists and matches @expected_type (or if the
551 * expected type is unspecified) then the value is returned.
553 * If the attribute does not exist, or does not match the expected type
554 * then %NULL is returned.
556 * Returns: (transfer full): the value of the attribute
561 g_menu_model_get_item_attribute_value (GMenuModel *model,
563 const gchar *attribute,
564 const GVariantType *expected_type)
566 return G_MENU_MODEL_GET_CLASS (model)
567 ->get_item_attribute_value (model, item_index, attribute, expected_type);
571 * g_menu_model_get_item_attribute:
572 * @model: a #GMenuModel
573 * @item_index: the index of the item
574 * @attribute: the attribute to query
575 * @format_string: a #GVariant format string
576 * @...: positional parameters, as per @format_string
578 * Queries item at position @item_index in @model for the attribute
579 * specified by @attribute.
581 * If the attribute exists and matches the #GVariantType corresponding
582 * to @format_string then @format_string is used to deconstruct the
583 * value into the positional parameters and %TRUE is returned.
585 * If the attribute does not exist, or it does exist but has the wrong
586 * type, then the positional parameters are ignored and %FALSE is
589 * This function is a mix of g_menu_model_get_item_attribute_value() and
590 * g_variant_get(), followed by a g_variant_unref(). As such,
591 * @format_string must make a complete copy of the data (since the
592 * #GVariant may go away after the call to g_variant_unref()). In
593 * particular, no '&' characters are allowed in @format_string.
595 * Returns: %TRUE if the named attribute was found with the expected
601 g_menu_model_get_item_attribute (GMenuModel *model,
603 const gchar *attribute,
604 const gchar *format_string,
610 value = g_menu_model_get_item_attribute_value (model, item_index, attribute, NULL);
615 if (!g_variant_check_format_string (value, format_string, TRUE))
617 g_variant_unref (value);
621 va_start (ap, format_string);
622 g_variant_get_va (value, format_string, NULL, &ap);
623 g_variant_unref (value);
630 * g_menu_model_iterate_item_links:
631 * @model: a #GMenuModel
632 * @item_index: the index of the item
634 * Creates a #GMenuLinkIter to iterate over the links of the item at
635 * position @item_index in @model.
637 * You must free the iterator with g_object_unref() when you are done.
639 * Returns: (transfer full): a new #GMenuLinkIter
644 g_menu_model_iterate_item_links (GMenuModel *model,
647 return G_MENU_MODEL_GET_CLASS (model)
648 ->iterate_item_links (model, item_index);
652 * g_menu_model_get_item_link:
653 * @model: a #GMenuModel
654 * @item_index: the index of the item
655 * @link: the link to query
657 * Queries the item at position @item_index in @model for the link
658 * specified by @link.
660 * If the link exists, the linked #GMenuModel is returned. If the link
661 * does not exist, %NULL is returned.
663 * Returns: (transfer full): the linked #GMenuModel, or %NULL
668 g_menu_model_get_item_link (GMenuModel *model,
672 return G_MENU_MODEL_GET_CLASS (model)
673 ->get_item_link (model, item_index, link);
677 * g_menu_model_items_changed:
678 * @model: a #GMenuModel
679 * @position: the position of the change
680 * @removed: the number of items removed
681 * @added: the number of items added
683 * Requests emission of the #GMenuModel::items-changed signal on @model.
685 * This function should never be called except by #GMenuModel
686 * subclasses. Any other calls to this function will very likely lead
687 * to a violation of the interface of the model.
689 * The implementation should update its internal representation of the
690 * menu before emitting the signal. The implementation should further
691 * expect to receive queries about the new state of the menu (and
692 * particularly added menu items) while signal handlers are running.
694 * The implementation must dispatch this call directly from a mainloop
695 * entry and not in response to calls -- particularly those from the
696 * #GMenuModel API. Said another way: the menu must not change while
697 * user code is running without returning to the mainloop.
702 g_menu_model_items_changed (GMenuModel *model,
707 g_signal_emit (model, g_menu_model_items_changed_signal, 0, position, removed, added);
710 struct _GMenuAttributeIterPrivate
717 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuAttributeIter, g_menu_attribute_iter, G_TYPE_OBJECT)
720 * g_menu_attribute_iter_get_next:
721 * @iter: a #GMenuAttributeIter
722 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
723 * @value: (out) (allow-none) (transfer full): the attribute value
725 * This function combines g_menu_attribute_iter_next() with
726 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
728 * First the iterator is advanced to the next (possibly first) attribute.
729 * If that fails, then %FALSE is returned and there are no other
732 * If successful, @name and @value are set to the name and value of the
733 * attribute that has just been advanced to. At this point,
734 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
735 * return the same values again.
737 * The value returned in @name remains valid for as long as the iterator
738 * remains at the current position. The value returned in @value must
739 * be unreffed using g_variant_unref() when it is no longer in use.
741 * Returns: %TRUE on success, or %FALSE if there is no additional
747 g_menu_attribute_iter_get_next (GMenuAttributeIter *iter,
748 const gchar **out_name,
753 if (iter->priv->value)
755 g_variant_unref (iter->priv->value);
756 iter->priv->value = NULL;
759 iter->priv->valid = G_MENU_ATTRIBUTE_ITER_GET_CLASS (iter)
760 ->get_next (iter, &name, &iter->priv->value);
762 if (iter->priv->valid)
764 iter->priv->name = g_quark_from_string (name);
766 *out_name = g_quark_to_string (iter->priv->name);
769 *value = g_variant_ref (iter->priv->value);
772 return iter->priv->valid;
776 * g_menu_attribute_iter_next:
777 * @iter: a #GMenuAttributeIter
779 * Attempts to advance the iterator to the next (possibly first)
782 * %TRUE is returned on success, or %FALSE if there are no more
785 * You must call this function when you first acquire the iterator
786 * to advance it to the first attribute (and determine if the first
787 * attribute exists at all).
789 * Returns: %TRUE on success, or %FALSE when there are no more attributes
794 g_menu_attribute_iter_next (GMenuAttributeIter *iter)
796 return g_menu_attribute_iter_get_next (iter, NULL, NULL);
800 * g_menu_attribute_iter_get_name:
801 * @iter: a #GMenuAttributeIter
803 * Gets the name of the attribute at the current iterator position, as
806 * The iterator is not advanced.
808 * Returns: the name of the attribute
813 g_menu_attribute_iter_get_name (GMenuAttributeIter *iter)
815 g_return_val_if_fail (iter->priv->valid, 0);
817 return g_quark_to_string (iter->priv->name);
821 * g_menu_attribute_iter_get_value:
822 * @iter: a #GMenuAttributeIter
824 * Gets the value of the attribute at the current iterator position.
826 * The iterator is not advanced.
828 * Returns: (transfer full): the value of the current attribute
833 g_menu_attribute_iter_get_value (GMenuAttributeIter *iter)
835 g_return_val_if_fail (iter->priv->valid, NULL);
837 return g_variant_ref (iter->priv->value);
841 g_menu_attribute_iter_finalize (GObject *object)
843 GMenuAttributeIter *iter = G_MENU_ATTRIBUTE_ITER (object);
845 if (iter->priv->value)
846 g_variant_unref (iter->priv->value);
848 G_OBJECT_CLASS (g_menu_attribute_iter_parent_class)
853 g_menu_attribute_iter_init (GMenuAttributeIter *iter)
855 iter->priv = g_menu_attribute_iter_get_instance_private (iter);
859 g_menu_attribute_iter_class_init (GMenuAttributeIterClass *class)
861 GObjectClass *object_class = G_OBJECT_CLASS (class);
863 object_class->finalize = g_menu_attribute_iter_finalize;
866 struct _GMenuLinkIterPrivate
873 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuLinkIter, g_menu_link_iter, G_TYPE_OBJECT)
876 * g_menu_link_iter_get_next:
877 * @iter: a #GMenuLinkIter
878 * @out_link: (out) (allow-none) (transfer none): the name of the link
879 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
881 * This function combines g_menu_link_iter_next() with
882 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
884 * First the iterator is advanced to the next (possibly first) link.
885 * If that fails, then %FALSE is returned and there are no other effects.
887 * If successful, @out_link and @value are set to the name and #GMenuModel
888 * of the link that has just been advanced to. At this point,
889 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
892 * The value returned in @out_link remains valid for as long as the iterator
893 * remains at the current position. The value returned in @value must
894 * be unreffed using g_object_unref() when it is no longer in use.
896 * Returns: %TRUE on success, or %FALSE if there is no additional link
901 g_menu_link_iter_get_next (GMenuLinkIter *iter,
902 const gchar **out_link,
907 if (iter->priv->value)
909 g_object_unref (iter->priv->value);
910 iter->priv->value = NULL;
913 iter->priv->valid = G_MENU_LINK_ITER_GET_CLASS (iter)
914 ->get_next (iter, &name, &iter->priv->value);
916 if (iter->priv->valid)
918 g_assert (name != NULL);
920 iter->priv->name = g_quark_from_string (name);
922 *out_link = g_quark_to_string (iter->priv->name);
925 *value = g_object_ref (iter->priv->value);
928 return iter->priv->valid;
932 * g_menu_link_iter_next:
933 * @iter: a #GMenuLinkIter
935 * Attempts to advance the iterator to the next (possibly first)
938 * %TRUE is returned on success, or %FALSE if there are no more links.
940 * You must call this function when you first acquire the iterator to
941 * advance it to the first link (and determine if the first link exists
944 * Returns: %TRUE on success, or %FALSE when there are no more links
949 g_menu_link_iter_next (GMenuLinkIter *iter)
951 return g_menu_link_iter_get_next (iter, NULL, NULL);
955 * g_menu_link_iter_get_name:
956 * @iter: a #GMenuLinkIter
958 * Gets the name of the link at the current iterator position.
960 * The iterator is not advanced.
962 * Returns: the type of the link
967 g_menu_link_iter_get_name (GMenuLinkIter *iter)
969 g_return_val_if_fail (iter->priv->valid, 0);
971 return g_quark_to_string (iter->priv->name);
975 * g_menu_link_iter_get_value:
976 * @iter: a #GMenuLinkIter
978 * Gets the linked #GMenuModel at the current iterator position.
980 * The iterator is not advanced.
982 * Returns: (transfer full): the #GMenuModel that is linked to
987 g_menu_link_iter_get_value (GMenuLinkIter *iter)
989 g_return_val_if_fail (iter->priv->valid, NULL);
991 return g_object_ref (iter->priv->value);
995 g_menu_link_iter_finalize (GObject *object)
997 GMenuLinkIter *iter = G_MENU_LINK_ITER (object);
999 if (iter->priv->value)
1000 g_object_unref (iter->priv->value);
1002 G_OBJECT_CLASS (g_menu_link_iter_parent_class)
1003 ->finalize (object);
1007 g_menu_link_iter_init (GMenuLinkIter *iter)
1009 iter->priv = g_menu_link_iter_get_instance_private (iter);
1013 g_menu_link_iter_class_init (GMenuLinkIterClass *class)
1015 GObjectClass *object_class = G_OBJECT_CLASS (class);
1017 object_class->finalize = g_menu_link_iter_finalize;