: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 ```` element, which contains one or more ```` elements. Each ```` element contains ```` and ```` elements with a mandatory name attribute. ```` elements have the same content model as ````\. Instead of ```` or ````\, you can use ```` or ``
`` elements. .. code-block:: xml :dedent:
_New Window app.new _About Sunny app.about _Quit app.quit
Attribute values can be translated using gettext, like other ``GtkBuilder`` content. ```` 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 `__ - "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 ````\. 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`\. Shortcuts and Gestures -------------------------------------------------------------------------------- ``GtkPopoverMenu`` supports the following keyboard shortcuts: - :kbd:`Space` activates the default widget. 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 type of the None singleton. .. versionadded:: 4.14 .. attribute:: props.menu_model :type: ~gi.repository.Gio.MenuModel The type of the None singleton. .. attribute:: props.visible_submenu :type: str The type of the None singleton.