Gtk.MenuButton

Example

Subclasses:None

Methods

Inherited:Gtk.ToggleButton (10), Gtk.Button (29), 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 ()
	get_align_widget ()
	get_direction ()
	get_menu_model ()
	get_popover ()
	get_popup ()
	get_use_popover ()
	set_align_widget (align_widget)
	set_direction (direction)
	set_menu_model (menu_model)
	set_popover (popover)
	set_popup (menu)
	set_use_popover (use_popover)

Virtual Methods

Inherited:Gtk.ToggleButton (1), Gtk.Button (6), Gtk.Container (10), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10), Gtk.Actionable (4), Gtk.Activatable (2)

Properties

Inherited:Gtk.ToggleButton (3), Gtk.Button (9), Gtk.Container (3), Gtk.Widget (39), Gtk.Actionable (2), Gtk.Activatable (2)

Name	Type	Flags	Short Description
align-widget	Gtk.Container	r/w	The parent widget which the menu should align with.
direction	Gtk.ArrowType	r/w/en	The direction the arrow should point.
menu-model	Gio.MenuModel	r/w	The model from which the popup is made.
popover	Gtk.Popover	r/w	The popover
popup	Gtk.Menu	r/w	The dropdown menu.
use-popover	bool	r/w/en	Use a popover instead of a menu

Style Properties

Inherited:Gtk.Button (7), Gtk.Widget (17)

Signals

Inherited:Gtk.ToggleButton (1), Gtk.Button (6), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Fields

Inherited:Gtk.ToggleButton (1), Gtk.Button (6), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Type	Access	Description
parent	Gtk.ToggleButton	r

Class Details

class Gtk.MenuButton(*args, **kwargs)

Bases:Gtk.ToggleButton Abstract:No Structure:Gtk.MenuButtonClass

The Gtk.MenuButton widget is used to display a popup when clicked on. This popup can be provided either as a Gtk.Menu, a Gtk.Popover or an abstract Gio.MenuModel.

The Gtk.MenuButton widget can hold any valid child widget. That is, it can hold almost any other standard Gtk.Widget. The most commonly used child is Gtk.Image. If no widget is explicitely added to the Gtk.MenuButton, a Gtk.Image is automatically created, using an arrow image oriented according to 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 Gtk.MenuButton :direction property of the menu button.

For menus, the Gtk.Widget :halign and 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”.

Direction = Down

• halign = start
• halign = center
• halign = end

Direction = Up

• halign = start
• halign = center
• halign = end

Direction = Left

• valign = start
• valign = center
• valign = end

Direction = Right

• valign = start
• valign = center
• valign = end

CSS nodes

Gtk.MenuButton has a single CSS node with name button. To differentiate it from a plain Gtk.Button, it gets the .popup style class.

classmethod new()

Returns:The newly created Gtk.MenuButton widget Return type:Gtk.Widget

Creates a new Gtk.MenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another Gtk.Widget should you wish to.

New in version 3.6.

get_align_widget()

Returns:a Gtk.Widget value or None Return type:Gtk.Widget or None

Returns the parent Gtk.Widget to use to line up with menu.

New in version 3.6.

get_direction()

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

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

New in version 3.6.

get_menu_model()

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

Returns the Gio.MenuModel used to generate the popup.

New in version 3.6.

get_popover()

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

Returns the Gtk.Popover that pops out of the button. If the button is not using a Gtk.Popover, this function returns None.

New in version 3.12.

get_popup()

Returns:a Gtk.Menu or None Return type:Gtk.Menu or None

Returns the Gtk.Menu that pops out of the button. If the button does not use a Gtk.Menu, this function returns None.

New in version 3.6.

get_use_popover()

Returns:True if using a Gtk.Popover Return type:bool

Returns whether a Gtk.Popover or a Gtk.Menu will be constructed from the menu model.

New in version 3.12.

set_align_widget(align_widget)

Parameters:align_widget (Gtk.Widget or None) – a Gtk.Widget

Sets the Gtk.Widget to use to line the menu with when popped up. Note that the align_widget must contain the Gtk.MenuButton itself.

Setting it to None means that the menu will be aligned with the button itself.

Note that this property is only used with menus currently, and not for popovers.

New in version 3.6.

set_direction(direction)

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

Sets the direction in which the popup will be popped up, as well as changing the arrow’s direction. The child will not be changed to an arrow if it was customized.

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

New in version 3.6.

set_menu_model(menu_model)

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

Sets the Gio.MenuModel from which the popup will be constructed, or None to dissociate any existing menu model and disable the button.

Depending on the value of Gtk.MenuButton :use-popover, either a Gtk.Menu will be created with Gtk.Menu.new_from_model(), or a Gtk.Popover with Gtk.Popover.new_from_model(). In either case, actions will be connected as documented for these functions.

If Gtk.MenuButton :popup or Gtk.MenuButton :popover are already set, those widgets are dissociated from the self, and those properties are set to None.

New in version 3.6.

set_popover(popover)

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

Sets the Gtk.Popover that will be popped up when the self is clicked, or None to dissociate any existing popover and disable the button.

If Gtk.MenuButton :menu-model or Gtk.MenuButton :popup are set, those objects are dissociated from the self, and those properties are set to None.

New in version 3.12.

set_popup(menu)

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

Sets the Gtk.Menu that will be popped up when the self is clicked, or None to dissociate any existing menu and disable the button.

If Gtk.MenuButton :menu-model or Gtk.MenuButton :popover are set, those objects are dissociated from the self, and those properties are set to None.

New in version 3.6.

set_use_popover(use_popover)

Parameters:use_popover (bool) – True to construct a popover from the menu model

Sets whether to construct a Gtk.Popover instead of Gtk.Menu when Gtk.MenuButton.set_menu_model() is called. Note that this property is only consulted when a new menu model is set.

New in version 3.12.

Property Details

Gtk.MenuButton.props.align_widget

Name:align-widget Type:Gtk.Container Default Value:None Flags:READABLE, WRITABLE

The Gtk.Widget to use to align the menu with.

New in version 3.6.

Gtk.MenuButton.props.direction

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

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

New in version 3.6.

Gtk.MenuButton.props.menu_model

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

The Gio.MenuModel from which the popup will be created. Depending on the Gtk.MenuButton :use-popover property, that may be a menu or a popover.

See Gtk.MenuButton.set_menu_model() for the interaction with the Gtk.MenuButton :popup property.

New in version 3.6.

Gtk.MenuButton.props.popover

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

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

New in version 3.12.

Gtk.MenuButton.props.popup

Name:popup Type:Gtk.Menu Default Value:None Flags:READABLE, WRITABLE

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

New in version 3.6.

Gtk.MenuButton.props.use_popover

Name:use-popover Type:bool Default Value:True Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to construct a Gtk.Popover from the menu model, or a Gtk.Menu.

New in version 3.12.