SplitButton

class SplitButton(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Actionable, Buildable, ConstraintTarget

A combined button and dropdown widget.

AdwSplitButton is typically used to present a set of actions in a menu, but allow access to one of them with a single click.

The API is very similar to Button and MenuButton, see their documentation for details.

CSS nodes

splitbutton[.image-button][.text-button]
├── button
│   ╰── <content>
├── separator
╰── menubutton
    ╰── button.toggle
        ╰── arrow

AdwSplitButton’s CSS node is called splitbutton. It contains the css nodes: button, separator, menubutton. See MenuButton documentation for the menubutton contents.

The main CSS node will contain the .image-button or .text-button style classes matching the button contents. The nested button nodes will never contain them.

Accessibility

AdwSplitButton uses the GTK_ACCESSIBLE_ROLE_GROUP role.

Constructors

class SplitButton

classmethod new() → Widget

Creates a new AdwSplitButton.

Methods

class SplitButton

get_can_shrink() → bool

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

Added in version 1.4.

get_child() → Widget | None

Gets the child widget.

get_direction() → ArrowType

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

get_dropdown_tooltip() → str

Gets the tooltip of the dropdown button of self.

Added in version 1.2.

get_icon_name() → str | None

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

get_label() → str | None

Gets the label for self.

get_menu_model() → MenuModel | None

Gets the menu model from which the popup will be created.

get_popover() → Popover | None

Gets the popover that will be popped up when the dropdown is clicked.

get_use_underline() → bool

Gets whether an underline in the text indicates a mnemonic.

popdown() → None

Dismisses the menu.

popup() → None

Pops up the menu.

set_can_shrink(can_shrink: bool) → None

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

If set to TRUE, the label will ellipsize.

See set_can_shrink and set_can_shrink.

Added in version 1.4.

Parameters:

can_shrink – whether the button can shrink

set_child(child: Widget | None = None) → None

Sets the child widget.

Setting the child widget will set label and icon_name to NULL.

Parameters:

child – the new child widget

set_direction(direction: ArrowType) → None

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

The dropdown arrow icon will point at the same direction.

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

If you pass GTK_ARROW_NONE, it’s equivalent to GTK_ARROW_DOWN.

Parameters:

direction – the direction

set_dropdown_tooltip(tooltip: str) → None

Sets the tooltip of the dropdown button of self.

The tooltip can be marked up with the Pango text markup language.

Added in version 1.2.

Parameters:

tooltip – the dropdown tooltip of self

set_icon_name(icon_name: str) → None

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

Setting the icon name will set label and child to NULL.

Parameters:

icon_name – the icon name to set

set_label(label: str) → None

Sets the label for self.

Setting the label will set icon_name and child to NULL.

Parameters:

label – the label to set

set_menu_model(menu_model: MenuModel | None = None) → None

Sets the menu model from which the popup will be created.

If the menu model is NULL, the dropdown is disabled.

A Popover will be created from the menu model with new_from_model. Actions will be connected as documented for this function.

If popover is already set, it will be dissociated from the button, and the property is set to NULL.

Parameters:

menu_model – the menu model

set_popover(popover: Popover | None = None) → None

Sets the popover that will be popped up when the dropdown is clicked.

If the popover is NULL, the dropdown is disabled.

If menu_model is set, the menu model is dissociated from the button, and the property is set to NULL.

Parameters:

popover – the popover

set_use_underline(use_underline: bool) → None

Sets whether an underline in the text indicates a mnemonic.

See label.

Parameters:

use_underline – whether an underline in the text indicates a mnemonic

Properties

class SplitButton

props.can_shrink: bool

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

If set to TRUE, the label will ellipsize.

See can_shrink and can_shrink.

Added in version 1.4.

props.child: Widget

The child widget.

Setting the child widget will set label and icon_name to NULL.

props.direction: ArrowType

The direction in which the popup will be popped up.

The dropdown arrow icon will point at the same direction.

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

If you pass GTK_ARROW_NONE, it’s equivalent to GTK_ARROW_DOWN.

props.dropdown_tooltip: str

The tooltip of the dropdown button.

The tooltip can be marked up with the Pango text markup language.

Added in version 1.2.

props.icon_name: str

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

Setting the icon name will set label and child to NULL.

props.label: str

The label for the button.

Setting the label will set icon_name and child to NULL.

props.menu_model: MenuModel

The GMenuModel from which the popup will be created.

If the menu model is NULL, the dropdown is disabled.

A Popover will be created from the menu model with new_from_model. Actions will be connected as documented for this function.

If popover is already set, it will be dissociated from the button, and the property is set to NULL.

props.popover: Popover

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

If the popover is NULL, the dropdown is disabled.

If menu_model is set, the menu model is dissociated from the button, and the property is set to NULL.

props.use_underline: bool

Whether an underline in the text indicates a mnemonic.

See label.

Signals

class SplitButton.signals

activate() → None

Emitted to animate press then release.

This is an action signal. Applications should never connect to this signal, but use the clicked signal.

clicked() → None

Emitted when the button has been activated (pressed and released).