GtkMenuItem

## GtkMenuItem GtkMenuItem — The widget used for item in menus |

## Synopsis

    #include <gtk/gtk.h>

                GtkMenuItem;
    GtkWidget*  gtk_menu_item_new               (void);
    GtkWidget*  gtk_menu_item_new_with_label    (const gchar *label);
    GtkWidget*  gtk_menu_item_new_with_mnemonic (const gchar *label);
    void        gtk_menu_item_set_right_justified
                                                (GtkMenuItem *menu_item,
                                                 gboolean right_justified);
    void        gtk_menu_item_set_submenu       (GtkMenuItem *menu_item,
                                                 GtkWidget *submenu);
    void        gtk_menu_item_set_accel_path    (GtkMenuItem *menu_item,
                                                 const gchar *accel_path);
    void        gtk_menu_item_remove_submenu    (GtkMenuItem *menu_item);
    void        gtk_menu_item_select            (GtkMenuItem *menu_item);
    void        gtk_menu_item_deselect          (GtkMenuItem *menu_item);
    void        gtk_menu_item_activate          (GtkMenuItem *menu_item);
    void        gtk_menu_item_toggle_size_request
                                                (GtkMenuItem *menu_item,
                                                 gint *requisition);
    void        gtk_menu_item_toggle_size_allocate
                                                (GtkMenuItem *menu_item,
                                                 gint allocation);
    #define     gtk_menu_item_right_justify     (menu_item)
    gboolean    gtk_menu_item_get_right_justified
                                                (GtkMenuItem *menu_item);
    GtkWidget*  gtk_menu_item_get_submenu       (GtkMenuItem *menu_item);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkItem
                                           +----GtkMenuItem
                                                 +----GtkCheckMenuItem
                                                 +----GtkImageMenuItem
                                                 +----GtkSeparatorMenuItem
                                                 +----GtkTearoffMenuItem

## Implemented Interfaces

GtkMenuItem implements AtkImplementorIface.

## Style Properties

      "arrow-spacing"        gint                  : Read
      "horizontal-padding"   gint                  : Read
      "selected-shadow-type" GtkShadowType         : Read
      "toggle-spacing"       gint                  : Read

## Signals

    "activate"  void        user_function      (GtkMenuItem *menuitem,
                                                gpointer     user_data)      : Run first / Action
    "activate-item"
                void        user_function      (GtkMenuItem *menuitem,
                                                gpointer     user_data)      : Run first
    "toggle-size-allocate"
                void        user_function      (GtkMenuItem *menuitem,
                                                gint         arg1,
                                                gpointer     user_data)      : Run first
    "toggle-size-request"
                void        user_function      (GtkMenuItem *menuitem,
                                                gpointer     arg1,
                                                gpointer     user_data)      : Run first

## Description

The GtkMenuItem widget and the derived widgets are the only valid childs for menus. Their function is to correctly handle highlighting, alignment, events and submenus.

As it derives from GtkBin it can hold any valid child widget, altough only a few are really useful.

## Details

### GtkMenuItem

    typedef struct _GtkMenuItem GtkMenuItem;

### gtk_menu_item_new ()

    GtkWidget*  gtk_menu_item_new               (void);

Creates a new GtkMenuItem.

Returns : | the newly created GtkMenuItem

### gtk_menu_item_new_with_label ()

    GtkWidget*  gtk_menu_item_new_with_label    (const gchar *label);

Creates a new GtkMenuItem whose child is a GtkLabel.

`label` : | the text for the label
Returns : | the newly created GtkMenuItem

### gtk_menu_item_new_with_mnemonic ()

    GtkWidget*  gtk_menu_item_new_with_mnemonic (const gchar *label);

Creates a new GtkMenuItem containing a label. The label will be created using `gtk_label_new_with_mnemonic()`, so underscores in `label` indicate the mnemonic for the menu item.

`label` : | The text of the button, with an underscore in front of the mnemonic character
Returns : | a new GtkMenuItem

### gtk_menu_item_set_right_justified ()

    void        gtk_menu_item_set_right_justified
                                                (GtkMenuItem *menu_item,
                                                 gboolean right_justified);

Sets whether the menu item appears justified at the right side of a menu bar. This was traditionally done for "Help" menu items, but is now considered a bad idea. (If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the left.)

`menu_item` : | a GtkMenuItem.
`right_justified` : | if `TRUE` the menu item will appear at the far right if added to a menu bar.

### gtk_menu_item_set_submenu ()

    void        gtk_menu_item_set_submenu       (GtkMenuItem *menu_item,
                                                 GtkWidget *submenu);

Sets the widget submenu, or changes it.

`menu_item` : | the menu item widget
`submenu` : | the submenu

### gtk_menu_item_set_accel_path ()

    void        gtk_menu_item_set_accel_path    (GtkMenuItem *menu_item,
                                                 const gchar *accel_path);

Set the accelerator path on `menu_item`, through which runtime changes of the menu item's accelerator caused by the user can be identified and saved to persistant storage (see `gtk_accel_map_save()` on this). To setup a default accelerator for this menu item, call `gtk_accel_map_add_entry()` with the same `accel_path`. See also `gtk_accel_map_add_entry()` on the specifics of accelerator paths, and `gtk_menu_set_accel_path()` for a more convenient variant of this function.

This function is basically a convenience wrapper that handles calling `gtk_widget_set_accel_path()` with the appropriate accelerator group for the menu item.

Note that you do need to set an accelerator on the parent menu with `gtk_menu_set_accel_group()` for this to work.

`menu_item` : | a valid GtkMenuItem
`accel_path` : | accelerator path, corresponding to this menu item's functionality, or `NULL` to unset the current path.

### gtk_menu_item_remove_submenu ()

    void        gtk_menu_item_remove_submenu    (GtkMenuItem *menu_item);

Removes the widget's submenu.

`menu_item` : | the menu item widget

### gtk_menu_item_select ()

    void        gtk_menu_item_select            (GtkMenuItem *menu_item);

Emits the "select" signal on the given item. Behaves exactly like gtk_item_select.

`menu_item` : | the menu item

### gtk_menu_item_deselect ()

    void        gtk_menu_item_deselect          (GtkMenuItem *menu_item);

Emits the "deselect" signal on the given item. Behaves exactly like gtk_item_deselect.

`menu_item` : | the menu item

### gtk_menu_item_activate ()

    void        gtk_menu_item_activate          (GtkMenuItem *menu_item);

Emits the "activate" signal on the given item

`menu_item` : | the menu item

### gtk_menu_item_toggle_size_request ()

    void        gtk_menu_item_toggle_size_request
                                                (GtkMenuItem *menu_item,
                                                 gint *requisition);

Emits the "toggle_size_request" signal on the given item.

`menu_item` : | the menu item
`requisition` : | the requisition to use as signal data.

### gtk_menu_item_toggle_size_allocate ()

    void        gtk_menu_item_toggle_size_allocate
                                                (GtkMenuItem *menu_item,
                                                 gint allocation);

Emits the "toggle_size_allocate" signal on the given item.

`menu_item` : | the menu item.
`allocation` : | the allocation to use as signal data.

### gtk_menu_item_right_justify()

    #define gtk_menu_item_right_justify(menu_item) gtk_menu_item_set_right_justified ((menu_item), TRUE)

### Warning

`gtk_menu_item_right_justify` is deprecated and should not be used in newly-written code.

Sets the menu item to be right-justified. Only useful for menu bars.

`menu_item` : | the menu item

### gtk_menu_item_get_right_justified ()

    gboolean    gtk_menu_item_get_right_justified
                                                (GtkMenuItem *menu_item);

Gets whether the menu item appears justified at the right side of the menu bar.

`menu_item` : | a GtkMenuItem
Returns : | `TRUE` if the menu item will appear at the far right if added to a menu bar.

### gtk_menu_item_get_submenu ()

    GtkWidget*  gtk_menu_item_get_submenu       (GtkMenuItem *menu_item);

Gets the submenu underneath this menu item, if any. See `gtk_menu_item_set_submenu()`.

`menu_item` : | a GtkMenuItem
Returns : | submenu for this menu item, or `NULL` if none.

## Style Property Details

### The "`arrow-spacing`" style property

      "arrow-spacing"        gint                  : Read

Space between label and arrow.

Allowed values: >= 0

Default value: 10

### The "`horizontal-padding`" style property

      "horizontal-padding"   gint                  : Read

Padding to left and right of the menu item.

Allowed values: >= 0

Default value: 3

### The "`selected-shadow-type`" style property

      "selected-shadow-type" GtkShadowType         : Read

Shadow type when item is selected.

Default value: GTK_SHADOW_NONE

### The "`toggle-spacing`" style property

      "toggle-spacing"       gint                  : Read

Space between icon and label.

Allowed values: >= 0

Default value: 5

## Signal Details

### The "activate" signal

    void        user_function                  (GtkMenuItem *menuitem,
                                                gpointer     user_data)      : Run first / Action

Emitted when the item is activated.

`menuitem` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "activate-item" signal

    void        user_function                  (GtkMenuItem *menuitem,
                                                gpointer     user_data)      : Run first

Emitted when the item is activated, but also if the menu item has a submenu. For normal applications, the relevant signal is "activate".

`menuitem` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "toggle-size-allocate" signal

    void        user_function                  (GtkMenuItem *menuitem,
                                                gint         arg1,
                                                gpointer     user_data)      : Run first

`menuitem` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "toggle-size-request" signal

    void        user_function                  (GtkMenuItem *menuitem,
                                                gpointer     arg1,
                                                gpointer     user_data)      : Run first

`menuitem` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkBin | for how to handle the child.
GtkItem | is the abstract class for all sorts of items.
GtkMenuShell | is always the parent of GtkMenuItem.