Gtk.MenuButton

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.Button Gtk.Button Gtk.Actionable->Gtk.Button Gtk.Activatable->Gtk.Button Gtk.Bin Gtk.Bin Gtk.Bin->Gtk.Button Gtk.Buildable->Gtk.Widget Gtk.ToggleButton Gtk.ToggleButton Gtk.Button->Gtk.ToggleButton Gtk.Container Gtk.Container Gtk.Container->Gtk.Bin Gtk.MenuButton Gtk.MenuButton Gtk.ToggleButton->Gtk.MenuButton Gtk.Widget->Gtk.Container

Example

../_images/MenuButton.png
Subclasses:None

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)

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()[source]
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()[source]
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()[source]
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()[source]
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()[source]
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()[source]
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()[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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.