GtkPopover

GtkPopover — Context dependent bubbles

Properties

gboolean autohide Read / Write
GtkWidget * child Read / Write
GtkWidget * default-widget Read / Write
gboolean has-arrow Read / Write
gboolean mnemonics-visible Read / Write
GdkRectangle * pointing-to Read / Write
GtkPositionType position Read / Write

Signals

void activate-default Action
void closed Run Last

Types and Values

struct GtkPopover

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkPopover
                ├── GtkEmojiChooser
                ╰── GtkPopoverMenu

Implemented Interfaces

GtkPopover implements AtkImplementorIface, GtkBuildable, GtkConstraintTarget, GtkShortcutManager and GtkNative.

Includes

#include <gtk/gtk.h>

Description

GtkPopover is a bubble-like context window, primarily meant to provide context-dependent information or options. Popovers are attached to a widget, set with gtk_widget_set_parent(). By default they will point to the whole widget area, although this behavior can be changed through gtk_popover_set_pointing_to().

The position of a popover relative to the widget it is attached to can also be changed through gtk_popover_set_position().

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, gtk_popover_set_autohide() may be called on it to tweak its behavior.

GtkPopover as menu replacement

GtkPopover is often used to replace menus. The best was to do this is to use the GtkPopoverMenu subclass which supports being populated from a GMenuModel with gtk_popover_menu_new_from_model().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<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

1
2
3
4
popover[.menu]
├── arrow
╰── contents.background
    ╰── <child>

The contents child node always gets the .background style class and the popover itself gets the .menu style class if the popover is menu-like (i.e. GtkPopoverMenu).

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.

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

Functions

gtk_popover_new ()

GtkWidget *
gtk_popover_new (void);

Creates a new popover.

Returns

the new popover


gtk_popover_popup ()

void
gtk_popover_popup (GtkPopover *popover);

Pops popover up. This is different than a gtk_widget_show() call in that it shows the popover with a transition. If you want to show the popover without a transition, use gtk_widget_show().

Parameters

popover

a GtkPopover

 

gtk_popover_popdown ()

void
gtk_popover_popdown (GtkPopover *popover);

Pops popover down.This is different than a gtk_widget_hide() call in that it shows the popover with a transition. If you want to hide the popover without a transition, use gtk_widget_hide().

Parameters

popover

a GtkPopover

 

gtk_popover_set_child ()

void
gtk_popover_set_child (GtkPopover *popover,
                       GtkWidget *child);

Sets the child widget of popover .

Parameters

popover

a GtkPopover

 

child

the child widget.

[allow-none]

gtk_popover_get_child ()

GtkWidget *
gtk_popover_get_child (GtkPopover *popover);

Gets the child widget of popover .

Parameters

popover

a GtkPopover

 

Returns

the child widget of popover .

[nullable][transfer none]


gtk_popover_set_pointing_to ()

void
gtk_popover_set_pointing_to (GtkPopover *popover,
                             const GdkRectangle *rect);

Sets the rectangle that popover will point to, in the coordinate space of the popover parent.

Parameters

popover

a GtkPopover

 

rect

rectangle to point to

 

gtk_popover_get_pointing_to ()

gboolean
gtk_popover_get_pointing_to (GtkPopover *popover,
                             GdkRectangle *rect);

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 attached widget coordinates.

Parameters

popover

a GtkPopover

 

rect

location to store the rectangle.

[out]

Returns

TRUE if a rectangle to point to was set.


gtk_popover_set_position ()

void
gtk_popover_set_position (GtkPopover *popover,
                          GtkPositionType position);

Sets the preferred position for popover to appear. If the 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

popover

a GtkPopover

 

position

preferred popover position

 

gtk_popover_get_position ()

GtkPositionType
gtk_popover_get_position (GtkPopover *popover);

Returns the preferred position of popover .

Parameters

popover

a GtkPopover

 

Returns

The preferred position.


gtk_popover_set_autohide ()

void
gtk_popover_set_autohide (GtkPopover *popover,
                          gboolean autohide);

Sets whether popover is modal.

A modal popover will grab the keyboard focus on it when being displayed. 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

popover

a GtkPopover

 

autohide

TRUE to dismiss the popover on outside clicks

 

gtk_popover_get_autohide ()

gboolean
gtk_popover_get_autohide (GtkPopover *popover);

Returns whether the popover is modal.

See gtk_popover_set_autohide() for the implications of this.

Parameters

popover

a GtkPopover

 

Returns

TRUE if popover is modal


gtk_popover_set_has_arrow ()

void
gtk_popover_set_has_arrow (GtkPopover *popover,
                           gboolean has_arrow);

Sets whether this popover should draw an arrow pointing at the widget it is relative to.

Parameters

popover

a GtkPopover

 

has_arrow

TRUE to draw an arrow

 

gtk_popover_get_has_arrow ()

gboolean
gtk_popover_get_has_arrow (GtkPopover *popover);

Gets whether this popover is showing an arrow pointing at the widget that it is relative to.

Parameters

popover

a GtkPopover

 

Returns

whether the popover has an arrow


gtk_popover_set_default_widget ()

void
gtk_popover_set_default_widget (GtkPopover *popover,
                                GtkWidget *widget);

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

popover

a GtkPopover

 

widget

a child widget of popover to set as the default, or NULL to unset the default widget for the popover.

[allow-none]

Types and Values

struct GtkPopover

struct GtkPopover;

Property Details

The “autohide” property

  “autohide”                 gboolean

Whether to dismiss the popover on outside clicks.

Owner: GtkPopover

Flags: Read / Write

Default value: TRUE


The “child” property

  “child”                    GtkWidget *

The child widget.

Owner: GtkPopover

Flags: Read / Write


The “default-widget” property

  “default-widget”           GtkWidget *

The default widget.

Owner: GtkPopover

Flags: Read / Write


The “has-arrow” property

  “has-arrow”                gboolean

Whether to draw an arrow.

Owner: GtkPopover

Flags: Read / Write

Default value: TRUE


The “mnemonics-visible” property

  “mnemonics-visible”        gboolean

Whether mnemonics are currently visible in this popover.

Owner: GtkPopover

Flags: Read / Write

Default value: FALSE


The “pointing-to” property

  “pointing-to”              GdkRectangle *

Rectangle the bubble window points to.

Owner: GtkPopover

Flags: Read / Write


The “position” property

  “position”                 GtkPositionType

Position to place the bubble window.

Owner: GtkPopover

Flags: Read / Write

Default value: GTK_POS_BOTTOM

Signal Details

The “activate-default” signal

void
user_function (GtkPopover *popover,
               gpointer    user_data)

Flags: Action


The “closed” signal

void
user_function (GtkPopover *popover,
               gpointer    user_data)

Flags: Run Last