Gtk.MenuButton¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (183), GObject.Object (37), Gtk.Accessible (17), Gtk.Buildable (1)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`get_active` ()
	`get_always_show_arrow` ()
	`get_can_shrink` ()
	`get_child` ()
	`get_direction` ()
	`get_has_frame` ()
	`get_icon_name` ()
	`get_label` ()
	`get_menu_model` ()
	`get_popover` ()
	`get_primary` ()
	`get_use_underline` ()
	`popdown` ()
	`popup` ()
	`set_active` (active)
	`set_always_show_arrow` (always_show_arrow)
	`set_can_shrink` (can_shrink)
	`set_child` (child)
	`set_create_popup_func` (func, *user_data)
	`set_direction` (direction)
	`set_has_frame` (has_frame)
	`set_icon_name` (icon_name)
	`set_label` (label)
	`set_menu_model` (menu_model)
	`set_popover` (popover)
	`set_primary` (primary)
	`set_use_underline` (use_underline)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties¶

Inherited:: Gtk.Widget (35), Gtk.Accessible (1)

Name	Type	Flags
`active`	`bool`	r/w/en
`always-show-arrow`	`bool`	r/w/en
`can-shrink`	`bool`	r/w/en
`child`	`Gtk.Widget`	r/w/en
`direction`	`Gtk.ArrowType`	r/w/en
`has-frame`	`bool`	r/w/en
`icon-name`	`str`	r/w/en
`label`	`str`	r/w/en
`menu-model`	`Gio.MenuModel`	r/w
`popover`	`Gtk.Popover`	r/w
`primary`	`bool`	r/w/en
`use-underline`	`bool`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`activate`	Emitted to when the menu button is activated.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.MenuButton(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No

Displays a popup when clicked.

This popup can be provided either as a GtkPopover or as an abstract GMenuModel.

The GtkMenuButton widget can show either an icon (set with the [property`Gtk`.MenuButton:icon-name] property) or a label (set with the [property`Gtk`.MenuButton:label] property). If neither is explicitly set, a [class`Gtk`.Image] is automatically created, using an arrow image oriented according to [property`Gtk`.MenuButton:direction] or the generic “open-menu-symbolic” icon if the direction is not set.

The positioning of the popup is determined by the [property`Gtk`.MenuButton:direction] property of the menu button.

For menus, the [property`Gtk`.Widget:halign] and [property`Gtk`.Widget:valign] properties of the menu are also taken into account. For example, when the direction is Gtk.ArrowType.DOWN and the horizontal alignment is Gtk.Align.START, the menu will be positioned below the button, with the starting edge (depending on the text direction) of the menu aligned with the starting edge of the button. If there is not enough space below the button, the menu is popped up above the button instead. If the alignment would move part of the menu offscreen, it is “pushed in”.

| start                | center                | end                |
-         | —                  | —                   | —                |
**down**  |   |   |   |
**up**    |     |     |     |
**left**  |   |   |   |
**right** |  |  |  |

CSS nodes

`` menubutton ╰── button.toggle

╰── <content>
╰── [arrow]

``

GtkMenuButton has a single CSS node with name menubutton which contains a button node with a .toggle style class.

If the button contains an icon, it will have the .image-button style class, if it contains text, it will have .text-button style class. If an arrow is visible in addition to an icon, text or a custom child, it will also have .arrow-button style class.

Inside the toggle button content, there is an arrow node for the indicator, which will carry one of the .none, .up, .down, .left or .right style classes to indicate the direction that the menu will appear in. The CSS is expected to provide a suitable image for each of these cases using the -gtk-icon-source property.

Optionally, the menubutton node can carry the .circular style class to request a round appearance.

Accessibility

GtkMenuButton uses the [enum`Gtk`.AccessibleRole.button] role.

classmethod new()[source]¶

Returns:: The newly created GtkMenuButton
Return type:: Gtk.Widget

Creates a new GtkMenuButton widget with downwards-pointing arrow as the only child.

You can replace the child widget with another GtkWidget should you wish to.

get_active()[source]¶

Returns:: True if the button is active
Return type:: bool

Returns whether the menu button is active.

New in version 4.10.

get_always_show_arrow()[source]¶

Returns:: whether to show a dropdown arrow even when using an icon or a custom child.
Return type:: bool

Gets whether to show a dropdown arrow even when using an icon or a custom child.

New in version 4.4.

get_can_shrink()[source]¶

Returns:: true if the button can shrink, and false otherwise
Return type:: bool

Retrieves whether the button can be smaller than the natural size of its contents.

New in version 4.12.

get_child()[source]¶

Returns:: the child widget of self
Return type:: Gtk.Widget or None

Gets the child widget of self.

New in version 4.6.

get_direction()[source]¶

Returns:: a GtkArrowType value
Return type:: Gtk.ArrowType

Returns the direction the popup will be pointing at when popped up.

get_has_frame()[source]¶

Returns:: True if the button has a frame
Return type:: bool

Returns whether the button has a frame.

get_icon_name()[source]¶

Returns:: the name of the icon shown in the button
Return type:: str or None

Gets the name of the icon shown in the button.

get_label()[source]¶

Returns:: the label shown in the button
Return type:: str or None

Gets the label shown in the button

get_menu_model()[source]¶

Returns:: a GMenuModel
Return type:: Gio.MenuModel or None

Returns the GMenuModel used to generate the popup.

get_popover()[source]¶

Returns:: a GtkPopover or None
Return type:: Gtk.Popover or None

Returns the GtkPopover that pops out of the button.

If the button is not using a GtkPopover, this function returns None.

get_primary()[source]¶

Returns:: True if the button is a primary menu
Return type:: bool

Returns whether the menu button acts as a primary menu.

New in version 4.4.

get_use_underline()[source]¶

Returns:: True whether an embedded underline in the text indicates the mnemonic accelerator keys.
Return type:: bool

Returns whether an embedded underline in the text indicates a mnemonic.

popdown()[source]¶: Dismiss the menu.

popup()[source]¶: Pop up the menu.

set_active(active)[source]¶

Parameters:: active (bool) – whether the menu button is active

Sets whether the menu button is active.

New in version 4.10.

set_always_show_arrow(always_show_arrow)[source]¶

Parameters:: always_show_arrow (bool) – whether to show a dropdown arrow even when using an icon or a custom child

Sets whether to show a dropdown arrow even when using an icon or a custom child.

New in version 4.4.

set_can_shrink(can_shrink)[source]¶

Parameters:: can_shrink (bool) – whether the button can shrink

Sets whether the button size can be smaller than the natural size of its contents.

For text buttons, setting can_shrink to true will ellipsize the label.

For icon buttons, this function has no effect.

New in version 4.12.

set_child(child)[source]¶

Parameters:: child (Gtk.Widget or None) – the child widget

Sets the child widget of self.

Setting a child resets [property`Gtk`.MenuButton:label] and [property`Gtk`.MenuButton:icon-name].

If [property`Gtk`.MenuButton:always-show-arrow] is set to TRUE and [property`Gtk`.MenuButton:direction] is not GTK_ARROW_NONE, a dropdown arrow will be shown next to the child.

New in version 4.6.

set_create_popup_func(func, *user_data)[source]¶

Parameters:

func (Gtk.MenuButtonCreatePopupFunc or None) – function to call when a popup is about to be shown, but none has been provided via other means, or None to reset to default behavior
user_data (object or None) – user data to pass to func

Sets func to be called when a popup is about to be shown.

func should use one of

[method`Gtk`.MenuButton.set_popover]
[method`Gtk`.MenuButton.set_menu_model]

to set a popup for self. If func is non-None, self will always be sensitive.

Using this function will not reset the menu widget attached to self. Instead, this can be done manually in func.

set_direction(direction)[source]¶

Parameters:: direction (Gtk.ArrowType) – a GtkArrowType

Sets the direction in which the popup will be popped up.

If the button is automatically populated with an arrow icon, its direction will be changed to match.

If the does not fit in the available space in the given direction, GTK will its best to keep it inside the screen and fully visible.

If you pass Gtk.ArrowType.NONE for a direction, the popup will behave as if you passed Gtk.ArrowType.DOWN (although you won’t see any arrows).

set_has_frame(has_frame)[source]¶

Parameters:: has_frame (bool) – whether the button should have a visible frame

Sets the style of the button.

set_icon_name(icon_name)[source]¶

Parameters:: icon_name (str) – the icon name

Sets the name of an icon to show inside the menu button.

Setting icon name resets [property`Gtk`.MenuButton:label] and [property`Gtk`.MenuButton:child].

If [property`Gtk`.MenuButton:always-show-arrow] is set to TRUE and [property`Gtk`.MenuButton:direction] is not GTK_ARROW_NONE, a dropdown arrow will be shown next to the icon.

set_label(label)[source]¶

Parameters:: label (str) – the label

Sets the label to show inside the menu button.

Setting a label resets [property`Gtk`.MenuButton:icon-name] and [property`Gtk`.MenuButton:child].

If [property`Gtk`.MenuButton:direction] is not GTK_ARROW_NONE, a dropdown arrow will be shown next to the label.

set_menu_model(menu_model)[source]¶

Parameters:: menu_model (Gio.MenuModel or None) – a GMenuModel, or None to unset and disable the button

Sets the GMenuModel from which the popup will be constructed.

If menu_model is None, the button is disabled.

A [class`Gtk`.Popover] will be created from the menu model with [ctor`Gtk`.PopoverMenu.new_from_model]. Actions will be connected as documented for this function.

If [property`Gtk`.MenuButton:popover] is already set, it will be dissociated from the self, and the property is set to None.

set_popover(popover)[source]¶

Parameters:: popover (Gtk.Widget or None) – a GtkPopover, or None to unset and disable the button

Sets the GtkPopover that will be popped up when the self is clicked.

If popover is None, the button is disabled.

If [property`Gtk`.MenuButton:menu-model] is set, the menu model is dissociated from the self, and the property is set to None.

set_primary(primary)[source]¶

Parameters:: primary (bool) – whether the menubutton should act as a primary menu

Sets whether menu button acts as a primary menu.

Primary menus can be opened with the <kbd>F10</kbd> key.

New in version 4.4.

set_use_underline(use_underline)[source]¶

Parameters:: use_underline (bool) – True if underlines in the text indicate mnemonics

If true, an underline in the text indicates a mnemonic.

Signal Details¶

Gtk.MenuButton.signals.activate(menu_button)¶

Signal Name:: activate
Flags:: RUN_FIRST, ACTION
Parameters:: menu_button (Gtk.MenuButton) – The object which received the signal

Emitted to when the menu button is activated.

The ::activate signal on GtkMenuButton is an action signal and emitting it causes the button to pop up its menu.

New in version 4.4.

Property Details¶

Gtk.MenuButton.props.active¶

Name:: active
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the menu button is active.

New in version 4.10.

Gtk.MenuButton.props.always_show_arrow¶

Name:: always-show-arrow
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to show a dropdown arrow even when using an icon or a custom child.

New in version 4.4.

Gtk.MenuButton.props.can_shrink¶

Name:: can-shrink
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the size of the button can be made smaller than the natural size of its contents.

New in version 4.12.

Gtk.MenuButton.props.child¶

Name:: child
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The child widget.

New in version 4.6.

Gtk.MenuButton.props.direction¶

Name:: direction
Type:: Gtk.ArrowType
Default Value:: Gtk.ArrowType.DOWN
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The GtkArrowType representing the direction in which the menu or popover will be popped out.

Gtk.MenuButton.props.has_frame¶

Name:: has-frame
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the button has a frame.

Gtk.MenuButton.props.icon_name¶

Name:: icon-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The name of the icon used to automatically populate the button.

Gtk.MenuButton.props.label¶

Name:: label
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The label for the button.

Gtk.MenuButton.props.menu_model¶

Name:: menu-model
Type:: Gio.MenuModel
Default Value:: None
Flags:: READABLE, WRITABLE

The GMenuModel from which the popup will be created.

See [method`Gtk`.MenuButton.set_menu_model] for the interaction with the [property`Gtk`.MenuButton:popover] property.

Gtk.MenuButton.props.popover¶

Name:: popover
Type:: Gtk.Popover
Default Value:: None
Flags:: READABLE, WRITABLE

The GtkPopover that will be popped up when the button is clicked.

Gtk.MenuButton.props.primary¶

Name:: primary
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the menu button acts as a primary menu.

Primary menus can be opened using the <kbd>F10</kbd> key

New in version 4.4.

Gtk.MenuButton.props.use_underline¶

Name:: use-underline
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If set an underscore in the text indicates a mnemonic.