g_menu_insert_item ()

The "insertion" is actually done by copying all of the attribute and
link values of item
and using them to form a new item within menu
.
As such, item
itself is not really inserted, but rather, a menu item
that is exactly the same as the one presently described by item
.

This means that item
is essentially useless after the insertion
occurs. Any changes you make to it are ignored unless it is inserted
again (at which point its updated values will be copied).

The effect of having one menu appear as a section of another is
exactly as it sounds: the items from section
become a direct part of
the menu that menu_item
is added to.

Visual separation is typically displayed between two non-empty
sections. If label
is non-NULL then it will be encorporated into
this visual indication. This allows for labeled subsections of a
menu.

As a simple example, consider a typical "Edit" menu from a simple
program. It probably contains an "Undo" and "Redo" item, followed by
a separator, followed by "Cut", "Copy" and "Paste".

This would be accomplished by creating three GMenu instances. The
first would be populated with the "Undo" and "Redo" items, and the
second with the "Cut", "Copy" and "Paste" items. The first and
second menus would then be added as submenus of the third. In XML
format, this would look something like the following:

The following example is exactly equivalent. It is more illustrative
of the exact relationship between the menus and items (keeping in
mind that the 'link' element defines a new menu that is linked to the
containing one). The style of the second example is more verbose and
difficult to read (and therefore not recommended except for the
purpose of understanding what is really going on).

This API is only intended for use with "noun" menu items; things like
bookmarks or applications in an "Open With" menu. Don't use it on
menu items corresponding to verbs (eg: stock icons for 'Save' or
'Quit').

g_menu_item_set_action_and_target_value ()

If action
is NULL then both the "action" and "target" attributes
are unset (and target_value
is ignored).

If action
is non-NULL then the "action" attribute is set. The
"target" attribute is then set to the value of target_value
if it is
non-NULL or unset otherwise.

Normal menu items (ie: not submenu, section or other custom item
types) are expected to have the "action" attribute set to identify
the action that they are associated with. The state type of the
action help to determine the disposition of the menu item. See
GAction and GActionGroup for an overview of actions.

In general, clicking on the menu item will result in activation of
the named action with the "target" attribute given as the parameter
to the action invocation. If the "target" attribute is not set then
the action is invoked with no parameter.

If the action has no state then the menu item is usually drawn as a
plain menu item (ie: with no additional decoration).

If the action has a boolean state then the menu item is usually drawn
as a toggle menu item (ie: with a checkmark or equivalent
indication). The item should be marked as 'toggled' or 'checked'
when the boolean state is TRUE.

If the action has a string state then the menu item is usually drawn
as a radio menu item (ie: with a radio bullet or equivalent
indication). The item should be marked as 'selected' when the string
state is equal to the value of the target
property.

g_menu_item_set_action_and_target ()

If action
is NULL then both the "action" and "target" attributes
are unset (and format_string
is ignored along with the positional
parameters).

If action
is non-NULL then the "action" attribute is set.
format_string
is then inspected. If it is non-NULL then the proper
position parameters are collected to create a GVariant instance to
use as the target value. If it is NULL then the positional
parameters are ignored and the "target" attribute is unset.

g_menu_item_set_section ()

The effect of having one menu appear as a section of another is
exactly as it sounds: the items from section
become a direct part of
the menu that menu_item
is added to. See g_menu_item_new_section()
for more information about what it means for a menu item to be a
section.

g_menu_item_set_attribute_value ()

The attribute to set or unset is specified by attribute
. This
can be one of the standard attribute names G_MENU_ATTRIBUTE_LABEL,
G_MENU_ATTRIBUTE_ACTION, G_MENU_ATTRIBUTE_TARGET, or a custom
attribute name.
Attribute names are restricted to lowercase characters, numbers
and '-'. Furthermore, the names must begin with a lowercase character,
must not end with a '-', and must not contain consecutive dashes.

must consist only of lowercase
ASCII characters, digits and '-'.

If value
is non-NULL then it is used as the new value for the
attribute. If value
is NULL then the attribute is unset. If
the valueGVariant is floating, it is consumed.

g_menu_item_set_attribute ()

The attribute to set or unset is specified by attribute
. This
can be one of the standard attribute names G_MENU_ATTRIBUTE_LABEL,
G_MENU_ATTRIBUTE_ACTION, G_MENU_ATTRIBUTE_TARGET, or a custom
attribute name.
Attribute names are restricted to lowercase characters, numbers
and '-'. Furthermore, the names must begin with a lowercase character,
must not end with a '-', and must not contain consecutive dashes.

If format_string
is non-NULL then the proper position parameters
are collected to create a GVariant instance to use as the attribute
value. If it is NULL then the positional parameterrs are ignored
and the named attribute is unset.

g_menu_item_set_link ()

Links are used to establish a relationship between a particular menu
item and another menu. For example, G_MENU_LINK_SUBMENU is used to
associate a submenu with a particular menu item, and G_MENU_LINK_SECTION
is used to create a section. Other types of link can be used, but there
is no guarantee that clients will be able to make sense of them.
Link types are restricted to lowercase characters, numbers
and '-'. Furthermore, the names must begin with a lowercase character,
must not end with a '-', and must not contain consecutive dashes.