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