:right-sidebar: True

MenuButton
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: MenuButton(**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.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



The ``GtkMenuButton`` widget is used to display a popup when clicked.


.. image:: https://docs.gtk.org/gtk4/menu-button.png


This popup can be provided either as a ``GtkPopover`` or as an abstract
``GMenuModel``.

The ``GtkMenuButton`` widget can show either an icon (set with the
:obj:`~gi.repository.Gtk.MenuButton.props.icon_name` property) or a label (set with the
:obj:`~gi.repository.Gtk.MenuButton.props.label` property). If neither is explicitly set,
a :obj:`~gi.repository.Gtk.Image` is automatically created, using an arrow image oriented
according to :obj:`~gi.repository.Gtk.MenuButton.props.direction` or the generic
“open-menu-symbolic” icon if the direction is not set.

The positioning of the popup is determined by the
:obj:`~gi.repository.Gtk.MenuButton.props.direction` property of the menu button.

For menus, the :obj:`~gi.repository.Gtk.Widget.props.halign` and :obj:`~gi.repository.Gtk.Widget.props.valign`
properties of the menu are also taken into account. For example, when the
direction is :const:`~gi.repository.Gtk.ArrowType.DOWN` and the horizontal alignment is :const:`~gi.repository.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”.

+-----------+------------------------------------------------------+-------------------------------------------------------+----------------------------------------------------+
|           | start                                                | center                                                | end                                                |
+===========+======================================================+=======================================================+====================================================+
| **down**  | .. image:: https://docs.gtk.org/gtk4/down-start.png  | .. image:: https://docs.gtk.org/gtk4/down-center.png  | .. image:: https://docs.gtk.org/gtk4/down-end.png  |
+-----------+------------------------------------------------------+-------------------------------------------------------+----------------------------------------------------+
| **up**    | .. image:: https://docs.gtk.org/gtk4/up-start.png    | .. image:: https://docs.gtk.org/gtk4/up-center.png    | .. image:: https://docs.gtk.org/gtk4/up-end.png    |
+-----------+------------------------------------------------------+-------------------------------------------------------+----------------------------------------------------+
| **left**  | .. image:: https://docs.gtk.org/gtk4/left-start.png  | .. image:: https://docs.gtk.org/gtk4/left-center.png  | .. image:: https://docs.gtk.org/gtk4/left-end.png  |
+-----------+------------------------------------------------------+-------------------------------------------------------+----------------------------------------------------+
| **right** | .. image:: https://docs.gtk.org/gtk4/right-start.png | .. image:: https://docs.gtk.org/gtk4/right-center.png | .. image:: https://docs.gtk.org/gtk4/right-end.png |
+-----------+------------------------------------------------------+-------------------------------------------------------+----------------------------------------------------+


CSS nodes
---------


.. code-block::
   :dedent:

   menubutton
   ╰── button.toggle
       ╰── <content>
            ╰── [arrow]


``GtkMenuButton`` has a single CSS node with name ``menubutton``
which contains a ``button`` node with a ``.toggle`` style class.

If the button contains an icon, it will have the ``.image-button`` style class,
if it contains text, it will have ``.text-button`` style class. If an arrow is
visible in addition to an icon, text or a custom child, it will also have
``.arrow-button`` style class.

Inside the toggle button content, there is an ``arrow`` node for
the indicator, which will carry one of the ``.none``, ``.up``, ``.down``,
``.left`` or ``.right`` style classes to indicate the direction that
the menu will appear in. The CSS is expected to provide a suitable
image for each of these cases using the ``-gtk-icon-source`` property.

Optionally, the ``menubutton`` node can carry the ``.circular`` style class
to request a round appearance.

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

``GtkMenuButton`` uses the :const:`~gi.repository.Gtk.AccessibleRole.BUTTON` role.



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

.. rst-class:: interim-class

.. class:: MenuButton
   :no-index:


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

      Creates a new ``GtkMenuButton`` widget with downwards-pointing
      arrow as the only child.

      You can replace the child widget with another ``GtkWidget``
      should you wish to.














Methods
-------

.. rst-class:: interim-class

.. class:: MenuButton
   :no-index:


   .. method:: get_active() -> bool

      Returns whether the menu button is active.



      .. versionadded:: 4.10








   .. method:: get_always_show_arrow() -> bool

      Gets whether to show a dropdown arrow even when using an icon or a custom
      child.



      .. versionadded:: 4.4








   .. method:: get_can_shrink() -> bool

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



      .. versionadded:: 4.12








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

      Gets the child widget of ``menu_button``.



      .. versionadded:: 4.6








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

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










   .. method:: get_has_frame() -> bool

      Returns whether the button has a frame.










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

      Gets the name of the icon shown in the button.










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

      Gets the label shown in the button










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

      Returns the ``GMenuModel`` used to generate the popup.










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

      Returns the ``GtkPopover`` that pops out of the button.

      If the button is not using a ``GtkPopover``, this function
      returns :const:`None`.










   .. method:: get_primary() -> bool

      Returns whether the menu button acts as a primary menu.



      .. versionadded:: 4.4








   .. method:: get_use_underline() -> bool

      Returns whether an embedded underline in the text indicates a
      mnemonic.










   .. method:: popdown() -> None

      Dismiss the menu.










   .. method:: popup() -> None

      Pop up the menu.










   .. method:: set_active(active: bool) -> None

      Sets whether the menu button is active.



      .. versionadded:: 4.10





      :param active: whether the menu button is active





   .. method:: set_always_show_arrow(always_show_arrow: bool) -> None

      Sets whether to show a dropdown arrow even when using an icon or a custom
      child.



      .. versionadded:: 4.4





      :param always_show_arrow: whether to show a dropdown arrow even when using an icon
         or a custom child





   .. method:: set_can_shrink(can_shrink: bool) -> None

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

      For text buttons, setting ``can_shrink`` to true will ellipsize the label.

      For icon buttons, this function has no effect.



      .. versionadded:: 4.12





      :param can_shrink: whether the button can shrink





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

      Sets the child widget of ``menu_button``.

      Setting a child resets :obj:`~gi.repository.Gtk.MenuButton.props.label` and
      :obj:`~gi.repository.Gtk.MenuButton.props.icon_name`.

      If :obj:`~gi.repository.Gtk.MenuButton.props.always_show_arrow` is set to ``TRUE`` and
      :obj:`~gi.repository.Gtk.MenuButton.props.direction` is not ``GTK_ARROW_NONE``, a dropdown arrow
      will be shown next to the child.



      .. versionadded:: 4.6





      :param child: the child widget





   .. method:: set_create_popup_func(func: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None

      Sets ``func`` to be called when a popup is about to be shown.

      ``func`` should use one of

       - :obj:`~gi.repository.Gtk.MenuButton.set_popover`
       - :obj:`~gi.repository.Gtk.MenuButton.set_menu_model`

      to set a popup for ``menu_button``.
      If ``func`` is non-:const:`None`, ``menu_button`` will always be sensitive.

      Using this function will not reset the menu widget attached to
      ``menu_button``. Instead, this can be done manually in ``func``.







      :param func: function to call when a popup is about to
         be shown, but none has been provided via other means, or :const:`None`
         to reset to default behavior.


      :param user_data: user data to pass to ``func``.





   .. method:: set_direction(direction: ~gi.repository.Gtk.ArrowType) -> None

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

      If the button is automatically populated with an arrow icon,
      its direction will be changed to match.

      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 :const:`~gi.repository.Gtk.ArrowType.NONE` for a ``direction``, the popup will behave
      as if you passed :const:`~gi.repository.Gtk.ArrowType.DOWN` (although you won’t see any arrows).







      :param direction: a ``GtkArrowType``





   .. method:: set_has_frame(has_frame: bool) -> None

      Sets the style of the button.







      :param has_frame: whether the button should have a visible frame





   .. method:: set_icon_name(icon_name: str) -> None

      Sets the name of an icon to show inside the menu button.

      Setting icon name resets :obj:`~gi.repository.Gtk.MenuButton.props.label` and
      :obj:`~gi.repository.Gtk.MenuButton.props.child`.

      If :obj:`~gi.repository.Gtk.MenuButton.props.always_show_arrow` is set to ``TRUE`` and
      :obj:`~gi.repository.Gtk.MenuButton.props.direction` is not ``GTK_ARROW_NONE``, a dropdown arrow
      will be shown next to the icon.







      :param icon_name: the icon name





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

      Sets the label to show inside the menu button.

      Setting a label resets :obj:`~gi.repository.Gtk.MenuButton.props.icon_name` and
      :obj:`~gi.repository.Gtk.MenuButton.props.child`.

      If :obj:`~gi.repository.Gtk.MenuButton.props.direction` is not ``GTK_ARROW_NONE``, a dropdown
      arrow will be shown next to the label.







      :param label: the label





   .. method:: set_menu_model(menu_model: ~gi.repository.Gio.MenuModel | None = None) -> None

      Sets the ``GMenuModel`` from which the popup will be constructed.

      If ``menu_model`` is :const:`None`, the button 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.Gtk.MenuButton.props.popover` is already set, it will be
      dissociated from the ``menu_button``, and the property is set to :const:`None`.







      :param menu_model: a ``GMenuModel``, or :const:`None` to unset and disable the
         button





   .. method:: set_popover(popover: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the ``GtkPopover`` that will be popped up when the ``menu_button`` is clicked.

      If ``popover`` is :const:`None`, the button is disabled.

      If :obj:`~gi.repository.Gtk.MenuButton.props.menu_model` is set, the menu model is dissociated
      from the ``menu_button``, and the property is set to :const:`None`.







      :param popover: a ``GtkPopover``, or :const:`None` to unset and disable the button





   .. method:: set_primary(primary: bool) -> None

      Sets whether menu button acts as a primary menu.

      Primary menus can be opened with the :kbd:`F10` key.



      .. versionadded:: 4.4





      :param primary: whether the menubutton should act as a primary menu





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

      If true, an underline in the text indicates a mnemonic.







      :param use_underline: :const:`True` if underlines in the text indicate mnemonics









Properties
----------

.. rst-class:: interim-class

.. class:: MenuButton
   :no-index:
   

   .. attribute:: props.active
      :type: bool

      Whether the menu button is active.



      .. versionadded:: 4.10





   .. attribute:: props.always_show_arrow
      :type: bool

      Whether to show a dropdown arrow even when using an icon or a custom child.



      .. versionadded:: 4.4





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

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



      .. versionadded:: 4.12





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

      The child widget.



      .. versionadded:: 4.6





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

      The ``GtkArrowType`` representing the direction in which the
      menu or popover will be popped out.







   .. attribute:: props.has_frame
      :type: bool

      Whether the button has a frame.







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

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







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

      The label for the button.







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

      The ``GMenuModel`` from which the popup will be created.

      See :obj:`~gi.repository.Gtk.MenuButton.set_menu_model` for the interaction
      with the :obj:`~gi.repository.Gtk.MenuButton.props.popover` property.







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

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







   .. attribute:: props.primary
      :type: bool

      Whether the menu button acts as a primary menu.

      Primary menus can be opened using the :kbd:`F10` key



      .. versionadded:: 4.4





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

      If set an underscore in the text indicates a mnemonic.











Signals
-------

.. rst-class:: interim-class

.. class:: MenuButton.signals
   :no-index:
   

   .. method:: activate() -> None

      Emitted to when the menu button is activated.

      The ``::activate`` signal on ``GtkMenuButton`` is an action signal and
      emitting it causes the button to pop up its menu.



      .. versionadded:: 4.4