gtk.MenuItem
Prev | The gtk Class Reference | Next

## gtk.MenuItem

gtk.MenuItem — the widget used for an item in menus

## Synopsis

    class gtk.MenuItem(gtk.Item):
        gtk.MenuItem(label=None, use_underline=True)
        def set_submenu(submenu)
        def get_submenu()
        def remove_submenu()
        def select()
        def deselect()
        def activate()
        def toggle_size_request()
        def toggle_size_allocate(allocation)
        def set_right_justified(right_justified)
        def get_right_justified()
        def set_accel_path(accel_path)
        def get_accel_path()
        def set_label(label)
        def get_label()
        def set_use_underline(setting)
        def get_use_underline()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.Item
                +-- gtk.MenuItem

## Implemented Interfaces

`gtk.MenuItem` implements `gtk.Buildable` `atk.ImplementorIFace`

## gtk.MenuItem Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"accel-path" | Read-Write | 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. Default value: `None`. Available in GTK+ 2.14.
"label" | Read-Write | The text for the child label. Available in GTK+ 2.16.
"right-justified" | Read-Write | Sets whether the menu item appears justified at the right side of a menu bar. Default value: `False`. Available in GTK+ 2.14.
"submenu" | Read-Write | The submenu attached to the menu item, or `None` if it has none. This property is available in GTK+ 2.12 and above.
"use-underline" | Read-Write | `True` if underlines in the text indicate mnemonics. Available in GTK+ 2.16.

## gtk.MenuItem Style Properties

gtk.Widget Style Properties

"arrow-scaling" | Read | Amount of space used up by arrow, relative to the menu item's font size. Allowed values: [0,2]. Default value: 0.8
"arrow-spacing" | Read | Space between label and arrow. Allowed values: >= 0. Default value: 10
"horizontal-padding" | Read | Padding to left and right of the menu item. Allowed values: >= 0. Default value: 3
"selected-shadow-type" | Read | The shadow type when the item is selected. Default value: `gtk.SHADOW_NONE`
"toggle-spacing" | Read | Space between icon and label. Allowed values: >= 0. Default value: 5
"width-chars" | Read | The minimum desired width of the menu item in characters. Allowed values: >= 0. Default value: 12. Available in GTK+ 2.14.

## gtk.MenuItem Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.Item Signal Prototypes

"activate" | `def callback(`menuitem`, `user_param1`, `...`)`
"activate-item" | `def callback(`menuitem`, `user_param1`, `...`)`
"toggle-size-allocate" | `def callback(`menuitem`, `allocation`, `user_param1`, `...`)`
"toggle-size-request" | `def callback(`menuitem`, `requisition`, `user_param1`, `...`)`

## Description

The `gtk.MenuItem` widget implements the appearance and behavior of menu items. The `gtk.MenuItem` and its derived widget subclasses are the only valid children of menus.

When menu items are selected and activated by a user they can:

- display a popup menu if they have an associated submenu
- invoke an associated function or method

As a `gtk.MenuItem` is a subclass of `gtk.Bin` it can hold any valid child widget.

## Constructor

        gtk.MenuItem(label=None, use_underline=True)

`label` : | a string to be used as the text of the menu item or `None`
`use_underline` : | if `True`, an underscore in the label text indicates the next character should be underlined and used for the mnemonic accelerator key if it is the first character so marked. Available in PyGTK 2.4 and above.
Returns : | a new `gtk.MenuItem` widget

Creates a new `gtk.MenuItem` widget and sets the text of the menu item label to the value of `label`. If `label` is `None` no label is created for the menu item. The text of label is parsed for underscore characters that indicate that the next character is a mnemonic accelerator.

In PyGTK 2.4 and above the `use_underline` parameter is available and defaults to `True`. If `use_underline` is set to `False` the label text will not be parsed for mnemonic characters.

## Methods

### gtk.MenuItem.set_submenu

        def set_submenu(submenu)

`submenu` : | the menu to use as the submenu

The `set_submenu`() method sets the menu specified by `submenu` as the submenu for the menu item.

### gtk.MenuItem.get_submenu

        def get_submenu()

Returns : | the submenu for this menu item, or `None` if there is no submenu.

The `get_submenu`() method returns the submenu widget associated with this menu item. If there is no submenu this method returns `None`. See `set_submenu`().

### gtk.MenuItem.remove_submenu

        def remove_submenu()

The `remove_submenu`() method removes the submenu associated with the menu item.

### gtk.MenuItem.select

        def select()

The `select`() method emits the "select" signal on the menu item.

### gtk.MenuItem.deselect

        def deselect()

The `deselect`() method emits the "deselect" signal on the menu item.

### gtk.MenuItem.activate

        def activate()

The `activate`() method emits the "activate" signal on the menu item.

### gtk.MenuItem.toggle_size_request

        def toggle_size_request()

Returns : | the size requisition

### Note

This method is available in PyGTK 2.4 and above.

The `toggle_size_request`() method emits the "toggle-size-request" signal on the menuitem and returns the size requested for the menuitem.

### gtk.MenuItem.toggle_size_allocate

        def toggle_size_allocate(allocation)

`allocation` : | the allocation size for the menu item

The `toggle_size_allocate`() method emits the "toggle-size-allocate" signal on the menu item.

### gtk.MenuItem.set_right_justified

        def set_right_justified(right_justified)

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

The `set_right_justified`() method sets the justification of the menu item according to the value of `right_justified`. If `right_justified` is `True` the menu item will appear at the right side of a menu bar. If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear on the left.

### gtk.MenuItem.get_right_justified

        def get_right_justified()

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

The `get_right_justified`() method gets the justification of the menu item. If `True` the menu item appears justified at the right side of the menu bar.

### gtk.MenuItem.set_accel_path

        def set_accel_path(accel_path)

`accel_path` : | the accelerator path, corresponding to this menu item

The `set_accel_path`() method sets the accelerator path on the menu item. The accelerator path provides access to the menu item's accelerator allowing user changes to be identified and saved to persistent storage. See also the `gtk.Menu.set_accel_path`() method for a more convenient variant of this function. This method is a convenience wrapper that handles calling `gtk.Widget.set_accel_path`() with the appropriate accelerator group for the menu item.

### gtk.MenuItem.get_accel_path

        def get_accel_path()

Returns : | the accelerator path corresponding to this menu item's functionality, or `None` if not set

The `get_accel_path`() method gets the accelerator path that was previously set on menu_item.

### gtk.MenuItem.set_label

        def set_label(label)

`label` : | the text you want to set.

### Note

This method is available in PyGTK 2.16 and above.

The `set_label`() method sets the text specified by `label` on the menu_item label .

### gtk.MenuItem.get_label

        def get_label()

Returns : | The text in the menu_item label.

### Note

This method is available in PyGTK 2.16 and above.

The `get_label`() method gets the text in the menu_item label.

### gtk.MenuItem.set_use_underline

        def set_use_underline(setting)

`setting` : | `True` if underlines in the text indicate mnemonics.

### Note

This method is available in PyGTK 2.16 and above.

The `set_use_underline`() method gets whether an underline in the text indicates the next character should be used for the mnemonic accelerator key.

### gtk.MenuItem.get_use_underline

        def get_use_underline()

Returns : | `True` if an embedded underline in the label indicates the mnemonic accelerator key.

### Note

This method is available in PyGTK 2.16 and above.

The `get_use_underline`() method checks if an underline in the text indicates the next character should be used for the mnemonic accelerator key.

## Signals

### The "activate" gtk.MenuItem Signal

        def callback(menuitem, user_param1, ...)

`menuitem` : | the menuitem that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "activate" signal is emitted when the menu item is activated.

### The "activate-item" gtk.MenuItem Signal

        def callback(menuitem, user_param1, ...)

`menuitem` : | the menuitem that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

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

### The "toggle-size-allocate" gtk.MenuItem Signal

        def callback(menuitem, allocation, user_param1, ...)

`menuitem` : | the menuitem that received the signal
`allocation` : | the size allocation for the menuitem
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "toggle-size-allocate" signal is emitted when the size allocation is changed.

### The "toggle-size-request" gtk.MenuItem Signal

        def callback(menuitem, requisition, user_param1, ...)

`menuitem` : | the menuitem that received the signal
`requisition` : | the pointer to the location to put the size request
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "toggle-size-request" signal is emitted when a new size request is needed.

Prev | Up | Next
gtk.MenuBar | Home | gtk.MenuShell