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

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