GtkMenuItem: GTK+ 2 Reference Manual

## GtkMenuItem GtkMenuItem |

## Functions

GtkWidget * | gtk_menu_item_new ()
GtkWidget * | gtk_menu_item_new_with_label ()
GtkWidget * | gtk_menu_item_new_with_mnemonic ()
void | gtk_menu_item_set_right_justified ()
gboolean | gtk_menu_item_get_right_justified ()
const gchar * | gtk_menu_item_get_label ()
void | gtk_menu_item_set_label ()
gboolean | gtk_menu_item_get_use_underline ()
void | gtk_menu_item_set_use_underline ()
void | gtk_menu_item_set_submenu ()
GtkWidget * | gtk_menu_item_get_submenu ()
void | gtk_menu_item_remove_submenu ()
void | gtk_menu_item_set_accel_path ()
const gchar * | gtk_menu_item_get_accel_path ()
void | gtk_menu_item_select ()
void | gtk_menu_item_deselect ()
void | gtk_menu_item_activate ()
void | gtk_menu_item_toggle_size_request ()
void | gtk_menu_item_toggle_size_allocate ()
#define | gtk_menu_item_right_justify()

## Properties

char * | accel-path | Read / Write
char * | label | Read / Write
gboolean | right-justified | Read / Write
GtkMenu * | submenu | Read / Write
gboolean | use-underline | Read / Write

## Style Properties

float | arrow-scaling | Read
int | arrow-spacing | Read
int | horizontal-padding | Read
GtkShadowType | selected-shadow-type | Read
int | toggle-spacing | Read
int | width-chars | Read

## Signals

void | activate | Action
void | activate-item | Run First
void | toggle-size-allocate | Run First
void | toggle-size-request | Run First

## Types and Values

struct | GtkMenuItem

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkContainer
                        ╰── GtkBin
                            ╰── GtkItem
                                ╰── GtkMenuItem
                                    ├── GtkCheckMenuItem
                                    ├── GtkImageMenuItem
                                    ├── GtkSeparatorMenuItem
                                    ╰── GtkTearoffMenuItem

## Implemented Interfaces

GtkMenuItem implements AtkImplementorIface, GtkBuildable and GtkActivatable.

## Includes

    #include <gtk/gtk.h>

## Description

## Functions

### gtk_menu_item_new ()

    GtkWidget *
    gtk_menu_item_new (void);

### gtk_menu_item_new_with_label ()

    GtkWidget *
    gtk_menu_item_new_with_label (const gchar *label);

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

#### Parameters

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

#### Parameters

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

#### Parameters

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_label ()

    const gchar *
    gtk_menu_item_get_label (GtkMenuItem *menu_item);

Sets `text` on the `menu_item` label

#### Parameters

menu_item | a GtkMenuItem |

#### Returns

The text in the `menu_item` label. This is the internal string used by the label, and must not be modified.

Since: 2.16

### gtk_menu_item_set_label ()

    void
    gtk_menu_item_set_label (GtkMenuItem *menu_item,
                             const gchar *label);

Sets `text` on the `menu_item` label

#### Parameters

menu_item | a GtkMenuItem |
label | the text you want to set |

Since: 2.16

### gtk_menu_item_get_use_underline ()

    gboolean
    gtk_menu_item_get_use_underline (GtkMenuItem *menu_item);

Checks if an underline in the text indicates the next character should be used for the mnemonic accelerator key.

#### Parameters

menu_item | a GtkMenuItem |

#### Returns

`TRUE` if an embedded underline in the label indicates the mnemonic accelerator key.

Since: 2.16

### gtk_menu_item_set_use_underline ()

    void
    gtk_menu_item_set_use_underline (GtkMenuItem *menu_item,
                                     gboolean setting);

If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

#### Parameters

menu_item | a GtkMenuItem |
setting | `TRUE` if underlines in the text indicate mnemonics |

Since: 2.16

### gtk_menu_item_set_submenu ()

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

Sets or replaces the menu item's submenu, or removes it when a `NULL` submenu is passed.

#### Parameters

menu_item | a GtkMenuItem |
submenu | the submenu, or `NULL`. | [allow-none]

### 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()`.

#### Parameters

menu_item | a GtkMenuItem |

#### Returns

submenu for this menu item, or `NULL` if none.

[transfer none]

### gtk_menu_item_remove_submenu ()

    void
    gtk_menu_item_remove_submenu (GtkMenuItem *menu_item);

`gtk_menu_item_remove_submenu` has been deprecated since version 2.12 and should not be used in newly-written code.

gtk_menu_item_remove_submenu() is deprecated and should not be used in newly written code. Use `gtk_menu_item_set_submenu()` instead.

Removes the widget's submenu.

#### Parameters

menu_item | a GtkMenuItem |

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

Note that `accel_path` string will be stored in a GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with `g_intern_static_string()`.

#### Parameters

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

### gtk_menu_item_get_accel_path ()

    const gchar *
    gtk_menu_item_get_accel_path (GtkMenuItem *menu_item);

Retrieve the accelerator path that was previously set on `menu_item` .

See `gtk_menu_item_set_accel_path()` for details.

#### Parameters

menu_item | a valid GtkMenuItem |

#### Returns

the accelerator path corresponding to this menu item's functionality, or `NULL` if not set

Since: 2.14

### gtk_menu_item_select ()

    void
    gtk_menu_item_select (GtkMenuItem *menu_item);

### gtk_menu_item_deselect ()

    void
    gtk_menu_item_deselect (GtkMenuItem *menu_item);

### gtk_menu_item_activate ()

    void
    gtk_menu_item_activate (GtkMenuItem *menu_item);

### gtk_menu_item_toggle_size_request ()

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

### gtk_menu_item_toggle_size_allocate ()

    void
    gtk_menu_item_toggle_size_allocate (GtkMenuItem *menu_item,
                                        gint allocation);

### gtk_menu_item_right_justify()

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

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

## Types and Values

### struct GtkMenuItem

    struct GtkMenuItem;

## Property Details

### The `“accel-path”` property

      “accel-path”               char *

Sets the accelerator path of the menu item, through which runtime changes of the menu item's accelerator caused by the user can be identified and saved to persistant storage.

Owner: GtkMenuItem

Flags: Read / Write

Default value: NULL

Since: 2.14

### The `“label”` property

      “label”                    char *

The text for the child label.

Owner: GtkMenuItem

Flags: Read / Write

Default value: ""

Since: 2.16

### The `“right-justified”` property

      “right-justified”          gboolean

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

Owner: GtkMenuItem

Flags: Read / Write

Default value: FALSE

Since: 2.14

### The `“submenu”` property

      “submenu”                  GtkMenu *

The submenu attached to the menu item, or NULL if it has none.

Owner: GtkMenuItem

Flags: Read / Write

Since: 2.12

### The `“use-underline”` property

      “use-underline”            gboolean

`TRUE` if underlines in the text indicate mnemonics

Owner: GtkMenuItem

Flags: Read / Write

Default value: FALSE

Since: 2.16

## Style Property Details

### The `“arrow-scaling”` style property

      “arrow-scaling”            float

Amount of space used up by arrow, relative to the menu item's font size.

Owner: GtkMenuItem

Flags: Read

Allowed values: [0,2]

Default value: 0.8

### The `“arrow-spacing”` style property

      “arrow-spacing”            int

Space between label and arrow.

Owner: GtkMenuItem

Flags: Read

Allowed values: >= 0

Default value: 10

### The `“horizontal-padding”` style property

      “horizontal-padding”       int

Padding to left and right of the menu item.

Owner: GtkMenuItem

Flags: Read

Allowed values: >= 0

Default value: 3

### The `“selected-shadow-type”` style property

      “selected-shadow-type”     GtkShadowType

Shadow type when item is selected.

Owner: GtkMenuItem

Flags: Read

Default value: GTK_SHADOW_NONE

### The `“toggle-spacing”` style property

      “toggle-spacing”           int

Space between icon and label.

Owner: GtkMenuItem

Flags: Read

Allowed values: >= 0

Default value: 5

### The `“width-chars”` style property

      “width-chars”              int

The minimum desired width of the menu item in characters.

Owner: GtkMenuItem

Flags: Read

Allowed values: >= 0

Default value: 12

Since: 2.14

## Signal Details

### The `“activate”` signal

    void
    user_function (GtkMenuItem *menuitem,
                   gpointer     user_data)

Flags: Action

### The `“activate-item”` signal

    void
    user_function (GtkMenuItem *menuitem,
                   gpointer     user_data)

Flags: Run First

### The `“toggle-size-allocate”` signal

    void
    user_function (GtkMenuItem *menuitem,
                   int          arg1,
                   gpointer     user_data)

Flags: Run First

### The `“toggle-size-request”` signal

    void
    user_function (GtkMenuItem *menuitem,
                   gpointer     arg1,
                   gpointer     user_data)

Flags: Run First