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

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.