Class gtk-popover

Package: gtk

Superclasses

gtk-bin, gtk-container, gtk-widget, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

gtk-popover-menu

Direct Slots

The position property of type gtk-position-type (Read / Write)
Sets the preferred position of the popover.
Default value: :top

The constrain-to property of type gtk-popover-constraint (Read / Write)
Sets a constraint for the popover position. Since 3.20
Default value: :window

The modal property of type :boolean (Read / Write)
Sets whether the popover is modal, so other elements in the window do not receive input while the popover is visible.
Default value: true

The pointing-to property of type gdk-rectangle (Read / Write)
Marks a specific rectangle to be pointed.

The relative-to property of type gtk-widget (Read / Write)
Sets the attached widget.

The transitions-enabled property of type :boolean (Read / Write)
Whether show/hide transitions are enabled for this popover.
Warning: The transitions-enabled property has been deprecated since version 3.22 and should not be used in newly written code. You can show or hide the popover without transitions using the gtk-widget-show and gtk-widget-hide functions while the gtk-popover-popup and gtk-popover-popdown functions will use transitions.
Default value: true

Details

A gtk-popover widget is a bubble-like context window, primarily meant to provide context-dependent information or options. Popovers are attached to a widget, passed at construction time on the gtk-popover-new function, or updated afterwards through the gtk-popover-relative-to function, by default they will point to the whole widget area, although this behavior can be changed through the gtk-popover-pointing-to function.

The position of a popover relative to the widget it is attached to can also be changed through the gtk-popover-position function.

By default, the gtk-popover widget performs a GTK grab, in order to ensure input events get redirected to it while it is shown, and also so the popover is dismissed in the expected situations, clicks outside the popover, or the Escape key being pressed. If no such modal behavior is desired on a popover, the gtk-popover-modal function may be called on it to tweak its behavior.

GtkPopover as menu replacement

A gtk-popover widget is often used to replace menus. To facilitate this, it supports being populated from a g-menu-model object, using the gtk-popover-new-from-model function. In addition to all the regular menu model features, this function supports rendering sections in the model in a more compact form, as a row of icon buttons instead of menu items.

To use this rendering, set the "display-hint" attribute of the section to "horizontal-buttons" and set the icons of your items with the "verb-icon" attribute.

Example

<section>
  <attribute name="display-hint">horizontal-buttons</attribute>
  <item>
    <attribute name="label">Cut</attribute>
    <attribute name="action">app.cut</attribute>
    <attribute name="verb-icon">edit-cut-symbolic</attribute>
  </item>
  <item>
    <attribute name="label">Copy</attribute>
    <attribute name="action">app.copy</attribute>
    <attribute name="verb-icon">edit-copy-symbolic</attribute>
  </item>
  <item>
    <attribute name="label">Paste</attribute>
    <attribute name="action">app.paste</attribute>
    <attribute name="verb-icon">edit-paste-symbolic</attribute>
  </item>
</section>

CSS nodes

The gtk-popover implementation has a single css node called popover. It always gets the .background style class and it gets the .menu style class if it is menu-like, e.g. a gtk-popover-menu widget or created using the gtk-popover-new-from-model function.

Particular uses of the gtk-popover widget, such as touch selection popups or magnifiers in gtk-entry or gtk-text-view widgets get style classes like .touch-selection or .magnifier to differentiate from plain popovers.