Gtk.MenuItem¶

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:

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

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.