GtkPopover

GtkPopover — Context dependent bubbles

Functions

Properties

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

Signals

void activate-default Action
void closed Run Last

Types and Values

struct GtkPopover

Object Hierarchy

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

Implemented Interfaces

GtkPopover implements AtkImplementorIface, GtkBuildable, GtkConstraintTarget 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, passed at construction time on gtk_popover_new(), or updated afterwards through gtk_popover_set_relative_to(), 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 (GtkWidget *relative_to);

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_relative_to ()

void
gtk_popover_set_relative_to (GtkPopover *popover,
                             GtkWidget *relative_to);

Sets a new widget to be attached to popover . If popover is visible, the position will be updated.

Note: the ownership of popovers is always given to their relative_to widget, so if relative_to is set to NULL on an attached popover , it will be detached from its previous widget, and consequently destroyed unless extra references are kept.

Parameters

popover

a GtkPopover

 

relative_to

a GtkWidget.

[allow-none]

gtk_popover_get_relative_to ()

GtkWidget *
gtk_popover_get_relative_to (GtkPopover *popover);

Returns the widget popover is currently attached to

Parameters

popover

a GtkPopover

 

Returns

a GtkWidget.

[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 widget popover is attached to, see gtk_popover_set_relative_to().

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.

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

Property Details

The “autohide” property

  “autohide”                 gboolean

Whether to dismiss the popover on outside clicks.

Owner: GtkPopover

Flags: Read / Write

Default value: TRUE


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


The “relative-to” property

  “relative-to”              GtkWidget *

Widget the bubble window points to.

Owner: GtkPopover

Flags: Read / Write

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