gio/gmenu.c

   1 /*
   2  * Copyright © 2011 Canonical Ltd.
   3  *
   4  * This library is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as
   6  * published by the Free Software Foundation; either version 2 of the
   7  * licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Author: Ryan Lortie <desrt@desrt.ca>
  18  */
  19
  20 #include "config.h"
  21
  22 #include "gmenu.h"
  23
  24 #include "gaction.h"
  25 #include <string.h>
  26
  27 #include "gicon.h"
  28
  29 /**
  30  * SECTION:gmenu
  31  * @title: GMenu
  32  * @short_description: A simple implementation of GMenuModel
  33  * @include: gio/gio.h
  34  *
  35  * #GMenu is a simple implementation of #GMenuModel.
  36  * You populate a #GMenu by adding #GMenuItem instances to it.
  37  *
  38  * There are some convenience functions to allow you to directly
  39  * add items (avoiding #GMenuItem) for the common cases. To add
  40  * a regular item, use g_menu_insert(). To add a section, use
  41  * g_menu_insert_section(). To add a submenu, use
  42  * g_menu_insert_submenu().
  43  */
  44
  45 /**
  46  * GMenu:
  47  *
  48  * #GMenu is an opaque structure type.  You must access it using the
  49  * functions below.
  50  *
  51  * Since: 2.32
  52  */
  53
  54 /**
  55  * GMenuItem:
  56  *
  57  * #GMenuItem is an opaque structure type.  You must access it using the
  58  * functions below.
  59  *
  60  * Since: 2.32
  61  */
  62
  63 struct _GMenuItem
  64 {
  65   GObject parent_instance;
  66
  67   GHashTable *attributes;
  68   GHashTable *links;
  69   gboolean    cow;
  70 };
  71
  72 typedef GObjectClass GMenuItemClass;
  73
  74 struct _GMenu
  75 {
  76   GMenuModel parent_instance;
  77
  78   GArray   *items;
  79   gboolean  mutable;
  80 };
  81
  82 typedef GMenuModelClass GMenuClass;
  83
  84 G_DEFINE_TYPE (GMenu, g_menu, G_TYPE_MENU_MODEL)
  85 G_DEFINE_TYPE (GMenuItem, g_menu_item, G_TYPE_OBJECT)
  86
  87 struct item
  88 {
  89   GHashTable *attributes;
  90   GHashTable *links;
  91 };
  92
  93 static gboolean
  94 g_menu_is_mutable (GMenuModel *model)
  95 {
  96   GMenu *menu = G_MENU (model);
  97
  98   return menu->mutable;
  99 }
 100
 101 static gint
 102 g_menu_get_n_items (GMenuModel *model)
 103 {
 104   GMenu *menu = G_MENU (model);
 105
 106   return menu->items->len;
 107 }
 108
 109 static void
 110 g_menu_get_item_attributes (GMenuModel  *model,
 111                             gint         position,
 112                             GHashTable **table)
 113 {
 114   GMenu *menu = G_MENU (model);
 115
 116   *table = g_hash_table_ref (g_array_index (menu->items, struct item, position).attributes);
 117 }
 118
 119 static void
 120 g_menu_get_item_links (GMenuModel  *model,
 121                        gint         position,
 122                        GHashTable **table)
 123 {
 124   GMenu *menu = G_MENU (model);
 125
 126   *table = g_hash_table_ref (g_array_index (menu->items, struct item, position).links);
 127 }
 128
 129 /**
 130  * g_menu_insert_item:
 131  * @menu: a #GMenu
 132  * @position: the position at which to insert the item
 133  * @item: the #GMenuItem to insert
 134  *
 135  * Inserts @item into @menu.
 136  *
 137  * The "insertion" is actually done by copying all of the attribute and
 138  * link values of @item and using them to form a new item within @menu.
 139  * As such, @item itself is not really inserted, but rather, a menu item
 140  * that is exactly the same as the one presently described by @item.
 141  *
 142  * This means that @item is essentially useless after the insertion
 143  * occurs.  Any changes you make to it are ignored unless it is inserted
 144  * again (at which point its updated values will be copied).
 145  *
 146  * You should probably just free @item once you're done.
 147  *
 148  * There are many convenience functions to take care of common cases.
 149  * See g_menu_insert(), g_menu_insert_section() and
 150  * g_menu_insert_submenu() as well as "prepend" and "append" variants of
 151  * each of these functions.
 152  *
 153  * Since: 2.32
 154  */
 155 void
 156 g_menu_insert_item (GMenu     *menu,
 157                     gint       position,
 158                     GMenuItem *item)
 159 {
 160   struct item new_item;
 161
 162   g_return_if_fail (G_IS_MENU (menu));
 163   g_return_if_fail (G_IS_MENU_ITEM (item));
 164
 165   if (position < 0 || position > menu->items->len)
 166     position = menu->items->len;
 167
 168   new_item.attributes = g_hash_table_ref (item->attributes);
 169   new_item.links = g_hash_table_ref (item->links);
 170   item->cow = TRUE;
 171
 172   g_array_insert_val (menu->items, position, new_item);
 173   g_menu_model_items_changed (G_MENU_MODEL (menu), position, 0, 1);
 174 }
 175
 176 /**
 177  * g_menu_prepend_item:
 178  * @menu: a #GMenu
 179  * @item: a #GMenuItem to prepend
 180  *
 181  * Prepends @item to the start of @menu.
 182  *
 183  * See g_menu_insert_item() for more information.
 184  *
 185  * Since: 2.32
 186  */
 187 void
 188 g_menu_prepend_item (GMenu     *menu,
 189                      GMenuItem *item)
 190 {
 191   g_menu_insert_item (menu, 0, item);
 192 }
 193
 194 /**
 195  * g_menu_append_item:
 196  * @menu: a #GMenu
 197  * @item: a #GMenuItem to append
 198  *
 199  * Appends @item to the end of @menu.
 200  *
 201  * See g_menu_insert_item() for more information.
 202  *
 203  * Since: 2.32
 204  */
 205 void
 206 g_menu_append_item (GMenu     *menu,
 207                     GMenuItem *item)
 208 {
 209   g_menu_insert_item (menu, -1, item);
 210 }
 211
 212 /**
 213  * g_menu_freeze:
 214  * @menu: a #GMenu
 215  *
 216  * Marks @menu as frozen.
 217  *
 218  * After the menu is frozen, it is an error to attempt to make any
 219  * changes to it.  In effect this means that the #GMenu API must no
 220  * longer be used.
 221  *
 222  * This function causes g_menu_model_is_mutable() to begin returning
 223  * %FALSE, which has some positive performance implications.
 224  *
 225  * Since: 2.32
 226  */
 227 void
 228 g_menu_freeze (GMenu *menu)
 229 {
 230   g_return_if_fail (G_IS_MENU (menu));
 231
 232   menu->mutable = FALSE;
 233 }
 234
 235 /**
 236  * g_menu_new:
 237  *
 238  * Creates a new #GMenu.
 239  *
 240  * The new menu has no items.
 241  *
 242  * Returns: a new #GMenu
 243  *
 244  * Since: 2.32
 245  */
 246 GMenu *
 247 g_menu_new (void)
 248 {
 249   return g_object_new (G_TYPE_MENU, NULL);
 250 }
 251
 252 /**
 253  * g_menu_insert:
 254  * @menu: a #GMenu
 255  * @position: the position at which to insert the item
 256  * @label: (allow-none): the section label, or %NULL
 257  * @detailed_action: (allow-none): the detailed action string, or %NULL
 258  *
 259  * Convenience function for inserting a normal menu item into @menu.
 260  * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
 261  * alternative.
 262  *
 263  * Since: 2.32
 264  */
 265 void
 266 g_menu_insert (GMenu       *menu,
 267                gint         position,
 268                const gchar *label,
 269                const gchar *detailed_action)
 270 {
 271   GMenuItem *menu_item;
 272
 273   menu_item = g_menu_item_new (label, detailed_action);
 274   g_menu_insert_item (menu, position, menu_item);
 275   g_object_unref (menu_item);
 276 }
 277
 278 /**
 279  * g_menu_prepend:
 280  * @menu: a #GMenu
 281  * @label: (allow-none): the section label, or %NULL
 282  * @detailed_action: (allow-none): the detailed action string, or %NULL
 283  *
 284  * Convenience function for prepending a normal menu item to the start
 285  * of @menu.  Combine g_menu_item_new() and g_menu_insert_item() for a more
 286  * flexible alternative.
 287  *
 288  * Since: 2.32
 289  */
 290 void
 291 g_menu_prepend (GMenu       *menu,
 292                 const gchar *label,
 293                 const gchar *detailed_action)
 294 {
 295   g_menu_insert (menu, 0, label, detailed_action);
 296 }
 297
 298 /**
 299  * g_menu_append:
 300  * @menu: a #GMenu
 301  * @label: (allow-none): the section label, or %NULL
 302  * @detailed_action: (allow-none): the detailed action string, or %NULL
 303  *
 304  * Convenience function for appending a normal menu item to the end of
 305  * @menu.  Combine g_menu_item_new() and g_menu_insert_item() for a more
 306  * flexible alternative.
 307  *
 308  * Since: 2.32
 309  */
 310 void
 311 g_menu_append (GMenu       *menu,
 312                const gchar *label,
 313                const gchar *detailed_action)
 314 {
 315   g_menu_insert (menu, -1, label, detailed_action);
 316 }
 317
 318 /**
 319  * g_menu_insert_section:
 320  * @menu: a #GMenu
 321  * @position: the position at which to insert the item
 322  * @label: (allow-none): the section label, or %NULL
 323  * @section: a #GMenuModel with the items of the section
 324  *
 325  * Convenience function for inserting a section menu item into @menu.
 326  * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
 327  * flexible alternative.
 328  *
 329  * Since: 2.32
 330  */
 331 void
 332 g_menu_insert_section (GMenu       *menu,
 333                        gint         position,
 334                        const gchar *label,
 335                        GMenuModel  *section)
 336 {
 337   GMenuItem *menu_item;
 338
 339   menu_item = g_menu_item_new_section (label, section);
 340   g_menu_insert_item (menu, position, menu_item);
 341   g_object_unref (menu_item);
 342 }
 343
 344
 345 /**
 346  * g_menu_prepend_section:
 347  * @menu: a #GMenu
 348  * @label: (allow-none): the section label, or %NULL
 349  * @section: a #GMenuModel with the items of the section
 350  *
 351  * Convenience function for prepending a section menu item to the start
 352  * of @menu.  Combine g_menu_item_new_section() and g_menu_insert_item() for
 353  * a more flexible alternative.
 354  *
 355  * Since: 2.32
 356  */
 357 void
 358 g_menu_prepend_section (GMenu       *menu,
 359                         const gchar *label,
 360                         GMenuModel  *section)
 361 {
 362   g_menu_insert_section (menu, 0, label, section);
 363 }
 364
 365 /**
 366  * g_menu_append_section:
 367  * @menu: a #GMenu
 368  * @label: (allow-none): the section label, or %NULL
 369  * @section: a #GMenuModel with the items of the section
 370  *
 371  * Convenience function for appending a section menu item to the end of
 372  * @menu.  Combine g_menu_item_new_section() and g_menu_insert_item() for a
 373  * more flexible alternative.
 374  *
 375  * Since: 2.32
 376  */
 377 void
 378 g_menu_append_section (GMenu       *menu,
 379                        const gchar *label,
 380                        GMenuModel  *section)
 381 {
 382   g_menu_insert_section (menu, -1, label, section);
 383 }
 384
 385 /**
 386  * g_menu_insert_submenu:
 387  * @menu: a #GMenu
 388  * @position: the position at which to insert the item
 389  * @label: (allow-none): the section label, or %NULL
 390  * @submenu: a #GMenuModel with the items of the submenu
 391  *
 392  * Convenience function for inserting a submenu menu item into @menu.
 393  * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
 394  * flexible alternative.
 395  *
 396  * Since: 2.32
 397  */
 398 void
 399 g_menu_insert_submenu (GMenu       *menu,
 400                        gint         position,
 401                        const gchar *label,
 402                        GMenuModel  *submenu)
 403 {
 404   GMenuItem *menu_item;
 405
 406   menu_item = g_menu_item_new_submenu (label, submenu);
 407   g_menu_insert_item (menu, position, menu_item);
 408   g_object_unref (menu_item);
 409 }
 410
 411 /**
 412  * g_menu_prepend_submenu:
 413  * @menu: a #GMenu
 414  * @label: (allow-none): the section label, or %NULL
 415  * @submenu: a #GMenuModel with the items of the submenu
 416  *
 417  * Convenience function for prepending a submenu menu item to the start
 418  * of @menu.  Combine g_menu_item_new_submenu() and g_menu_insert_item() for
 419  * a more flexible alternative.
 420  *
 421  * Since: 2.32
 422  */
 423 void
 424 g_menu_prepend_submenu (GMenu       *menu,
 425                         const gchar *label,
 426                         GMenuModel  *submenu)
 427 {
 428   g_menu_insert_submenu (menu, 0, label, submenu);
 429 }
 430
 431 /**
 432  * g_menu_append_submenu:
 433  * @menu: a #GMenu
 434  * @label: (allow-none): the section label, or %NULL
 435  * @submenu: a #GMenuModel with the items of the submenu
 436  *
 437  * Convenience function for appending a submenu menu item to the end of
 438  * @menu.  Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
 439  * more flexible alternative.
 440  *
 441  * Since: 2.32
 442  */
 443 void
 444 g_menu_append_submenu (GMenu       *menu,
 445                        const gchar *label,
 446                        GMenuModel  *submenu)
 447 {
 448   g_menu_insert_submenu (menu, -1, label, submenu);
 449 }
 450
 451 static void
 452 g_menu_clear_item (struct item *item)
 453 {
 454   if (item->attributes != NULL)
 455     g_hash_table_unref (item->attributes);
 456   if (item->links != NULL)
 457     g_hash_table_unref (item->links);
 458 }
 459
 460 /**
 461  * g_menu_remove:
 462  * @menu: a #GMenu
 463  * @position: the position of the item to remove
 464  *
 465  * Removes an item from the menu.
 466  *
 467  * @position gives the index of the item to remove.
 468  *
 469  * It is an error if position is not in range the range from 0 to one
 470  * less than the number of items in the menu.
 471  *
 472  * It is not possible to remove items by identity since items are added
 473  * to the menu simply by copying their links and attributes (ie:
 474  * identity of the item itself is not preserved).
 475  *
 476  * Since: 2.32
 477  */
 478 void
 479 g_menu_remove (GMenu *menu,
 480                gint   position)
 481 {
 482   g_return_if_fail (G_IS_MENU (menu));
 483   g_return_if_fail (0 <= position && position < menu->items->len);
 484
 485   g_menu_clear_item (&g_array_index (menu->items, struct item, position));
 486   g_array_remove_index (menu->items, position);
 487   g_menu_model_items_changed (G_MENU_MODEL (menu), position, 1, 0);
 488 }
 489
 490 /**
 491  * g_menu_remove_all:
 492  * @menu: a #GMenu
 493  *
 494  * Removes all items in the menu.
 495  *
 496  * Since: 2.38
 497  **/
 498 void
 499 g_menu_remove_all (GMenu *menu)
 500 {
 501   gint i, n;
 502
 503   g_return_if_fail (G_IS_MENU (menu));
 504   n = menu->items->len;
 505
 506   for (i = 0; i < n; i++)
 507     g_menu_clear_item (&g_array_index (menu->items, struct item, i));
 508   g_array_set_size (menu->items, 0);
 509
 510   g_menu_model_items_changed (G_MENU_MODEL (menu), 0, n, 0);
 511 }
 512
 513 static void
 514 g_menu_finalize (GObject *object)
 515 {
 516   GMenu *menu = G_MENU (object);
 517   struct item *items;
 518   gint n_items;
 519   gint i;
 520
 521   n_items = menu->items->len;
 522   items = (struct item *) g_array_free (menu->items, FALSE);
 523   for (i = 0; i < n_items; i++)
 524     g_menu_clear_item (&items[i]);
 525   g_free (items);
 526
 527   G_OBJECT_CLASS (g_menu_parent_class)
 528     ->finalize (object);
 529 }
 530
 531 static void
 532 g_menu_init (GMenu *menu)
 533 {
 534   menu->items = g_array_new (FALSE, FALSE, sizeof (struct item));
 535   menu->mutable = TRUE;
 536 }
 537
 538 static void
 539 g_menu_class_init (GMenuClass *class)
 540 {
 541   GMenuModelClass *model_class = G_MENU_MODEL_CLASS (class);
 542   GObjectClass *object_class = G_OBJECT_CLASS (class);
 543
 544   object_class->finalize = g_menu_finalize;
 545
 546   model_class->is_mutable = g_menu_is_mutable;
 547   model_class->get_n_items = g_menu_get_n_items;
 548   model_class->get_item_attributes = g_menu_get_item_attributes;
 549   model_class->get_item_links = g_menu_get_item_links;
 550 }
 551
 552
 553 static void
 554 g_menu_item_clear_cow (GMenuItem *menu_item)
 555 {
 556   if (menu_item->cow)
 557     {
 558       GHashTableIter iter;
 559       GHashTable *new;
 560       gpointer key;
 561       gpointer val;
 562
 563       new = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_variant_unref);
 564       g_hash_table_iter_init (&iter, menu_item->attributes);
 565       while (g_hash_table_iter_next (&iter, &key, &val))
 566         g_hash_table_insert (new, g_strdup (key), g_variant_ref (val));
 567       g_hash_table_unref (menu_item->attributes);
 568       menu_item->attributes = new;
 569
 570       new = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_object_unref);
 571       g_hash_table_iter_init (&iter, menu_item->links);
 572       while (g_hash_table_iter_next (&iter, &key, &val))
 573         g_hash_table_insert (new, g_strdup (key), g_object_ref (val));
 574       g_hash_table_unref (menu_item->links);
 575       menu_item->links = new;
 576
 577       menu_item->cow = FALSE;
 578     }
 579 }
 580
 581 static void
 582 g_menu_item_finalize (GObject *object)
 583 {
 584   GMenuItem *menu_item = G_MENU_ITEM (object);
 585
 586   g_hash_table_unref (menu_item->attributes);
 587   g_hash_table_unref (menu_item->links);
 588
 589   G_OBJECT_CLASS (g_menu_item_parent_class)
 590     ->finalize (object);
 591 }
 592
 593 static void
 594 g_menu_item_init (GMenuItem *menu_item)
 595 {
 596   menu_item->attributes = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_variant_unref);
 597   menu_item->links = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, g_object_unref);
 598   menu_item->cow = FALSE;
 599 }
 600
 601 static void
 602 g_menu_item_class_init (GMenuItemClass *class)
 603 {
 604   class->finalize = g_menu_item_finalize;
 605 }
 606
 607 /* We treat attribute names the same as GSettings keys:
 608  * - only lowercase ascii, digits and '-'
 609  * - must start with lowercase
 610  * - must not end with '-'
 611  * - no consecutive '-'
 612  * - not longer than 1024 chars
 613  */
 614 static gboolean
 615 valid_attribute_name (const gchar *name)
 616 {
 617   gint i;
 618
 619   if (!g_ascii_islower (name[0]))
 620     return FALSE;
 621
 622   for (i = 1; name[i]; i++)
 623     {
 624       if (name[i] != '-' &&
 625           !g_ascii_islower (name[i]) &&
 626           !g_ascii_isdigit (name[i]))
 627         return FALSE;
 628
 629       if (name[i] == '-' && name[i + 1] == '-')
 630         return FALSE;
 631     }
 632
 633   if (name[i - 1] == '-')
 634     return FALSE;
 635
 636   if (i > 1024)
 637     return FALSE;
 638
 639   return TRUE;
 640 }
 641
 642 /**
 643  * g_menu_item_set_attribute_value:
 644  * @menu_item: a #GMenuItem
 645  * @attribute: the attribute to set
 646  * @value: (allow-none): a #GVariant to use as the value, or %NULL
 647  *
 648  * Sets or unsets an attribute on @menu_item.
 649  *
 650  * The attribute to set or unset is specified by @attribute. This
 651  * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
 652  * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
 653  * attribute name.
 654  * Attribute names are restricted to lowercase characters, numbers
 655  * and '-'. Furthermore, the names must begin with a lowercase character,
 656  * must not end with a '-', and must not contain consecutive dashes.
 657  *
 658  * must consist only of lowercase
 659  * ASCII characters, digits and '-'.
 660  *
 661  * If @value is non-%NULL then it is used as the new value for the
 662  * attribute.  If @value is %NULL then the attribute is unset. If
 663  * the @value #GVariant is floating, it is consumed.
 664  *
 665  * See also g_menu_item_set_attribute() for a more convenient way to do
 666  * the same.
 667  *
 668  * Since: 2.32
 669  */
 670 void
 671 g_menu_item_set_attribute_value (GMenuItem   *menu_item,
 672                                  const gchar *attribute,
 673                                  GVariant    *value)
 674 {
 675   g_return_if_fail (G_IS_MENU_ITEM (menu_item));
 676   g_return_if_fail (attribute != NULL);
 677   g_return_if_fail (valid_attribute_name (attribute));
 678
 679   g_menu_item_clear_cow (menu_item);
 680
 681   if (value != NULL)
 682     g_hash_table_insert (menu_item->attributes, g_strdup (attribute), g_variant_ref_sink (value));
 683   else
 684     g_hash_table_remove (menu_item->attributes, attribute);
 685 }
 686
 687 /**
 688  * g_menu_item_set_attribute:
 689  * @menu_item: a #GMenuItem
 690  * @attribute: the attribute to set
 691  * @format_string: (allow-none): a #GVariant format string, or %NULL
 692  * @...: positional parameters, as per @format_string
 693  *
 694  * Sets or unsets an attribute on @menu_item.
 695  *
 696  * The attribute to set or unset is specified by @attribute. This
 697  * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
 698  * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
 699  * attribute name.
 700  * Attribute names are restricted to lowercase characters, numbers
 701  * and '-'. Furthermore, the names must begin with a lowercase character,
 702  * must not end with a '-', and must not contain consecutive dashes.
 703  *
 704  * If @format_string is non-%NULL then the proper position parameters
 705  * are collected to create a #GVariant instance to use as the attribute
 706  * value.  If it is %NULL then the positional parameterrs are ignored
 707  * and the named attribute is unset.
 708  *
 709  * See also g_menu_item_set_attribute_value() for an equivalent call
 710  * that directly accepts a #GVariant.
 711  *
 712  * Since: 2.32
 713  */
 714 void
 715 g_menu_item_set_attribute (GMenuItem   *menu_item,
 716                            const gchar *attribute,
 717                            const gchar *format_string,
 718                            ...)
 719 {
 720   GVariant *value;
 721
 722   if (format_string != NULL)
 723     {
 724       va_list ap;
 725
 726       va_start (ap, format_string);
 727       value = g_variant_new_va (format_string, NULL, &ap);
 728       va_end (ap);
 729     }
 730   else
 731     value = NULL;
 732
 733   g_menu_item_set_attribute_value (menu_item, attribute, value);
 734 }
 735
 736 /**
 737  * g_menu_item_set_link:
 738  * @menu_item: a #GMenuItem
 739  * @link: type of link to establish or unset
 740  * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
 741  *
 742  * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
 743  *
 744  * Links are used to establish a relationship between a particular menu
 745  * item and another menu.  For example, %G_MENU_LINK_SUBMENU is used to
 746  * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
 747  * is used to create a section. Other types of link can be used, but there
 748  * is no guarantee that clients will be able to make sense of them.
 749  * Link types are restricted to lowercase characters, numbers
 750  * and '-'. Furthermore, the names must begin with a lowercase character,
 751  * must not end with a '-', and must not contain consecutive dashes.
 752  *
 753  * Since: 2.32
 754  */
 755 void
 756 g_menu_item_set_link (GMenuItem   *menu_item,
 757                       const gchar *link,
 758                       GMenuModel  *model)
 759 {
 760   g_return_if_fail (G_IS_MENU_ITEM (menu_item));
 761   g_return_if_fail (link != NULL);
 762   g_return_if_fail (valid_attribute_name (link));
 763
 764   g_menu_item_clear_cow (menu_item);
 765
 766   if (model != NULL)
 767     g_hash_table_insert (menu_item->links, g_strdup (link), g_object_ref (model));
 768   else
 769     g_hash_table_remove (menu_item->links, link);
 770 }
 771
 772 /**
 773  * g_menu_item_get_attribute_value:
 774  * @menu_item: a #GMenuItem
 775  * @attribute: the attribute name to query
 776  * @expected_type: (allow-none): the expected type of the attribute
 777  *
 778  * Queries the named @attribute on @menu_item.
 779  *
 780  * If @expected_type is specified and the attribute does not have this
 781  * type, %NULL is returned.  %NULL is also returned if the attribute
 782  * simply does not exist.
 783  *
 784  * Returns: (transfer full): the attribute value, or %NULL
 785  *
 786  * Since: 2.34
 787  */
 788 GVariant *
 789 g_menu_item_get_attribute_value (GMenuItem          *menu_item,
 790                                  const gchar        *attribute,
 791                                  const GVariantType *expected_type)
 792 {
 793   GVariant *value;
 794
 795   g_return_val_if_fail (G_IS_MENU_ITEM (menu_item), NULL);
 796   g_return_val_if_fail (attribute != NULL, NULL);
 797
 798   value = g_hash_table_lookup (menu_item->attributes, attribute);
 799
 800   if (value != NULL)
 801     {
 802       if (expected_type == NULL || g_variant_is_of_type (value, expected_type))
 803         g_variant_ref (value);
 804       else
 805         value = NULL;
 806     }
 807
 808   return value;
 809 }
 810
 811 /**
 812  * g_menu_item_get_attribute:
 813  * @menu_item: a #GMenuItem
 814  * @attribute: the attribute name to query
 815  * @format_string: a #GVariant format string
 816  * @...: positional parameters, as per @format_string
 817  *
 818  * Queries the named @attribute on @menu_item.
 819  *
 820  * If the attribute exists and matches the #GVariantType corresponding
 821  * to @format_string then @format_string is used to deconstruct the
 822  * value into the positional parameters and %TRUE is returned.
 823  *
 824  * If the attribute does not exist, or it does exist but has the wrong
 825  * type, then the positional parameters are ignored and %FALSE is
 826  * returned.
 827  *
 828  * Returns: %TRUE if the named attribute was found with the expected
 829  *     type
 830  *
 831  * Since: 2.34
 832  */
 833 gboolean
 834 g_menu_item_get_attribute (GMenuItem   *menu_item,
 835                            const gchar *attribute,
 836                            const gchar *format_string,
 837                            ...)
 838 {
 839   GVariant *value;
 840   va_list ap;
 841
 842   g_return_val_if_fail (G_IS_MENU_ITEM (menu_item), FALSE);
 843   g_return_val_if_fail (attribute != NULL, FALSE);
 844   g_return_val_if_fail (format_string != NULL, FALSE);
 845
 846   value = g_hash_table_lookup (menu_item->attributes, attribute);
 847
 848   if (value == NULL)
 849     return FALSE;
 850
 851   if (!g_variant_check_format_string (value, format_string, FALSE))
 852     return FALSE;
 853
 854   va_start (ap, format_string);
 855   g_variant_get_va (value, format_string, NULL, &ap);
 856   va_end (ap);
 857
 858   return TRUE;
 859 }
 860
 861 /**
 862  * g_menu_item_get_link:
 863  * @menu_item: a #GMenuItem
 864  * @link: the link name to query
 865  *
 866  * Queries the named @link on @menu_item.
 867  *
 868  * Returns: (transfer full): the link, or %NULL
 869  *
 870  * Since: 2.34
 871  */
 872 GMenuModel *
 873 g_menu_item_get_link (GMenuItem   *menu_item,
 874                       const gchar *link)
 875 {
 876   GMenuModel *model;
 877
 878   g_return_val_if_fail (G_IS_MENU_ITEM (menu_item), NULL);
 879   g_return_val_if_fail (link != NULL, NULL);
 880   g_return_val_if_fail (valid_attribute_name (link), NULL);
 881
 882   model = g_hash_table_lookup (menu_item->links, link);
 883
 884   if (model)
 885     g_object_ref (model);
 886
 887   return model;
 888 }
 889
 890 /**
 891  * g_menu_item_set_label:
 892  * @menu_item: a #GMenuItem
 893  * @label: (allow-none): the label to set, or %NULL to unset
 894  *
 895  * Sets or unsets the "label" attribute of @menu_item.
 896  *
 897  * If @label is non-%NULL it is used as the label for the menu item.  If
 898  * it is %NULL then the label attribute is unset.
 899  *
 900  * Since: 2.32
 901  */
 902 void
 903 g_menu_item_set_label (GMenuItem   *menu_item,
 904                        const gchar *label)
 905 {
 906   GVariant *value;
 907
 908   if (label != NULL)
 909     value = g_variant_new_string (label);
 910   else
 911     value = NULL;
 912
 913   g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_LABEL, value);
 914 }
 915
 916 /**
 917  * g_menu_item_set_submenu:
 918  * @menu_item: a #GMenuItem
 919  * @submenu: (allow-none): a #GMenuModel, or %NULL
 920  *
 921  * Sets or unsets the "submenu" link of @menu_item to @submenu.
 922  *
 923  * If @submenu is non-%NULL, it is linked to.  If it is %NULL then the
 924  * link is unset.
 925  *
 926  * The effect of having one menu appear as a submenu of another is
 927  * exactly as it sounds.
 928  *
 929  * Since: 2.32
 930  */
 931 void
 932 g_menu_item_set_submenu (GMenuItem  *menu_item,
 933                          GMenuModel *submenu)
 934 {
 935   g_menu_item_set_link (menu_item, G_MENU_LINK_SUBMENU, submenu);
 936 }
 937
 938 /**
 939  * g_menu_item_set_section:
 940  * @menu_item: a #GMenuItem
 941  * @section: (allow-none): a #GMenuModel, or %NULL
 942  *
 943  * Sets or unsets the "section" link of @menu_item to @section.
 944  *
 945  * The effect of having one menu appear as a section of another is
 946  * exactly as it sounds: the items from @section become a direct part of
 947  * the menu that @menu_item is added to.  See g_menu_item_new_section()
 948  * for more information about what it means for a menu item to be a
 949  * section.
 950  *
 951  * Since: 2.32
 952  */
 953 void
 954 g_menu_item_set_section (GMenuItem  *menu_item,
 955                          GMenuModel *section)
 956 {
 957   g_menu_item_set_link (menu_item, G_MENU_LINK_SECTION, section);
 958 }
 959
 960 /**
 961  * g_menu_item_set_action_and_target_value:
 962  * @menu_item: a #GMenuItem
 963  * @action: (allow-none): the name of the action for this item
 964  * @target_value: (allow-none): a #GVariant to use as the action target
 965  *
 966  * Sets or unsets the "action" and "target" attributes of @menu_item.
 967  *
 968  * If @action is %NULL then both the "action" and "target" attributes
 969  * are unset (and @target_value is ignored).
 970  *
 971  * If @action is non-%NULL then the "action" attribute is set.  The
 972  * "target" attribute is then set to the value of @target_value if it is
 973  * non-%NULL or unset otherwise.
 974  *
 975  * Normal menu items (ie: not submenu, section or other custom item
 976  * types) are expected to have the "action" attribute set to identify
 977  * the action that they are associated with.  The state type of the
 978  * action help to determine the disposition of the menu item.  See
 979  * #GAction and #GActionGroup for an overview of actions.
 980  *
 981  * In general, clicking on the menu item will result in activation of
 982  * the named action with the "target" attribute given as the parameter
 983  * to the action invocation.  If the "target" attribute is not set then
 984  * the action is invoked with no parameter.
 985  *
 986  * If the action has no state then the menu item is usually drawn as a
 987  * plain menu item (ie: with no additional decoration).
 988  *
 989  * If the action has a boolean state then the menu item is usually drawn
 990  * as a toggle menu item (ie: with a checkmark or equivalent
 991  * indication).  The item should be marked as 'toggled' or 'checked'
 992  * when the boolean state is %TRUE.
 993  *
 994  * If the action has a string state then the menu item is usually drawn
 995  * as a radio menu item (ie: with a radio bullet or equivalent
 996  * indication).  The item should be marked as 'selected' when the string
 997  * state is equal to the value of the @target property.
 998  *
 999  * See g_menu_item_set_action_and_target() or
1000  * g_menu_item_set_detailed_action() for two equivalent calls that are
1001  * probably more convenient for most uses.
1002  *
1003  * Since: 2.32
1004  */
1005 void
1006 g_menu_item_set_action_and_target_value (GMenuItem   *menu_item,
1007                                          const gchar *action,
1008                                          GVariant    *target_value)
1009 {
1010   GVariant *action_value;
1011
1012   if (action != NULL)
1013     {
1014       action_value = g_variant_new_string (action);
1015     }
1016   else
1017     {
1018       action_value = NULL;
1019       target_value = NULL;
1020     }
1021
1022   g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_ACTION, action_value);
1023   g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_TARGET, target_value);
1024 }
1025
1026 /**
1027  * g_menu_item_set_action_and_target:
1028  * @menu_item: a #GMenuItem
1029  * @action: (allow-none): the name of the action for this item
1030  * @format_string: (allow-none): a GVariant format string
1031  * @...: positional parameters, as per @format_string
1032  *
1033  * Sets or unsets the "action" and "target" attributes of @menu_item.
1034  *
1035  * If @action is %NULL then both the "action" and "target" attributes
1036  * are unset (and @format_string is ignored along with the positional
1037  * parameters).
1038  *
1039  * If @action is non-%NULL then the "action" attribute is set.
1040  * @format_string is then inspected.  If it is non-%NULL then the proper
1041  * position parameters are collected to create a #GVariant instance to
1042  * use as the target value.  If it is %NULL then the positional
1043  * parameters are ignored and the "target" attribute is unset.
1044  *
1045  * See also g_menu_item_set_action_and_target_value() for an equivalent
1046  * call that directly accepts a #GVariant.  See
1047  * g_menu_item_set_detailed_action() for a more convenient version that
1048  * works with string-typed targets.
1049  *
1050  * See also g_menu_item_set_action_and_target_value() for a
1051  * description of the semantics of the action and target attributes.
1052  *
1053  * Since: 2.32
1054  */
1055 void
1056 g_menu_item_set_action_and_target (GMenuItem   *menu_item,
1057                                    const gchar *action,
1058                                    const gchar *format_string,
1059                                    ...)
1060 {
1061   GVariant *value;
1062
1063   if (format_string != NULL)
1064     {
1065       va_list ap;
1066
1067       va_start (ap, format_string);
1068       value = g_variant_new_va (format_string, NULL, &ap);
1069       va_end (ap);
1070     }
1071   else
1072     value = NULL;
1073
1074   g_menu_item_set_action_and_target_value (menu_item, action, value);
1075 }
1076
1077 /**
1078  * g_menu_item_set_detailed_action:
1079  * @menu_item: a #GMenuItem
1080  * @detailed_action: the "detailed" action string
1081  *
1082  * Sets the "action" and possibly the "target" attribute of @menu_item.
1083  *
1084  * The format of @detailed_action is the same format parsed by
1085  * g_action_parse_detailed_name().
1086  *
1087  * See g_menu_item_set_action_and_target() or
1088  * g_menu_item_set_action_and_target_value() for more flexible (but
1089  * slightly less convenient) alternatives.
1090  *
1091  * See also g_menu_item_set_action_and_target_value() for a description of
1092  * the semantics of the action and target attributes.
1093  *
1094  * Since: 2.32
1095  */
1096 void
1097 g_menu_item_set_detailed_action (GMenuItem   *menu_item,
1098                                  const gchar *detailed_action)
1099 {
1100   GError *error = NULL;
1101   GVariant *target;
1102   gchar *name;
1103
1104   if (!g_action_parse_detailed_name (detailed_action, &name, &target, &error))
1105     g_error ("g_menu_item_set_detailed_action: %s", error->message);
1106
1107   g_menu_item_set_action_and_target_value (menu_item, name, target);
1108   if (target)
1109     g_variant_unref (target);
1110   g_free (name);
1111 }
1112
1113 /**
1114  * g_menu_item_new:
1115  * @label: (allow-none): the section label, or %NULL
1116  * @detailed_action: (allow-none): the detailed action string, or %NULL
1117  *
1118  * Creates a new #GMenuItem.
1119  *
1120  * If @label is non-%NULL it is used to set the "label" attribute of the
1121  * new item.
1122  *
1123  * If @detailed_action is non-%NULL it is used to set the "action" and
1124  * possibly the "target" attribute of the new item.  See
1125  * g_menu_item_set_detailed_action() for more information.
1126  *
1127  * Returns: a new #GMenuItem
1128  *
1129  * Since: 2.32
1130  */
1131 GMenuItem *
1132 g_menu_item_new (const gchar *label,
1133                  const gchar *detailed_action)
1134 {
1135   GMenuItem *menu_item;
1136
1137   menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1138
1139   if (label != NULL)
1140     g_menu_item_set_label (menu_item, label);
1141
1142   if (detailed_action != NULL)
1143     g_menu_item_set_detailed_action (menu_item, detailed_action);
1144
1145   return menu_item;
1146 }
1147
1148 /**
1149  * g_menu_item_new_submenu:
1150  * @label: (allow-none): the section label, or %NULL
1151  * @submenu: a #GMenuModel with the items of the submenu
1152  *
1153  * Creates a new #GMenuItem representing a submenu.
1154  *
1155  * This is a convenience API around g_menu_item_new() and
1156  * g_menu_item_set_submenu().
1157  *
1158  * Returns: a new #GMenuItem
1159  *
1160  * Since: 2.32
1161  */
1162 GMenuItem *
1163 g_menu_item_new_submenu (const gchar *label,
1164                          GMenuModel  *submenu)
1165 {
1166   GMenuItem *menu_item;
1167
1168   menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1169
1170   if (label != NULL)
1171     g_menu_item_set_label (menu_item, label);
1172
1173   g_menu_item_set_submenu (menu_item, submenu);
1174
1175   return menu_item;
1176 }
1177
1178 /**
1179  * g_menu_item_new_section:
1180  * @label: (allow-none): the section label, or %NULL
1181  * @section: a #GMenuModel with the items of the section
1182  *
1183  * Creates a new #GMenuItem representing a section.
1184  *
1185  * This is a convenience API around g_menu_item_new() and
1186  * g_menu_item_set_section().
1187  *
1188  * The effect of having one menu appear as a section of another is
1189  * exactly as it sounds: the items from @section become a direct part of
1190  * the menu that @menu_item is added to.
1191  *
1192  * Visual separation is typically displayed between two non-empty
1193  * sections.  If @label is non-%NULL then it will be encorporated into
1194  * this visual indication.  This allows for labeled subsections of a
1195  * menu.
1196  *
1197  * As a simple example, consider a typical "Edit" menu from a simple
1198  * program.  It probably contains an "Undo" and "Redo" item, followed by
1199  * a separator, followed by "Cut", "Copy" and "Paste".
1200  *
1201  * This would be accomplished by creating three #GMenu instances.  The
1202  * first would be populated with the "Undo" and "Redo" items, and the
1203  * second with the "Cut", "Copy" and "Paste" items.  The first and
1204  * second menus would then be added as submenus of the third.  In XML
1205  * format, this would look something like the following:
1206  * |[
1207  * <menu id='edit-menu'>
1208  *   <section>
1209  *     <item label='Undo'/>
1210  *     <item label='Redo'/>
1211  *   </section>
1212  *   <section>
1213  *     <item label='Cut'/>
1214  *     <item label='Copy'/>
1215  *     <item label='Paste'/>
1216  *   </section>
1217  * </menu>
1218  * ]|
1219  *
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).
1226  * |[
1227  * <menu id='edit-menu'>
1228  *   <item>
1229  *     <link name='section'>
1230  *       <item label='Undo'/>
1231  *       <item label='Redo'/>
1232  *     </link>
1233  *   </item>
1234  *   <item>
1235  *     <link name='section'>
1236  *       <item label='Cut'/>
1237  *       <item label='Copy'/>
1238  *       <item label='Paste'/>
1239  *     </link>
1240  *   </item>
1241  * </menu>
1242  * ]|
1243  *
1244  * Returns: a new #GMenuItem
1245  *
1246  * Since: 2.32
1247  */
1248 GMenuItem *
1249 g_menu_item_new_section (const gchar *label,
1250                          GMenuModel  *section)
1251 {
1252   GMenuItem *menu_item;
1253
1254   menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1255
1256   if (label != NULL)
1257     g_menu_item_set_label (menu_item, label);
1258
1259   g_menu_item_set_section (menu_item, section);
1260
1261   return menu_item;
1262 }
1263
1264 /**
1265  * g_menu_item_new_from_model:
1266  * @model: a #GMenuModel
1267  * @item_index: the index of an item in @model
1268  *
1269  * Creates a #GMenuItem as an exact copy of an existing menu item in a
1270  * #GMenuModel.
1271  *
1272  * @item_index must be valid (ie: be sure to call
1273  * g_menu_model_get_n_items() first).
1274  *
1275  * Returns: a new #GMenuItem.
1276  *
1277  * Since: 2.34
1278  */
1279 GMenuItem *
1280 g_menu_item_new_from_model (GMenuModel *model,
1281                             gint        item_index)
1282 {
1283   GMenuModelClass *class = G_MENU_MODEL_GET_CLASS (model);
1284   GMenuItem *menu_item;
1285
1286   menu_item = g_object_new (G_TYPE_MENU_ITEM, NULL);
1287
1288   /* With some trickery we can be pretty efficient.
1289    *
1290    * A GMenuModel must either implement iterate_item_attributes() or
1291    * get_item_attributes().  If it implements get_item_attributes() then
1292    * we are in luck -- we can just take a reference on the returned
1293    * hashtable and mark ourselves as copy-on-write.
1294    *
1295    * In the case that the model is based on get_item_attributes (which
1296    * is the case for both GMenu and GDBusMenuModel) then this is
1297    * basically just g_hash_table_ref().
1298    */
1299   if (class->get_item_attributes)
1300     {
1301       GHashTable *attributes = NULL;
1302
1303       class->get_item_attributes (model, item_index, &attributes);
1304       if (attributes)
1305         {
1306           g_hash_table_unref (menu_item->attributes);
1307           menu_item->attributes = attributes;
1308           menu_item->cow = TRUE;
1309         }
1310     }
1311   else
1312     {
1313       GMenuAttributeIter *iter;
1314       const gchar *attribute;
1315       GVariant *value;
1316
1317       iter = g_menu_model_iterate_item_attributes (model, item_index);
1318       while (g_menu_attribute_iter_get_next (iter, &attribute, &value))
1319         g_hash_table_insert (menu_item->attributes, g_strdup (attribute), value);
1320       g_object_unref (iter);
1321     }
1322
1323   /* Same story for the links... */
1324   if (class->get_item_links)
1325     {
1326       GHashTable *links = NULL;
1327
1328       class->get_item_links (model, item_index, &links);
1329       if (links)
1330         {
1331           g_hash_table_unref (menu_item->links);
1332           menu_item->links = links;
1333           menu_item->cow = TRUE;
1334         }
1335     }
1336   else
1337     {
1338       GMenuLinkIter *iter;
1339       const gchar *link;
1340       GMenuModel *value;
1341
1342       iter = g_menu_model_iterate_item_links (model, item_index);
1343       while (g_menu_link_iter_get_next (iter, &link, &value))
1344         g_hash_table_insert (menu_item->links, g_strdup (link), value);
1345       g_object_unref (iter);
1346     }
1347
1348   return menu_item;
1349 }
1350
1351 /**
1352  * g_menu_item_set_icon:
1353  * @menu_item: a #GMenuItem
1354  * @icon: a #GIcon, or %NULL
1355  *
1356  * Sets (or unsets) the icon on @menu_item.
1357  *
1358  * This call is the same as calling g_icon_serialize() and using the
1359  * result as the value to g_menu_item_set_attribute_value() for
1360  * %G_MENU_ATTRIBUTE_ICON.
1361  *
1362  * This API is only intended for use with "noun" menu items; things like
1363  * bookmarks or applications in an "Open With" menu.  Don't use it on
1364  * menu items corresponding to verbs (eg: stock icons for 'Save' or
1365  * 'Quit').
1366  *
1367  * If @icon is %NULL then the icon is unset.
1368  *
1369  * Since: 2.38
1370  **/
1371 void
1372 g_menu_item_set_icon (GMenuItem *menu_item,
1373                       GIcon     *icon)
1374 {
1375   GVariant *value;
1376
1377   g_return_if_fail (G_IS_MENU_ITEM (menu_item));
1378   g_return_if_fail (G_IS_ICON (icon));
1379
1380   if (icon != NULL)
1381     value = g_icon_serialize (icon);
1382   else
1383     value = NULL;
1384
1385   g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_ICON, value);
1386   if (value)
1387     g_variant_unref (value);
1388 }