Class Popover

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.Popover
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Native, ShortcutManager, Proxy
Direct Known Subclasses:
EmojiChooser, PopoverMenu
@Generated("org.javagi.JavaGI") public class Popover extends Widget implements Accessible, Buildable, ConstraintTarget, Native, ShortcutManager

Presents a bubble-like popup.

An example GtkPopover

It is primarily meant to provide context-dependent information or options. Popovers are attached to a parent widget. The parent widget must support popover children, as MenuButton and PopoverMenuBar do. If you want to make a custom widget that has an attached popover, you need to call present() in your Widget.sizeAllocate(Allocation, int) vfunc, in order to update the positioning of the popover.

The position of a popover relative to the widget it is attached to can also be changed with setPosition(PositionType). By default, it points to the whole widget area, but it can be made to point to a specific area using setPointingTo(Rectangle).

By default, GtkPopover performs a 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, setAutohide(boolean) may be called on it to tweak its behavior.

GtkPopover as menu replacement

GtkPopover is often used to replace menus. The best way to do this is to use the PopoverMenu subclass which supports being populated from a GMenuModel with PopoverMenu.fromModel(MenuModel).

<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>

Shortcuts and Gestures

GtkPopover supports the following keyboard shortcuts:

  • Escape closes the popover.
  • Alt makes the mnemonics visible.

The following signals have default keybindings:

  • Gtk.Popover::activate-default

CSS nodes

popover.background[.menu]
├── arrow
╰── contents
    ╰── <child>

GtkPopover has a main node with name popover, an arrow with name arrow, and another node for the content named contents. The popover node always gets the .background style class. It also gets the .menu style class if the popover is menu-like, e.g. is a PopoverMenu.

Particular uses of GtkPopover, such as touch selection popups or magnifiers in GtkEntry or GtkTextView get style classes like .touch-selection or .magnifier to differentiate from plain popovers.

When styling a popover directly, the popover node should usually not have any background. The visible part of the popover can have a shadow. To specify it in CSS, set the box-shadow of the contents node.

Note that, in order to accomplish appropriate arrow visuals, GtkPopover uses custom drawing for the arrow node. This makes it possible for the arrow to change its shape dynamically, but it also limits the possibilities of styling it using CSS. In particular, the arrow gets drawn over the content node's border and shadow, so they look like one shape, which means that the border width of the content node and the arrow node should be the same. The arrow also does not support any border shape other than solid, no border-radius, only one border width (border-bottom-width is used) and no box-shadow.

  • Constructor Details

    • Popover

      public Popover(MemorySegment address)
      Create a Popover instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Popover

      public Popover()
      Create a new Popover.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Popover class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Popover asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • getAutohide

      public boolean getAutohide()

      Returns whether the popover is modal.

      See setAutohide(boolean) for the implications of this.

      Returns:
      true if this Popover is modal

    • getCascadePopdown

      public boolean getCascadePopdown()
      Returns whether the popover will close after a modal child is closed.
      Returns:
      true if this Popover will close after a modal child.

    • getChild

      public @Nullable Widget getChild()
      Gets the child widget of popover.
      Returns:
      the child widget of this Popover

    • getHasArrow

      public boolean getHasArrow()
      Gets whether this popover is showing an arrow pointing at the widget that it is relative to.
      Returns:
      whether the popover has an arrow

    • getMnemonicsVisible

      public boolean getMnemonicsVisible()
      Gets whether mnemonics are visible.
      Returns:
      true if mnemonics are supposed to be visible in this popover

    • getOffset

      public void getOffset(@Nullable Out<Integer> xOffset, @Nullable Out<Integer> yOffset)
      Gets the offset previous set with setOffset(int, int).
      Parameters:
      xOffset - a location for the x_offset
      yOffset - a location for the y_offset

    • getPointingTo

      public boolean getPointingTo(Rectangle rect)

      Gets the rectangle that the popover points to.

      If a rectangle to point to has been set, this function will return true and fill in rect with such rectangle, otherwise it will return false and fill in rect with the parent widget coordinates.

      Parameters:
      rect - location to store the rectangle
      Returns:
      true if a rectangle to point to was set.

    • getPosition

      public PositionType getPosition()
      Returns the preferred position of popover.
      Returns:
      The preferred position.

    • popdown

      public void popdown()

      Pops this Popover down.

      This may have the side-effect of closing a parent popover as well. See Gtk.Popover:cascade-popdown.

    • popup

      public void popup()
      Pops this Popover up.

    • present

      public void present()

      Allocate a size for the GtkPopover.

      This function needs to be called in size-allocate by widgets who have a GtkPopover as child. When using a layout manager, this is happening automatically.

      To make a popover appear on screen, use popup().

    • setAutohide

      public void setAutohide(boolean autohide)

      Sets whether this Popover is modal.

      A modal popover will grab the keyboard focus on it when being displayed. Focus will wrap around within the popover. Clicking outside the popover area or pressing Esc will dismiss the popover.

      Called this function on an already showing popup with a new autohide value different from the current one, will cause the popup to be hidden.

      Parameters:
      autohide - true to dismiss the popover on outside clicks

    • setCascadePopdown

      public void setCascadePopdown(boolean cascadePopdown)

      If cascadePopdown is true, the popover will be closed when a child modal popover is closed.

      If false, this Popover will stay visible.

      Parameters:
      cascadePopdown - true if the popover should follow a child closing

    • setChild

      public void setChild(@Nullable Widget child)
      Sets the child widget of popover.
      Parameters:
      child - the child widget

    • setDefaultWidget

      public void setDefaultWidget(@Nullable Widget widget)

      Sets the default widget of a GtkPopover.

      The default widget is the widget that’s activated when the user presses Enter in a dialog (for example). This function sets or unsets the default widget for a GtkPopover.

      Parameters:
      widget - a child widget of this Popover to set as the default, or null to unset the default widget for the popover

    • setHasArrow

      public void setHasArrow(boolean hasArrow)
      Sets whether this popover should draw an arrow pointing at the widget it is relative to.
      Parameters:
      hasArrow - true to draw an arrow

    • setMnemonicsVisible

      public void setMnemonicsVisible(boolean mnemonicsVisible)
      Sets whether mnemonics should be visible.
      Parameters:
      mnemonicsVisible - the new value

    • setOffset

      public void setOffset(int xOffset, int yOffset)

      Sets the offset to use when calculating the position of the popover.

      These values are used when preparing the Gdk.PopupLayout for positioning the popover.

      Parameters:
      xOffset - the x offset to adjust the position by
      yOffset - the y offset to adjust the position by

    • setPointingTo

      public void setPointingTo(@Nullable Rectangle rect)

      Sets the rectangle that this Popover points to.

      This is in the coordinate space of the this Popover parent.

      Parameters:
      rect - rectangle to point to

    • setPosition

      public void setPosition(PositionType position)

      Sets the preferred position for this Popover to appear.

      If the this Popover is currently visible, it will be immediately updated.

      This preference will be respected where possible, although on lack of space (eg. if close to the window edges), the GtkPopover may choose to appear on the opposite side.

      Parameters:
      position - preferred popover position

    • activateDefault

      public void activateDefault()
      Description copied from class: Widget

      Activates the default.activate action for the widget.

      The action is looked up in the same was as for Widget.activateAction.

      Overrides:
      activateDefault in class Widget

    • closed

      protected void closed()

    • onActivateDefault

      public SignalConnection<Popover.ActivateDefaultCallback> onActivateDefault(Popover.ActivateDefaultCallback handler)

      Emitted whend the user activates the default widget.

      This is a keybinding signal.

      The default binding for this signal is Enter.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitActivateDefault

      public void emitActivateDefault()
      Emits the "activate-default" signal. See onActivateDefault(Popover.ActivateDefaultCallback).

    • onClosed

      public SignalConnection<Popover.ClosedCallback> onClosed(Popover.ClosedCallback handler)
      Emitted when the popover is closed.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitClosed

      public void emitClosed()
      Emits the "closed" signal. See onClosed(Popover.ClosedCallback).

    • builder

      public static Popover.Builder<? extends Popover.Builder> builder()
      A Popover.Builder object constructs a Popover with the specified properties. Use the various set...() methods to set properties, and finish construction with Popover.Builder.build().
      Returns:
      the builder object