:right-sidebar: True

SplitButton
===================================================================

.. currentmodule:: gi.repository.Adw





.. class:: SplitButton(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Actionable`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



A combined button and dropdown widget.

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/split-button.png

``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 :obj:`~gi.repository.Gtk.Button` and :obj:`~gi.repository.Gtk.MenuButton`\, see
their documentation for details.

CSS nodes
--------------------------------------------------------------------------------


.. code-block::
    :dedent:

    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 :obj:`~gi.repository.Gtk.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.

Style classes
--------------------------------------------------------------------------------

``AdwSplitButton`` can use some of the same style classes as :obj:`~gi.repository.Gtk.Button`\:

- ```.suggested-action`` <style-classes.html#suggested-action>`__
- ```.destructive-action`` <style-classes.html#destructive-action>`__
- ```.flat`` <style-classes.html#flat>`__
- ```.raised`` <style-classes.html#raised>`__


Other style classes, like ``.pill``\, cannot be used.

Accessibility
--------------------------------------------------------------------------------

``AdwSplitButton`` uses the ``GTK_ACCESSIBLE_ROLE_GROUP`` role.


Constructors
------------

.. rst-class:: interim-class

.. class:: SplitButton
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new ``AdwSplitButton``\.













Methods
-------

.. rst-class:: interim-class

.. class:: SplitButton
   :no-index:


   .. method:: get_can_shrink() -> bool

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


      .. versionadded:: 1.4








   .. method:: get_child() -> ~gi.repository.Gtk.Widget | None

      Gets the child widget.









   .. method:: get_direction() -> ~gi.repository.Gtk.ArrowType

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









   .. method:: get_dropdown_tooltip() -> str

      Gets the tooltip of the dropdown button of ``self``\.


      .. versionadded:: 1.2








   .. method:: get_icon_name() -> str | None

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









   .. method:: get_label() -> str | None

      Gets the label for ``self``\.









   .. method:: get_menu_model() -> ~gi.repository.Gio.MenuModel | None

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









   .. method:: get_popover() -> ~gi.repository.Gtk.Popover | None

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









   .. method:: get_use_underline() -> bool

      Gets whether an underline in the text indicates a mnemonic.









   .. method:: popdown() -> None

      Dismisses the menu.









   .. method:: popup() -> None

      Pops up the menu.









   .. method:: 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 :obj:`~gi.repository.Gtk.Button.set_can_shrink` and
      :obj:`~gi.repository.Gtk.MenuButton.set_can_shrink`\.


      .. versionadded:: 1.4





      :param can_shrink: whether the button can shrink




   .. method:: set_child(child: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the child widget.

      Setting the child widget will set :obj:`~gi.repository.Adw.SplitButton.props.label` and
      :obj:`~gi.repository.Adw.SplitButton.props.icon_name` to ``NULL``\.






      :param child: the new child widget




   .. method:: set_direction(direction: ~gi.repository.Gtk.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``\.






      :param direction: the direction




   .. method:: 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.


      .. versionadded:: 1.2





      :param tooltip: the dropdown tooltip of ``self``




   .. method:: 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 :obj:`~gi.repository.Adw.SplitButton.props.label` and
      :obj:`~gi.repository.Adw.SplitButton.props.child` to ``NULL``\.






      :param icon_name: the icon name to set




   .. method:: set_label(label: str) -> None

      Sets the label for ``self``\.

      Setting the label will set :obj:`~gi.repository.Adw.SplitButton.props.icon_name` and
      :obj:`~gi.repository.Adw.SplitButton.props.child` to ``NULL``\.






      :param label: the label to set




   .. method:: set_menu_model(menu_model: ~gi.repository.Gio.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 :obj:`~gi.repository.Gtk.Popover` will be created from the menu model with
      :obj:`~gi.repository.Gtk.PopoverMenu.new_from_model`\. Actions will be connected as
      documented for this function.

      If :obj:`~gi.repository.Adw.SplitButton.props.popover` is already set, it will be dissociated from
      the button, and the property is set to ``NULL``\.






      :param menu_model: the menu model




   .. method:: set_popover(popover: ~gi.repository.Gtk.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 :obj:`~gi.repository.Adw.SplitButton.props.menu_model` is set, the menu model is dissociated
      from the button, and the property is set to ``NULL``\.






      :param popover: the popover




   .. method:: set_use_underline(use_underline: bool) -> None

      Sets whether an underline in the text indicates a mnemonic.

      See :obj:`~gi.repository.Adw.SplitButton.props.label`\.






      :param use_underline: whether an underline in the text indicates a mnemonic








Properties
----------

.. rst-class:: interim-class

.. class:: SplitButton
   :no-index:
   

   .. attribute:: props.can_shrink
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.child
      :type: ~gi.repository.Gtk.Widget

      The type of the None singleton.







   .. attribute:: props.direction
      :type: ~gi.repository.Gtk.ArrowType

      The type of the None singleton.







   .. attribute:: props.dropdown_tooltip
      :type: str

      The type of the None singleton.



      .. versionadded:: 1.2





   .. attribute:: props.icon_name
      :type: str

      The type of the None singleton.







   .. attribute:: props.label
      :type: str

      The type of the None singleton.







   .. attribute:: props.menu_model
      :type: ~gi.repository.Gio.MenuModel

      The type of the None singleton.







   .. attribute:: props.popover
      :type: ~gi.repository.Gtk.Popover

      The type of the None singleton.







   .. attribute:: props.use_underline
      :type: bool

      The type of the None singleton.











Signals
-------

.. rst-class:: interim-class

.. class:: SplitButton.signals
   :no-index:
   

   .. method:: activate() -> None

      Emitted to animate press then release.

      This is an action signal. Applications should never connect to this signal,
      but use the :obj:`~gi.repository.Adw.SplitButton.signals.clicked` signal.









   .. method:: clicked() -> None

      The type of the None singleton.