GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkMenuItem

## Name

GtkMenuItem -- the widget used for item in menus

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkMenuItem;
    GtkWidget*  gtk_menu_item_new               (void);
    GtkWidget*  gtk_menu_item_new_with_label    (const gchar *label);
    void        gtk_menu_item_set_submenu       (GtkMenuItem *menu_item,
                                                 GtkWidget *submenu);
    void        gtk_menu_item_remove_submenu    (GtkMenuItem *menu_item);
    void        gtk_menu_item_set_placement     (GtkMenuItem *menu_item,
                                                 GtkSubmenuPlacement placement);
    void        gtk_menu_item_configure         (GtkMenuItem *menu_item,
                                                 gint show_toggle_indicator,
                                                 gint show_submenu_indicator);
    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_right_justify     (GtkMenuItem *menu_item);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBin
                         +----GtkItem
                               +----GtkMenuItem

## Signal Prototypes

    "activate"  void        user_function      (GtkMenuItem *menuitem,
                                                gpointer user_data);
    "activate-item"
                void        user_function      (GtkMenuItem *menuitem,
                                                gpointer user_data);

## 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

### struct GtkMenuItem

    struct 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 simple GtlLabel.

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

### 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_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_set_placement ()

    void        gtk_menu_item_set_placement     (GtkMenuItem *menu_item,
                                                 GtkSubmenuPlacement placement);

Specifies the placement of the submenu around the menu item. The placement is usually GTK_LEFT_RIGHT for menu items in a popup menu and GTK_TOP_BOTTOM in menu bars.

This function is useless in usual applications.

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

### gtk_menu_item_configure ()

    void        gtk_menu_item_configure         (GtkMenuItem *menu_item,
                                                 gint show_toggle_indicator,
                                                 gint show_submenu_indicator);

Sets whether the menu item should show a submenu indicator, which is a right arrow.

`menu_item` : | the menu item
`show_toggle_indicator` : | unused
`show_submenu_indicator` : | whether to show the arrow or not

### 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_right_justify ()

    void        gtk_menu_item_right_justify     (GtkMenuItem *menu_item);

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

`menu_item` : | the menu item

## Signals

### The "activate" signal

    void        user_function                  (GtkMenuItem *menuitem,
                                                gpointer user_data);

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);

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.

## 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.

<<< Previous Page | Home | Up | Next Page >>>
GtkMenuBar | GtkMenuShell