## GtkPopover GtkPopover — Context dependent bubbles |

## Functions

GtkWidget * | gtk_popover_new ()
void | gtk_popover_popup ()
void | gtk_popover_popdown ()
void | gtk_popover_set_child ()
GtkWidget * | gtk_popover_get_child ()
void | gtk_popover_set_pointing_to ()
gboolean | gtk_popover_get_pointing_to ()
void | gtk_popover_set_position ()
GtkPositionType | gtk_popover_get_position ()
void | gtk_popover_set_autohide ()
gboolean | gtk_popover_get_autohide ()
void | gtk_popover_set_has_arrow ()
gboolean | gtk_popover_get_has_arrow ()
void | gtk_popover_set_default_widget ()

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