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>
32 * @short_description: A simple implementation of GMenuModel
34 * #GMenu is a simple implementation of #GMenuModel.
35 * You populate a #GMenu by adding #GMenuItem instances to it.
37 * There are some convenience functions to allow you to directly
38 * add items (avoiding #GMenuItem) for the common cases. To add
39 * a regular item, use g_menu_insert(). To add a section, use
40 * g_menu_insert_section(). To add a submenu, use
41 * g_menu_insert_submenu().
47 * #GMenu is an opaque structure type. You must access it using the
56 * #GMenuItem is an opaque structure type. You must access it using the
64 GObject parent_instance;
66 GHashTable *attributes;
71 typedef GObjectClass GMenuItemClass;
75 GMenuModel parent_instance;
81 typedef GMenuModelClass GMenuClass;
83 G_DEFINE_TYPE (GMenu, g_menu, G_TYPE_MENU_MODEL)
84 G_DEFINE_TYPE (GMenuItem, g_menu_item, G_TYPE_OBJECT)
88 GHashTable *attributes;
93 g_menu_is_mutable (GMenuModel *model)
95 GMenu *menu = G_MENU (model);
101 g_menu_get_n_items (GMenuModel *model)
103 GMenu *menu = G_MENU (model);
105 return menu->items->len;
109 g_menu_get_item_attributes (GMenuModel *model,
113 GMenu *menu = G_MENU (model);
115 *table = g_hash_table_ref (g_array_index (menu->items, struct item, position).attributes);
119 g_menu_get_item_links (GMenuModel *model,
123 GMenu *menu = G_MENU (model);
125 *table = g_hash_table_ref (g_array_index (menu->items, struct item, position).links);
129 * g_menu_insert_item:
131 * @position: the position at which to insert the item
132 * @item: the #GMenuItem to insert
134 * Inserts @item into @menu.
136 * The "insertion" is actually done by copying all of the attribute and
137 * link values of @item and using them to form a new item within @menu.
138 * As such, @item itself is not really inserted, but rather, a menu item
139 * that is exactly the same as the one presently described by @item.
141 * This means that @item is essentially useless after the insertion
142 * occurs. Any changes you make to it are ignored unless it is inserted
143 * again (at which point its updated values will be copied).
145 * You should probably just free @item once you're done.
147 * There are many convenience functions to take care of common cases.
148 * See g_menu_insert(), g_menu_insert_section() and
149 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
150 * each of these functions.
155 g_menu_insert_item (GMenu *menu,
159 struct item new_item;
161 g_return_if_fail (G_IS_MENU (menu));
162 g_return_if_fail (G_IS_MENU_ITEM (item));
164 if (position < 0 || position > menu->items->len)
165 position = menu->items->len;
167 new_item.attributes = g_hash_table_ref (item->attributes);
168 new_item.links = g_hash_table_ref (item->links);
171 g_array_insert_val (menu->items, position, new_item);
172 g_menu_model_items_changed (G_MENU_MODEL (menu), position, 0, 1);
176 * g_menu_prepend_item:
178 * @item: a #GMenuItem to prepend
180 * Prepends @item to the start of @menu.
182 * See g_menu_insert_item() for more information.
187 g_menu_prepend_item (GMenu *menu,
190 g_menu_insert_item (menu, 0, item);
194 * g_menu_append_item:
196 * @item: a #GMenuItem to append
198 * Appends @item to the end of @menu.
200 * See g_menu_insert_item() for more information.
205 g_menu_append_item (GMenu *menu,
208 g_menu_insert_item (menu, -1, item);
215 * Marks @menu as frozen.
217 * After the menu is frozen, it is an error to attempt to make any
218 * changes to it. In effect this means that the #GMenu API must no
221 * This function causes g_menu_model_is_mutable() to begin returning
222 * %FALSE, which has some positive performance implications.
227 g_menu_freeze (GMenu *menu)
229 g_return_if_fail (G_IS_MENU (menu));
231 menu->mutable = FALSE;
237 * Creates a new #GMenu.
239 * The new menu has no items.
241 * Returns: a new #GMenu
248 return g_object_new (G_TYPE_MENU, NULL);
254 * @position: the position at which to insert the item
255 * @label: (allow-none): the section label, or %NULL
256 * @detailed_action: (allow-none): the detailed action string, or %NULL
258 * Convenience function for inserting a normal menu item into @menu.
259 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
265 g_menu_insert (GMenu *menu,
268 const gchar *detailed_action)
270 GMenuItem *menu_item;
272 menu_item = g_menu_item_new (label, detailed_action);
273 g_menu_insert_item (menu, position, menu_item);
274 g_object_unref (menu_item);
280 * @label: (allow-none): the section label, or %NULL
281 * @detailed_action: (allow-none): the detailed action string, or %NULL
283 * Convenience function for prepending a normal menu item to the start
284 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
285 * flexible alternative.
290 g_menu_prepend (GMenu *menu,
292 const gchar *detailed_action)
294 g_menu_insert (menu, 0, label, detailed_action);
300 * @label: (allow-none): the section label, or %NULL
301 * @detailed_action: (allow-none): the detailed action string, or %NULL
303 * Convenience function for appending a normal menu item to the end of
304 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
305 * flexible alternative.
310 g_menu_append (GMenu *menu,
312 const gchar *detailed_action)
314 g_menu_insert (menu, -1, label, detailed_action);
318 * g_menu_insert_section:
320 * @position: the position at which to insert the item
321 * @label: (allow-none): the section label, or %NULL
322 * @section: a #GMenuModel with the items of the section
324 * Convenience function for inserting a section menu item into @menu.
325 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
326 * flexible alternative.
331 g_menu_insert_section (GMenu *menu,
336 GMenuItem *menu_item;
338 menu_item = g_menu_item_new_section (label, section);
339 g_menu_insert_item (menu, position, menu_item);
340 g_object_unref (menu_item);
345 * g_menu_prepend_section:
347 * @label: (allow-none): the section label, or %NULL
348 * @section: a #GMenuModel with the items of the section
350 * Convenience function for prepending a section menu item to the start
351 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
352 * a more flexible alternative.
357 g_menu_prepend_section (GMenu *menu,
361 g_menu_insert_section (menu, 0, label, section);
365 * g_menu_append_section:
367 * @label: (allow-none): the section label, or %NULL
368 * @section: a #GMenuModel with the items of the section
370 * Convenience function for appending a section menu item to the end of
371 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
372 * more flexible alternative.
377 g_menu_append_section (GMenu *menu,
381 g_menu_insert_section (menu, -1, label, section);
385 * g_menu_insert_submenu:
387 * @position: the position at which to insert the item
388 * @label: (allow-none): the section label, or %NULL
389 * @submenu: a #GMenuModel with the items of the submenu
391 * Convenience function for inserting a submenu menu item into @menu.
392 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
393 * flexible alternative.
398 g_menu_insert_submenu (GMenu *menu,
403 GMenuItem *menu_item;
405 menu_item = g_menu_item_new_submenu (label, submenu);
406 g_menu_insert_item (menu, position, menu_item);
407 g_object_unref (menu_item);
411 * g_menu_prepend_submenu:
413 * @label: (allow-none): the section label, or %NULL
414 * @submenu: a #GMenuModel with the items of the submenu
416 * Convenience function for prepending a submenu menu item to the start
417 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
418 * a more flexible alternative.
423 g_menu_prepend_submenu (GMenu *menu,
427 g_menu_insert_submenu (menu, 0, label, submenu);
431 * g_menu_append_submenu:
433 * @label: (allow-none): the section label, or %NULL
434 * @submenu: a #GMenuModel with the items of the submenu
436 * Convenience function for appending a submenu menu item to the end of
437 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
438 * more flexible alternative.
443 g_menu_append_submenu (GMenu *menu,
447 g_menu_insert_submenu (menu, -1, label, submenu);
451 g_menu_clear_item (struct item *item)
453 if (item->attributes != NULL)
454 g_hash_table_unref (item->attributes);
455 if (item->links != NULL)
456 g_hash_table_unref (item->links);
462 * @position: the position of the item to remove
464 * Removes an item from the menu.
466 * @position gives the index of the item to remove.
468 * It is an error if position is not in range the range from 0 to one
469 * less than the number of items in the menu.
471 * It is not possible to remove items by identity since items are added
472 * to the menu simply by copying their links and attributes (ie:
473 * identity of the item itself is not preserved).
478 g_menu_remove (GMenu *menu,
481 g_return_if_fail (G_IS_MENU (menu));
482 g_return_if_fail (0 <= position && position < menu->items->len);
484 g_menu_clear_item (&g_array_index (menu->items, struct item, position));
485 g_array_remove_index (menu->items, position);
486 g_menu_model_items_changed (G_MENU_MODEL (menu), position, 1, 0);
493 * Removes all items in the menu.
498 g_menu_remove_all (GMenu *menu)
502 g_return_if_fail (G_IS_MENU (menu));
503 n = menu->items->len;
505 for (i = 0; i < n; i++)
506 g_menu_clear_item (&g_array_index (menu->items, struct item, i));
507 g_array_set_size (menu->items, 0);
509 g_menu_model_items_changed (G_MENU_MODEL (menu), 0, n, 0);
513 g_menu_finalize (GObject *object)
515 GMenu *menu = G_MENU (object);
520 n_items = menu->items->len;
521 items = (struct item *) g_array_free (menu->items, FALSE);
522 for (i = 0; i < n_items; i++)
523 g_menu_clear_item (&items[i]);
526 G_OBJECT_CLASS (g_menu_parent_class)
531 g_menu_init (GMenu *menu)
533 menu->items = g_array_new (FALSE, FALSE, sizeof (struct item));
534 menu->mutable = TRUE;
538 g_menu_class_init (GMenuClass *class)
540 GMenuModelClass *model_class = G_MENU_MODEL_CLASS (class);
541 GObjectClass *object_class = G_OBJECT_CLASS (class);
543 object_class->finalize = g_menu_finalize;
545 model_class->is_mutable = g_menu_is_mutable;
546 model_class->get_n_items = g_menu_get_n_items;
547 model_class->get_item_attributes = g_menu_get_item_attributes;
548 model_class->get_item_links = g_menu_get_item_links;
553 g_menu_item_clear_cow (GMenuItem *menu_item)
562 new = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_variant_unref);
563 g_hash_table_iter_init (&iter, menu_item->attributes);
564 while (g_hash_table_iter_next (&iter, &key, &val))
565 g_hash_table_insert (new, g_strdup (key), g_variant_ref (val));
566 g_hash_table_unref (menu_item->attributes);
567 menu_item->attributes = new;
569 new = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_object_unref);
570 g_hash_table_iter_init (&iter, menu_item->links);
571 while (g_hash_table_iter_next (&iter, &key, &val))
572 g_hash_table_insert (new, g_strdup (key), g_object_ref (val));
573 g_hash_table_unref (menu_item->links);
574 menu_item->links = new;
576 menu_item->cow = FALSE;
581 g_menu_item_finalize (GObject *object)
583 GMenuItem *menu_item = G_MENU_ITEM (object);
585 g_hash_table_unref (menu_item->attributes);
586 g_hash_table_unref (menu_item->links);
588 G_OBJECT_CLASS (g_menu_item_parent_class)
593 g_menu_item_init (GMenuItem *menu_item)
595 menu_item->attributes = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_variant_unref);
596 menu_item->links = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, g_object_unref);
597 menu_item->cow = FALSE;
601 g_menu_item_class_init (GMenuItemClass *class)
603 class->finalize = g_menu_item_finalize;
606 /* We treat attribute names the same as GSettings keys:
607 * - only lowercase ascii, digits and '-'
608 * - must start with lowercase
609 * - must not end with '-'
610 * - no consecutive '-'
611 * - not longer than 1024 chars
614 valid_attribute_name (const gchar *name)
618 if (!g_ascii_islower (name[0]))
621 for (i = 1; name[i]; i++)
623 if (name[i] != '-' &&
624 !g_ascii_islower (name[i]) &&
625 !g_ascii_isdigit (name[i]))
628 if (name[i] == '-' && name[i + 1] == '-')
632 if (name[i - 1] == '-')
642 * g_menu_item_set_attribute_value:
643 * @menu_item: a #GMenuItem
644 * @attribute: the attribute to set
645 * @value: (allow-none): a #GVariant to use as the value, or %NULL
647 * Sets or unsets an attribute on @menu_item.
649 * The attribute to set or unset is specified by @attribute. This
650 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
651 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
653 * Attribute names are restricted to lowercase characters, numbers
654 * and '-'. Furthermore, the names must begin with a lowercase character,
655 * must not end with a '-', and must not contain consecutive dashes.
657 * must consist only of lowercase
658 * ASCII characters, digits and '-'.
660 * If @value is non-%NULL then it is used as the new value for the
661 * attribute. If @value is %NULL then the attribute is unset. If
662 * the @value #GVariant is floating, it is consumed.
664 * See also g_menu_item_set_attribute() for a more convenient way to do
670 g_menu_item_set_attribute_value (GMenuItem *menu_item,
671 const gchar *attribute,
674 g_return_if_fail (G_IS_MENU_ITEM (menu_item));
675 g_return_if_fail (attribute != NULL);
676 g_return_if_fail (valid_attribute_name (attribute));
678 g_menu_item_clear_cow (menu_item);
681 g_hash_table_insert (menu_item->attributes, g_strdup (attribute), g_variant_ref_sink (value));
683 g_hash_table_remove (menu_item->attributes, attribute);
687 * g_menu_item_set_attribute:
688 * @menu_item: a #GMenuItem
689 * @attribute: the attribute to set
690 * @format_string: (allow-none): a #GVariant format string, or %NULL
691 * @...: positional parameters, as per @format_string
693 * Sets or unsets an attribute on @menu_item.
695 * The attribute to set or unset is specified by @attribute. This
696 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
697 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
699 * Attribute names are restricted to lowercase characters, numbers
700 * and '-'. Furthermore, the names must begin with a lowercase character,
701 * must not end with a '-', and must not contain consecutive dashes.
703 * If @format_string is non-%NULL then the proper position parameters
704 * are collected to create a #GVariant instance to use as the attribute
705 * value. If it is %NULL then the positional parameterrs are ignored
706 * and the named attribute is unset.
708 * See also g_menu_item_set_attribute_value() for an equivalent call
709 * that directly accepts a #GVariant.
714 g_menu_item_set_attribute (GMenuItem *menu_item,
715 const gchar *attribute,
716 const gchar *format_string,
721 if (format_string != NULL)
725 va_start (ap, format_string);
726 value = g_variant_new_va (format_string, NULL, &ap);
732 g_menu_item_set_attribute_value (menu_item, attribute, value);
736 * g_menu_item_set_link:
737 * @menu_item: a #GMenuItem
738 * @link: type of link to establish or unset
739 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
741 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
743 * Links are used to establish a relationship between a particular menu
744 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
745 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
746 * is used to create a section. Other types of link can be used, but there
747 * is no guarantee that clients will be able to make sense of them.
748 * Link types are restricted to lowercase characters, numbers
749 * and '-'. Furthermore, the names must begin with a lowercase character,
750 * must not end with a '-', and must not contain consecutive dashes.
755 g_menu_item_set_link (GMenuItem *menu_item,
759 g_return_if_fail (G_IS_MENU_ITEM (menu_item));
760 g_return_if_fail (link != NULL);
761 g_return_if_fail (valid_attribute_name (link));
763 g_menu_item_clear_cow (menu_item);
766 g_hash_table_insert (menu_item->links, g_strdup (link), g_object_ref (model));
768 g_hash_table_remove (menu_item->links, link);
772 * g_menu_item_get_attribute_value:
773 * @menu_item: a #GMenuItem
774 * @attribute: the attribute name to query
775 * @expected_type: (allow-none): the expected type of the attribute
777 * Queries the named @attribute on @menu_item.
779 * If @expected_type is specified and the attribute does not have this
780 * type, %NULL is returned. %NULL is also returned if the attribute
781 * simply does not exist.
783 * Returns: (transfer full): the attribute value, or %NULL
788 g_menu_item_get_attribute_value (GMenuItem *menu_item,
789 const gchar *attribute,
790 const GVariantType *expected_type)
794 g_return_val_if_fail (G_IS_MENU_ITEM (menu_item), NULL);
795 g_return_val_if_fail (attribute != NULL, NULL);
797 value = g_hash_table_lookup (menu_item->attributes, attribute);
801 if (expected_type == NULL || g_variant_is_of_type (value, expected_type))
802 g_variant_ref (value);
811 * g_menu_item_get_attribute:
812 * @menu_item: a #GMenuItem
813 * @attribute: the attribute name to query
814 * @format_string: a #GVariant format string
815 * @...: positional parameters, as per @format_string
817 * Queries the named @attribute on @menu_item.
819 * If the attribute exists and matches the #GVariantType corresponding
820 * to @format_string then @format_string is used to deconstruct the
821 * value into the positional parameters and %TRUE is returned.
823 * If the attribute does not exist, or it does exist but has the wrong
824 * type, then the positional parameters are ignored and %FALSE is
827 * Returns: %TRUE if the named attribute was found with the expected
833 g_menu_item_get_attribute (GMenuItem *menu_item,
834 const gchar *attribute,
835 const gchar *format_string,
841 g_return_val_if_fail (G_IS_MENU_ITEM (menu_item), FALSE);
842 g_return_val_if_fail (attribute != NULL, FALSE);
843 g_return_val_if_fail (format_string != NULL, FALSE);
845 value = g_hash_table_lookup (menu_item->attributes, attribute);
850 if (!g_variant_check_format_string (value, format_string, FALSE))
853 va_start (ap, format_string);
854 g_variant_get_va (value, format_string, NULL, &ap);
861 * g_menu_item_get_link:
862 * @menu_item: a #GMenuItem
863 * @link: the link name to query
865 * Queries the named @link on @menu_item.
867 * Returns: (transfer full): the link, or %NULL
872 g_menu_item_get_link (GMenuItem *menu_item,
877 g_return_val_if_fail (G_IS_MENU_ITEM (menu_item), NULL);
878 g_return_val_if_fail (link != NULL, NULL);
879 g_return_val_if_fail (valid_attribute_name (link), NULL);
881 model = g_hash_table_lookup (menu_item->links, link);
884 g_object_ref (model);
890 * g_menu_item_set_label:
891 * @menu_item: a #GMenuItem
892 * @label: (allow-none): the label to set, or %NULL to unset
894 * Sets or unsets the "label" attribute of @menu_item.
896 * If @label is non-%NULL it is used as the label for the menu item. If
897 * it is %NULL then the label attribute is unset.
902 g_menu_item_set_label (GMenuItem *menu_item,
908 value = g_variant_new_string (label);
912 g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_LABEL, value);
916 * g_menu_item_set_submenu:
917 * @menu_item: a #GMenuItem
918 * @submenu: (allow-none): a #GMenuModel, or %NULL
920 * Sets or unsets the "submenu" link of @menu_item to @submenu.
922 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
925 * The effect of having one menu appear as a submenu of another is
926 * exactly as it sounds.
931 g_menu_item_set_submenu (GMenuItem *menu_item,
934 g_menu_item_set_link (menu_item, G_MENU_LINK_SUBMENU, submenu);
938 * g_menu_item_set_section:
939 * @menu_item: a #GMenuItem
940 * @section: (allow-none): a #GMenuModel, or %NULL
942 * Sets or unsets the "section" link of @menu_item to @section.
944 * The effect of having one menu appear as a section of another is
945 * exactly as it sounds: the items from @section become a direct part of
946 * the menu that @menu_item is added to. See g_menu_item_new_section()
947 * for more information about what it means for a menu item to be a
953 g_menu_item_set_section (GMenuItem *menu_item,
956 g_menu_item_set_link (menu_item, G_MENU_LINK_SECTION, section);
960 * g_menu_item_set_action_and_target_value:
961 * @menu_item: a #GMenuItem
962 * @action: (allow-none): the name of the action for this item
963 * @target_value: (allow-none): a #GVariant to use as the action target
965 * Sets or unsets the "action" and "target" attributes of @menu_item.
967 * If @action is %NULL then both the "action" and "target" attributes
968 * are unset (and @target_value is ignored).
970 * If @action is non-%NULL then the "action" attribute is set. The
971 * "target" attribute is then set to the value of @target_value if it is
972 * non-%NULL or unset otherwise.
974 * Normal menu items (ie: not submenu, section or other custom item
975 * types) are expected to have the "action" attribute set to identify
976 * the action that they are associated with. The state type of the
977 * action help to determine the disposition of the menu item. See
978 * #GAction and #GActionGroup for an overview of actions.
980 * In general, clicking on the menu item will result in activation of
981 * the named action with the "target" attribute given as the parameter
982 * to the action invocation. If the "target" attribute is not set then
983 * the action is invoked with no parameter.
985 * If the action has no state then the menu item is usually drawn as a
986 * plain menu item (ie: with no additional decoration).
988 * If the action has a boolean state then the menu item is usually drawn
989 * as a toggle menu item (ie: with a checkmark or equivalent
990 * indication). The item should be marked as 'toggled' or 'checked'
991 * when the boolean state is %TRUE.
993 * If the action has a string state then the menu item is usually drawn
994 * as a radio menu item (ie: with a radio bullet or equivalent
995 * indication). The item should be marked as 'selected' when the string
996 * state is equal to the value of the @target property.
998 * See g_menu_item_set_action_and_target() or
999 * g_menu_item_set_detailed_action() for two equivalent calls that are
1000 * probably more convenient for most uses.
1005 g_menu_item_set_action_and_target_value (GMenuItem *menu_item,
1006 const gchar *action,
1007 GVariant *target_value)
1009 GVariant *action_value;
1013 action_value = g_variant_new_string (action);
1017 action_value = NULL;
1018 target_value = NULL;
1021 g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_ACTION, action_value);
1022 g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_TARGET, target_value);
1026 * g_menu_item_set_action_and_target:
1027 * @menu_item: a #GMenuItem
1028 * @action: (allow-none): the name of the action for this item
1029 * @format_string: (allow-none): a GVariant format string
1030 * @...: positional parameters, as per @format_string
1032 * Sets or unsets the "action" and "target" attributes of @menu_item.
1034 * If @action is %NULL then both the "action" and "target" attributes
1035 * are unset (and @format_string is ignored along with the positional
1038 * If @action is non-%NULL then the "action" attribute is set.
1039 * @format_string is then inspected. If it is non-%NULL then the proper
1040 * position parameters are collected to create a #GVariant instance to
1041 * use as the target value. If it is %NULL then the positional
1042 * parameters are ignored and the "target" attribute is unset.
1044 * See also g_menu_item_set_action_and_target_value() for an equivalent
1045 * call that directly accepts a #GVariant. See
1046 * g_menu_item_set_detailed_action() for a more convenient version that
1047 * works with string-typed targets.
1049 * See also g_menu_item_set_action_and_target_value() for a
1050 * description of the semantics of the action and target attributes.
1055 g_menu_item_set_action_and_target (GMenuItem *menu_item,
1056 const gchar *action,
1057 const gchar *format_string,
1062 if (format_string != NULL)
1066 va_start (ap, format_string);
1067 value = g_variant_new_va (format_string, NULL, &ap);
1073 g_menu_item_set_action_and_target_value (menu_item, action, value);
1077 * g_menu_item_set_detailed_action:
1078 * @menu_item: a #GMenuItem
1079 * @detailed_action: the "detailed" action string
1081 * Sets the "action" and possibly the "target" attribute of @menu_item.
1083 * The format of @detailed_action is the same format parsed by
1084 * g_action_parse_detailed_name().
1086 * See g_menu_item_set_action_and_target() or
1087 * g_menu_item_set_action_and_target_value() for more flexible (but
1088 * slightly less convenient) alternatives.
1090 * See also g_menu_item_set_action_and_target_value() for a description of
1091 * the semantics of the action and target attributes.
1096 g_menu_item_set_detailed_action (GMenuItem *menu_item,
1097 const gchar *detailed_action)
1099 GError *error = NULL;
1103 if (!g_action_parse_detailed_name (detailed_action, &name, &target, &error))
1104 g_error ("g_menu_item_set_detailed_action: %s", error->message);
1106 g_menu_item_set_action_and_target_value (menu_item, name, target);
1108 g_variant_unref (target);
1114 * @label: (allow-none): the section label, or %NULL
1115 * @detailed_action: (allow-none): the detailed action string, or %NULL
1117 * Creates a new #GMenuItem.
1119 * If @label is non-%NULL it is used to set the "label" attribute of the
1122 * If @detailed_action is non-%NULL it is used to set the "action" and
1123 * possibly the "target" attribute of the new item. See
1124 * g_menu_item_set_detailed_action() for more information.
1126 * Returns: a new #GMenuItem
1131 g_menu_item_new (const gchar *label,
1132 const gchar *detailed_action)
1134 GMenuItem *menu_item;
1136 menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1139 g_menu_item_set_label (menu_item, label);
1141 if (detailed_action != NULL)
1142 g_menu_item_set_detailed_action (menu_item, detailed_action);
1148 * g_menu_item_new_submenu:
1149 * @label: (allow-none): the section label, or %NULL
1150 * @submenu: a #GMenuModel with the items of the submenu
1152 * Creates a new #GMenuItem representing a submenu.
1154 * This is a convenience API around g_menu_item_new() and
1155 * g_menu_item_set_submenu().
1157 * Returns: a new #GMenuItem
1162 g_menu_item_new_submenu (const gchar *label,
1163 GMenuModel *submenu)
1165 GMenuItem *menu_item;
1167 menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1170 g_menu_item_set_label (menu_item, label);
1172 g_menu_item_set_submenu (menu_item, submenu);
1178 * g_menu_item_new_section:
1179 * @label: (allow-none): the section label, or %NULL
1180 * @section: a #GMenuModel with the items of the section
1182 * Creates a new #GMenuItem representing a section.
1184 * This is a convenience API around g_menu_item_new() and
1185 * g_menu_item_set_section().
1187 * The effect of having one menu appear as a section of another is
1188 * exactly as it sounds: the items from @section become a direct part of
1189 * the menu that @menu_item is added to.
1191 * Visual separation is typically displayed between two non-empty
1192 * sections. If @label is non-%NULL then it will be encorporated into
1193 * this visual indication. This allows for labeled subsections of a
1196 * As a simple example, consider a typical "Edit" menu from a simple
1197 * program. It probably contains an "Undo" and "Redo" item, followed by
1198 * a separator, followed by "Cut", "Copy" and "Paste".
1200 * This would be accomplished by creating three #GMenu instances. The
1201 * first would be populated with the "Undo" and "Redo" items, and the
1202 * second with the "Cut", "Copy" and "Paste" items. The first and
1203 * second menus would then be added as submenus of the third. In XML
1204 * format, this would look something like the following:
1206 * <informalexample><programlisting><![CDATA[
1207 * <menu id='edit-menu'>
1209 * <item label='Undo'/>
1210 * <item label='Redo'/>
1213 * <item label='Cut'/>
1214 * <item label='Copy'/>
1215 * <item label='Paste'/>
1218 * ]]></programlisting></informalexample>
1220 * The following example is exactly equivalent. It is more illustrative
1221 * of the exact relationship between the menus and items (keeping in
1222 * mind that the 'link' element defines a new menu that is linked to the
1223 * containing one). The style of the second example is more verbose and
1224 * difficult to read (and therefore not recommended except for the
1225 * purpose of understanding what is really going on).
1227 * <informalexample><programlisting><![CDATA[
1228 * <menu id='edit-menu'>
1230 * <link name='section'>
1231 * <item label='Undo'/>
1232 * <item label='Redo'/>
1236 * <link name='section'>
1237 * <item label='Cut'/>
1238 * <item label='Copy'/>
1239 * <item label='Paste'/>
1243 * ]]></programlisting></informalexample>
1245 * Returns: a new #GMenuItem
1250 g_menu_item_new_section (const gchar *label,
1251 GMenuModel *section)
1253 GMenuItem *menu_item;
1255 menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1258 g_menu_item_set_label (menu_item, label);
1260 g_menu_item_set_section (menu_item, section);
1266 * g_menu_item_new_from_model:
1267 * @model: a #GMenuModel
1268 * @item_index: the index of an item in @model
1270 * Creates a #GMenuItem as an exact copy of an existing menu item in a
1273 * @item_index must be valid (ie: be sure to call
1274 * g_menu_model_get_n_items() first).
1276 * Returns: a new #GMenuItem.
1281 g_menu_item_new_from_model (GMenuModel *model,
1284 GMenuModelClass *class = G_MENU_MODEL_GET_CLASS (model);
1285 GMenuItem *menu_item;
1287 menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1289 /* With some trickery we can be pretty efficient.
1291 * A GMenuModel must either implement iterate_item_attributes() or
1292 * get_item_attributes(). If it implements get_item_attributes() then
1293 * we are in luck -- we can just take a reference on the returned
1294 * hashtable and mark ourselves as copy-on-write.
1296 * In the case that the model is based on get_item_attributes (which
1297 * is the case for both GMenu and GDBusMenuModel) then this is
1298 * basically just g_hash_table_ref().
1300 if (class->get_item_attributes)
1302 GHashTable *attributes = NULL;
1304 class->get_item_attributes (model, item_index, &attributes);
1307 g_hash_table_unref (menu_item->attributes);
1308 menu_item->attributes = attributes;
1309 menu_item->cow = TRUE;
1314 GMenuAttributeIter *iter;
1315 const gchar *attribute;
1318 iter = g_menu_model_iterate_item_attributes (model, item_index);
1319 while (g_menu_attribute_iter_get_next (iter, &attribute, &value))
1320 g_hash_table_insert (menu_item->attributes, g_strdup (attribute), value);
1321 g_object_unref (iter);
1324 /* Same story for the links... */
1325 if (class->get_item_links)
1327 GHashTable *links = NULL;
1329 class->get_item_links (model, item_index, &links);
1332 g_hash_table_unref (menu_item->links);
1333 menu_item->links = links;
1334 menu_item->cow = TRUE;
1339 GMenuLinkIter *iter;
1343 iter = g_menu_model_iterate_item_links (model, item_index);
1344 while (g_menu_link_iter_get_next (iter, &link, &value))
1345 g_hash_table_insert (menu_item->links, g_strdup (link), value);
1346 g_object_unref (iter);