Gtk.MenuItem

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Actionable Gtk.Actionable GObject.GInterface->Gtk.Actionable Gtk.Activatable Gtk.Activatable GObject.GInterface->Gtk.Activatable Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.MenuItem Gtk.MenuItem Gtk.Actionable->Gtk.MenuItem Gtk.Activatable->Gtk.MenuItem Gtk.Bin Gtk.Bin Gtk.Bin->Gtk.MenuItem Gtk.Buildable->Gtk.Widget Gtk.Container Gtk.Container Gtk.Container->Gtk.Bin Gtk.Widget->Gtk.Container

Subclasses:

Gtk.CheckMenuItem, Gtk.ImageMenuItem, Gtk.SeparatorMenuItem, Gtk.TearoffMenuItem

Methods

Inherited:

Gtk.Bin (1), Gtk.Container (35), Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10), Gtk.Actionable (5), Gtk.Activatable (6)

Structs:

Gtk.ContainerClass (5), Gtk.WidgetClass (12), GObject.ObjectClass (5)

class

new ()

class

new_with_label (label)

class

new_with_mnemonic (label)

activate ()

deselect ()

get_accel_path ()

get_label ()

get_reserve_indicator ()

get_right_justified ()

get_submenu ()

get_use_underline ()

select ()

set_accel_path (accel_path)

set_label (label)

set_reserve_indicator (reserve)

set_right_justified (right_justified)

set_submenu (submenu)

set_use_underline (setting)

toggle_size_allocate (allocation)

toggle_size_request (requisition)

Virtual Methods

Inherited:

Gtk.Container (10), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10), Gtk.Actionable (4), Gtk.Activatable (2)

do_activate ()

do_activate_item ()

do_deselect ()

do_get_label ()

do_select ()

do_set_label (label)

do_toggle_size_allocate (allocation)

do_toggle_size_request (requisition)

Properties

Inherited:

Gtk.Container (3), Gtk.Widget (39), Gtk.Actionable (2), Gtk.Activatable (2)

Name

Type

Flags

Short Description

accel-path

str

r/w

Sets the accelerator path of the menu item

label

str

r/w

The text for the child label

right-justified

bool

d/r/w/en

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

submenu

Gtk.Menu

r/w

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

use-underline

bool

r/w/en

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

Style Properties

Inherited:

Gtk.Widget (17)

Name

Type

Default

Flags

Short Description

arrow-scaling

float

0.800000011920929

d/r

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

arrow-spacing

int

10

d/r

Space between label and arrow deprecated

horizontal-padding

int

0

d/r

Padding to left and right of the menu item deprecated

selected-shadow-type

Gtk.ShadowType

Gtk.ShadowType.NONE

d/r

Shadow type when item is selected deprecated

toggle-spacing

int

5

d/r

Space between icon and label deprecated

width-chars

int

12

d/r

The minimum desired width of the menu item in characters deprecated

Signals

Inherited:

Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name

Short Description

activate

Emitted when the item is activated.

activate-item

Emitted when the item is activated, but also if the menu item has a submenu.

deselect

select

toggle-size-allocate

toggle-size-request

Fields

Inherited:

Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name

Type

Access

Description

bin

Gtk.Bin

r

Class Details

class Gtk.MenuItem(*args, **kwargs)
Bases:

Gtk.Bin, Gtk.Actionable, Gtk.Activatable

Abstract:

No

Structure:

Gtk.MenuItemClass

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

As a Gtk.MenuItem derives from Gtk.Bin it can hold any valid child widget, although only a few are really useful.

By default, a Gtk.MenuItem sets a Gtk.AccelLabel as its child. Gtk.MenuItem has direct functions to set the label and its mnemonic. For more advanced label settings, you can fetch the child widget from the Gtk.Bin.

An example for setting markup and accelerator on a MenuItem:

GtkWidget *menu_item = gtk_menu_item_new_with_label ("Example Menu Item");

GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item));
gtk_label_set_markup (GTK_LABEL (child), "<i>new label</i> with <b>markup</b>");
gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0);
Gtk.MenuItem as Gtk.Buildable

The Gtk.MenuItem implementation of the Gtk.Buildable interface supports adding a submenu by specifying “submenu” as the “type” attribute of a <child> element.

An example of UI definition fragment with submenus:

<object class="GtkMenuItem">
  <child type="submenu">
    <object class="GtkMenu"/>
  </child>
</object>
CSS nodes
menuitem
├── <child>
╰── [arrow.right]

Gtk.MenuItem has a single CSS node with name menuitem. If the menuitem has a submenu, it gets another CSS node with name arrow, which has the .left or .right style class.

classmethod new()[source]
Returns:

the newly created Gtk.MenuItem

Return type:

Gtk.Widget

Creates a new Gtk.MenuItem.

classmethod new_with_label(label)[source]
Parameters:

label (str) – the text for the label

Returns:

the newly created Gtk.MenuItem

Return type:

Gtk.Widget

Creates a new Gtk.MenuItem whose child is a Gtk.Label.

classmethod new_with_mnemonic(label)[source]
Parameters:

label (str) – The text of the button, with an underscore in front of the mnemonic character

Returns:

a new Gtk.MenuItem

Return type:

Gtk.Widget

Creates a new Gtk.MenuItem 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.

activate()[source]

Emits the Gtk.MenuItem ::activate signal on the given item

deselect()[source]

Emits the Gtk.MenuItem ::deselect signal on the given item.

get_accel_path()[source]
Returns:

the accelerator path corresponding to this menu item’s functionality, or None if not set

Return type:

str or None

Retrieve the accelerator path that was previously set on self.

See Gtk.MenuItem.set_accel_path() for details.

New in version 2.14.

get_label()[source]
Returns:

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

Return type:

str

Sets text on the self label

New in version 2.16.

get_reserve_indicator()[source]
Returns:

True if self always reserves space for the submenu indicator

Return type:

bool

Returns whether the self reserves space for the submenu indicator, regardless if it has a submenu or not.

New in version 3.0.

get_right_justified()[source]
Returns:

True if the menu item will appear at the far right if added to a menu bar.

Return type:

bool

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

Deprecated since version 3.2: See Gtk.MenuItem.set_right_justified()

get_submenu()[source]
Returns:

submenu for this menu item, or None if none

Return type:

Gtk.Widget or None

Gets the submenu underneath this menu item, if any. See Gtk.MenuItem.set_submenu().

get_use_underline()[source]
Returns:

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

Return type:

bool

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

New in version 2.16.

select()[source]

Emits the Gtk.MenuItem ::select signal on the given item.

set_accel_path(accel_path)[source]
Parameters:

accel_path (str or None) – accelerator path, corresponding to this menu item’s functionality, or None to unset the current path.

Set the accelerator path on self, through which runtime changes of the menu item’s accelerator caused by the user can be identified and saved to persistent storage (see Gtk.AccelMap.save() on this). To set up a default accelerator for this menu item, call Gtk.AccelMap.add_entry() with the same accel_path. See also Gtk.AccelMap.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 GLib.intern_static_string().

set_label(label)[source]
Parameters:

label (str) – the text you want to set

Sets text on the self label

New in version 2.16.

set_reserve_indicator(reserve)[source]
Parameters:

reserve (bool) – the new value

Sets whether the self should reserve space for the submenu indicator, regardless if it actually has a submenu or not.

There should be little need for applications to call this functions.

New in version 3.0.

set_right_justified(right_justified)[source]
Parameters:

right_justified (bool) – if True the menu item will appear at the far right if added to a menu bar

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

Deprecated since version 3.2: If you insist on using it, use Gtk.Widget.set_hexpand() and Gtk.Widget.set_halign().

set_submenu(submenu)[source]
Parameters:

submenu (Gtk.Menu or None) – the submenu, or None

Sets or replaces the menu item’s submenu, or removes it when a None submenu is passed.

set_use_underline(setting)[source]
Parameters:

setting (bool) – True if underlines in the text indicate mnemonics

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

New in version 2.16.

toggle_size_allocate(allocation)[source]
Parameters:

allocation (int) – the allocation to use as signal data.

Emits the Gtk.MenuItem ::toggle-size-allocate signal on the given item.

toggle_size_request(requisition)[source]
Parameters:

requisition (int) – the requisition to use as signal data.

Returns:

the requisition to use as signal data.

Return type:

requisition: int

Emits the Gtk.MenuItem ::toggle-size-request signal on the given item.

do_activate() virtual

Emits the Gtk.MenuItem ::activate signal on the given item

do_activate_item() virtual

Signal emitted when the item is activated, but also if the menu item has a submenu.

do_deselect() virtual

Emits the Gtk.MenuItem ::deselect signal on the given item.

do_get_label() virtual
Returns:

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

Return type:

str

Sets text on the menu_item label

New in version 2.16.

do_select() virtual

Emits the Gtk.MenuItem ::select signal on the given item.

do_set_label(label) virtual
Parameters:

label (str) – the text you want to set

Sets text on the menu_item label

New in version 2.16.

do_toggle_size_allocate(allocation) virtual
Parameters:

allocation (int) – the allocation to use as signal data.

Emits the Gtk.MenuItem ::toggle-size-allocate signal on the given item.

do_toggle_size_request(requisition) virtual
Parameters:

requisition (int) – the requisition to use as signal data.

Returns:

the requisition to use as signal data.

Return type:

requisition: int

Emits the Gtk.MenuItem ::toggle-size-request signal on the given item.

Signal Details

Gtk.MenuItem.signals.activate(menu_item)
Signal Name:

activate

Flags:

RUN_FIRST, ACTION

Parameters:

menu_item (Gtk.MenuItem) – The object which received the signal

Emitted when the item is activated.

Gtk.MenuItem.signals.activate_item(menu_item)
Signal Name:

activate-item

Flags:

RUN_FIRST

Parameters:

menu_item (Gtk.MenuItem) – The object which received the signal

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

Gtk.MenuItem.signals.deselect(menu_item)
Signal Name:

deselect

Flags:

RUN_FIRST

Parameters:

menu_item (Gtk.MenuItem) – The object which received the signal

Gtk.MenuItem.signals.select(menu_item)
Signal Name:

select

Flags:

RUN_FIRST

Parameters:

menu_item (Gtk.MenuItem) – The object which received the signal

Gtk.MenuItem.signals.toggle_size_allocate(menu_item, object)
Signal Name:

toggle-size-allocate

Flags:

RUN_FIRST

Parameters:
  • menu_item (Gtk.MenuItem) – The object which received the signal

  • object (int) –

Gtk.MenuItem.signals.toggle_size_request(menu_item, object)
Signal Name:

toggle-size-request

Flags:

RUN_FIRST

Parameters:

Property Details

Gtk.MenuItem.props.accel_path
Name:

accel-path

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

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.

New in version 2.14.

Gtk.MenuItem.props.label
Name:

label

Type:

str

Default Value:

''

Flags:

READABLE, WRITABLE

The text for the child label.

New in version 2.16.

Gtk.MenuItem.props.right_justified
Name:

right-justified

Type:

bool

Default Value:

False

Flags:

DEPRECATED, READABLE, WRITABLE, EXPLICIT_NOTIFY

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

New in version 2.14.

Deprecated since version ???.

Gtk.MenuItem.props.submenu
Name:

submenu

Type:

Gtk.Menu

Default Value:

None

Flags:

READABLE, WRITABLE

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

New in version 2.12.

Gtk.MenuItem.props.use_underline
Name:

use-underline

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

True if underlines in the text indicate mnemonics.

New in version 2.16.