:right-sidebar: True

PopoverMenu
===================================================================

.. currentmodule:: gi.repository.Gtk





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


Superclasses: :class:`~gi.repository.Gtk.Popover`, :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`, :class:`~gi.repository.Gtk.Native`, :class:`~gi.repository.Gtk.ShortcutManager`



``GtkPopoverMenu`` is a subclass of ``GtkPopover`` that implements menu
behavior.


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


``GtkPopoverMenu`` treats its children like menus and allows switching
between them. It can open submenus as traditional, nested submenus,
or in a more touch-friendly sliding fashion.
The property :obj:`~gi.repository.Gtk.PopoverMenu.props.flags` controls this appearance.

``GtkPopoverMenu`` is meant to be used primarily with menu models,
using :obj:`~gi.repository.Gtk.PopoverMenu.new_from_model`. If you need to put
other widgets such as a ``GtkSpinButton`` or a ``GtkSwitch`` into a popover,
you can use :obj:`~gi.repository.Gtk.PopoverMenu.add_child`.

For more dialog-like behavior, use a plain ``GtkPopover``.

Menu models
-----------

The XML format understood by ``GtkBuilder`` for ``GMenuModel`` consists
of a toplevel ``<menu>`` element, which contains one or more ``<item>``
elements. Each ``<item>`` element contains ``<attribute>`` and ``<link>``
elements with a mandatory name attribute. ``<link>`` elements have the
same content model as ``<menu>``. Instead of `<link name="submenu">`
or `<link name="section">`, you can use ``<submenu>`` or ``<section>``
elements.


.. code-block::
   :dedent:

   <menu id='app-menu'>
     <section>
       <item>
         <attribute name='label' translatable='yes'>_New Window</attribute>
         <attribute name='action'>app.new</attribute>
       </item>
       <item>
         <attribute name='label' translatable='yes'>_About Sunny</attribute>
         <attribute name='action'>app.about</attribute>
       </item>
       <item>
         <attribute name='label' translatable='yes'>_Quit</attribute>
         <attribute name='action'>app.quit</attribute>
       </item>
     </section>
   </menu>


Attribute values can be translated using gettext, like other ``GtkBuilder``
content. ``<attribute>`` elements can be marked for translation with a
``translatable="yes"`` attribute. It is also possible to specify message
context and translator comments, using the context and comments attributes.
To make use of this, the ``GtkBuilder`` must have been given the gettext
domain to use.

The following attributes are used when constructing menu items:


- "label": a user-visible string to display
- "use-markup": whether the text in the menu item includes `Pango markup <https://docs.gtk.org/Pango/pango_markup.html>`_
- "action": the prefixed name of the action to trigger
- "target": the parameter to use when activating the action
- "icon" and "verb-icon": names of icons that may be displayed
- "submenu-action": name of an action that may be used to track
     whether a submenu is open
- "hidden-when": a string used to determine when the item will be hidden.
     Possible values include "action-disabled", "action-missing", "macos-menubar".
     This is mainly useful for exported menus, see :obj:`~gi.repository.Gtk.Application.set_menubar`.
- "custom": a string used to match against the ID of a custom child added with
     :obj:`~gi.repository.Gtk.PopoverMenu.add_child`, :obj:`~gi.repository.Gtk.PopoverMenuBar.add_child`,
     or in the ui file with `<child type="ID">`.

The following attributes are used when constructing sections:


- "label": a user-visible string to use as section heading
- "display-hint": a string used to determine special formatting for the section.
    Possible values include "horizontal-buttons", "circular-buttons" and
    "inline-buttons". They all indicate that section should be
    displayed as a horizontal row of buttons.
- "text-direction": a string used to determine the ``GtkTextDirection`` to use
    when "display-hint" is set to "horizontal-buttons". Possible values
    include "rtl", "ltr", and "none".

The following attributes are used when constructing submenus:


- "label": a user-visible string to display
- "icon": icon name to display

Menu items will also show accelerators, which are usually associated
with actions via :obj:`~gi.repository.Gtk.Application.set_accels_for_action`,
:obj:`~gi.repository.WidgetClass.add_binding_action` or
:obj:`~gi.repository.Gtk.ShortcutController.add_shortcut`.

CSS Nodes
---------

``GtkPopoverMenu`` is just a subclass of ``GtkPopover`` that adds custom content
to it, therefore it has the same CSS nodes. It is one of the cases that add
a ``.menu`` style class to the main ``popover`` node.

Menu items have nodes with name ``button`` and class ``.model``. If a section
display-hint is set, the section gets a node ``box`` with class ``horizontal``
plus a class with the same text as the display hint. Note that said box may
not be the direct ancestor of the item ``button``'s. Thus, for example, to style
items in an ``inline-buttons`` section, select `.inline-buttons button.model`.
Other things that may be of interest to style in menus include ``label`` nodes.

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

``GtkPopoverMenu`` uses the :const:`~gi.repository.Gtk.AccessibleRole.MENU` role, and its
items use the :const:`~gi.repository.Gtk.AccessibleRole.MENU_ITEM`,
:const:`~gi.repository.Gtk.AccessibleRole.MENU_ITEM_CHECKBOX` or
:const:`~gi.repository.Gtk.AccessibleRole.MENU_ITEM_RADIO` roles, depending on the
action they are connected to.



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

.. rst-class:: interim-class

.. class:: PopoverMenu
   :no-index:


   .. classmethod:: new_from_model(model: ~gi.repository.Gio.MenuModel | None = None) -> ~gi.repository.Gtk.Widget

      Creates a ``GtkPopoverMenu`` and populates it according to ``model``.

      The created buttons are connected to actions found in the
      ``GtkApplicationWindow`` to which the popover belongs - typically
      by means of being attached to a widget that is contained within
      the ``GtkApplicationWindow``'s widget hierarchy.

      Actions can also be added using :obj:`~gi.repository.Gtk.Widget.insert_action_group`
      on the menus attach widget or on any of its parent widgets.

      This function creates menus with sliding submenus.
      See :obj:`~gi.repository.Gtk.PopoverMenu.new_from_model_full` for a way
      to control this.







      :param model: a ``GMenuModel``





   .. classmethod:: new_from_model_full(model: ~gi.repository.Gio.MenuModel, flags: ~gi.repository.Gtk.PopoverMenuFlags) -> ~gi.repository.Gtk.Widget

      Creates a ``GtkPopoverMenu`` and populates it according to ``model``.

      The created buttons are connected to actions found in the
      action groups that are accessible from the parent widget.
      This includes the ``GtkApplicationWindow`` to which the popover
      belongs. Actions can also be added using :obj:`~gi.repository.Gtk.Widget.insert_action_group`
      on the parent widget or on any of its parent widgets.







      :param model: a ``GMenuModel``


      :param flags: flags that affect how the menu is created









Methods
-------

.. rst-class:: interim-class

.. class:: PopoverMenu
   :no-index:


   .. method:: add_child(child: ~gi.repository.Gtk.Widget, id: str) -> bool

      Adds a custom widget to a generated menu.

      For this to work, the menu model of ``popover`` must have
      an item with a ``custom`` attribute that matches ``id``.







      :param child: the ``GtkWidget`` to add


      :param id: the ID to insert ``child`` at





   .. method:: get_flags() -> ~gi.repository.Gtk.PopoverMenuFlags

      Returns the flags that ``popover`` uses to create/display a menu from its model.



      .. versionadded:: 4.14








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

      Returns the menu model used to populate the popover.










   .. method:: remove_child(child: ~gi.repository.Gtk.Widget) -> bool

      Removes a widget that has previously been added with
      :obj:`~gi.repository.Gtk.PopoverMenu.add_child()`







      :param child: the ``GtkWidget`` to remove





   .. method:: set_flags(flags: ~gi.repository.Gtk.PopoverMenuFlags) -> None

      Sets the flags that ``popover`` uses to create/display a menu from its model.

      If a model is set and the flags change, contents are rebuilt, so if setting
      properties individually, set flags before model to avoid a redundant rebuild.



      .. versionadded:: 4.14





      :param flags: a set of ``GtkPopoverMenuFlags``





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

      Sets a new menu model on ``popover``.

      The existing contents of ``popover`` are removed, and
      the ``popover`` is populated with new contents according
      to ``model``.







      :param model: a ``GMenuModel``









Properties
----------

.. rst-class:: interim-class

.. class:: PopoverMenu
   :no-index:
   

   .. attribute:: props.flags
      :type: ~gi.repository.Gtk.PopoverMenuFlags

      The flags that ``popover`` uses to create/display a menu from its model.

      If a model is set and the flags change, contents are rebuilt, so if setting
      properties individually, set flags before model to avoid a redundant rebuild.



      .. versionadded:: 4.14





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

      The model from which the menu is made.







   .. attribute:: props.visible_submenu
      :type: str

      The name of the visible submenu.