GTK+ 3 Reference Manual: GtkPopover

## GtkPopover GtkPopover — Context dependent bubbles |

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkPopover;
    GtkWidget *         gtk_popover_new                     (GtkWidget *relative_to);
    void                gtk_popover_set_relative_to         (GtkPopover *popover,
                                                             GtkWidget *relative_to);
    GtkWidget *         gtk_popover_get_relative_to         (GtkPopover *popover);
    void                gtk_popover_set_pointing_to         (GtkPopover *popover,
                                                             cairo_rectangle_int_t *rect);
    gboolean            gtk_popover_get_pointing_to         (GtkPopover *popover,
                                                             cairo_rectangle_int_t *rect);
    void                gtk_popover_set_position            (GtkPopover *popover,
                                                             GtkPositionType position);
    GtkPositionType     gtk_popover_get_position            (GtkPopover *popover);
    void                gtk_popover_set_modal               (GtkPopover *popover,
                                                             gboolean modal);
    gboolean            gtk_popover_get_modal               (GtkPopover *popover);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkPopover

## Implemented Interfaces

GtkPopover implements AtkImplementorIface and GtkBuildable.

## Properties

      "modal"                    gboolean              : Read / Write
      "pointing-to"              CairoRectangleInt*    : Read / Write
      "position"                 GtkPositionType       : Read / Write / Construct
      "relative-to"              GtkWidget*            : Read / Write

## 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 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 Esc key being pressed). If no such modal behavior is desired on a popover, `gtk_popover_set_modal()` may be called on it to tweak its behavior.

## Details

### struct GtkPopover

    struct GtkPopover;

### gtk_popover_new ()

    GtkWidget *         gtk_popover_new                     (GtkWidget *relative_to);

Creates a new popover to point to `relative_to`

`relative_to` : | GtkWidget the popover is related to
Returns : | a new GtkPopover

Since 3.12

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

`popover` : | a GtkPopover
`relative_to` : | a GtkWidget

Since 3.12

### gtk_popover_get_relative_to ()

    GtkWidget *         gtk_popover_get_relative_to         (GtkPopover *popover);

Returns the wigdet `popover` is currently attached to

`popover` : | a GtkPopover
Returns : | a GtkWidget. [transfer none]

Since 3.12

### gtk_popover_set_pointing_to ()

    void                gtk_popover_set_pointing_to         (GtkPopover *popover,
                                                             cairo_rectangle_int_t *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()`

`popover` : | a GtkPopover
`rect` : | rectangle to point to

Since 3.12

### gtk_popover_get_pointing_to ()

    gboolean            gtk_popover_get_pointing_to         (GtkPopover *popover,
                                                             cairo_rectangle_int_t *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.

`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

`popover` : | a GtkPopover
`position` : | preferred popover position

Since 3.12

### gtk_popover_get_position ()

    GtkPositionType     gtk_popover_get_position            (GtkPopover *popover);

Returns the preferred position of `popover`.

`popover` : | a GtkPopover
Returns : | The preferred position.

### gtk_popover_set_modal ()

    void                gtk_popover_set_modal               (GtkPopover *popover,
                                                             gboolean modal);

Sets whether `popover` is modal, a modal popover will grab all input within the toplevel and grab the keyboard focus on it when being displayed. Clicking outside the popover area or pressing Esc will dismiss the popover and ungrab input.

`popover` : | a GtkPopover
`modal` : | TRUE to make popover claim all input within the toplevel

Since 3.12

### gtk_popover_get_modal ()

    gboolean            gtk_popover_get_modal               (GtkPopover *popover);

Returns whether the popover is modal, see gtk_popover_set_modal to see the implications of this.

`popover` : | a GtkPopover
Returns : | TRUE if `popover` is modal

Since 3.12

## Property Details

### The `"modal"` property

      "modal"                    gboolean              : 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

Since 3.12

### The `"pointing-to"` property

      "pointing-to"              CairoRectangleInt*    : Read / Write

Marks a specific rectangle to be pointed.

Since 3.12

### The `"position"` property

      "position"                 GtkPositionType       : Read / Write / Construct

Sets the preferred position of the popover.

Default value: GTK_POS_TOP

Since 3.12

### The `"relative-to"` property

      "relative-to"              GtkWidget*            : Read / Write

Sets the attached widget.

Since 3.12