GtkPopover: GTK+ 3 Reference Manual

## GtkPopover GtkPopover — Context dependent bubbles |

## Functions

GtkWidget * | gtk_popover_new ()
GtkWidget * | gtk_popover_new_from_model ()
void | gtk_popover_bind_model ()
void | gtk_popover_set_relative_to ()
GtkWidget * | gtk_popover_get_relative_to ()
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_modal ()
gboolean | gtk_popover_get_modal ()
void | gtk_popover_set_transitions_enabled ()
gboolean | gtk_popover_get_transitions_enabled ()

## Properties

gboolean | modal | Read / Write
CairoRectangleInt * | pointing-to | Read / Write
GtkPositionType | position | Read / Write / Construct
GtkWidget * | relative-to | Read / Write
gboolean | transitions-enabled | Read / Write

## Signals

void | closed | Run Last

## Types and Values

struct | GtkPopover

## Object Hierarchy

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

## Implemented Interfaces

GtkPopover implements AtkImplementorIface and GtkBuildable.

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

#### GtkPopover as menu replacement

GtkPopover is often used to replace menus. To facilitate this, it supports being populated from a GMenuModel, using `gtk_popover_new_from_model()`. In addition to all the regular menu model features, this function supports rendering sections in the model in a more compact form, as a row of icon buttons instead of menu items.

To use this rendering, set the ”display-hint” attribute of the section to ”horizontal-buttons” and set the icons of your items with the ”verb-icon” attribute.

    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>

## Functions

### gtk_popover_new ()

    GtkWidget *
    gtk_popover_new (GtkWidget *relative_to);

Creates a new popover to point to `relative_to`

#### Parameters

relative_to | GtkWidget the popover is related to. | [allow-none]

#### Returns

a new GtkPopover

Since: 3.12

### gtk_popover_new_from_model ()

    GtkWidget *
    gtk_popover_new_from_model (GtkWidget *relative_to,
                                GMenuModel *model);

Creates a GtkPopover and populates it according to `model` . The popover is pointed to the `relative_to` widget.

The created buttons are connected to actions found in the GtkApplicationWindow to which the popover belongs - typically by means of being attached to a widget that is contained within the GtkApplicationWindows widget hierarchy.

Actions can also be added using `gtk_widget_insert_action_group()` on the menus attach widget or on any of its parent widgets.

#### Parameters

relative_to | GtkWidget the popover is related to. | [allow-none]
model | a GMenuModel |

#### Returns

the new GtkPopover

Since: 3.12

### gtk_popover_bind_model ()

    void
    gtk_popover_bind_model (GtkPopover *popover,
                            GMenuModel *model,
                            const gchar *action_namespace);

Establishes a binding between a GtkPopover and a GMenuModel.

The contents of `popover` are removed and then refilled with menu items according to `model` . When `model` changes, `popover` is updated. Calling this function twice on `popover` with different `model` will cause the first binding to be replaced with a binding to the new model. If `model` is `NULL` then any previous binding is undone and all children are removed.

If `action_namespace` is non-`NULL` then the effect is as if all actions mentioned in the `model` have their names prefixed with the namespace, plus a dot. For example, if the action “quit” is mentioned and `action_namespace` is “app” then the effective action name is “app.quit”.

This function uses GtkActionable to define the action name and target values on the created menu items. If you want to use an action group other than “app” and “win”, or if you want to use a GtkMenuShell outside of a GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using `gtk_widget_insert_action_group()`. As an example, if you created a group with a “quit” action and inserted it with the name “mygroup” then you would use the action name “mygroup.quit” in your GMenuModel.

#### Parameters

popover | a GtkPopover |
model | the GMenuModel to bind to or `NULL` to remove binding. | [allow-none]
action_namespace | the namespace for actions in `model` . | [allow-none]

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.

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]

Since: 3.12

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

Since: 3.12

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

Since: 3.12

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

Since: 3.12

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

#### Parameters

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.

#### Parameters

popover | a GtkPopover |

#### Returns

TRUE if `popover` is modal

Since: 3.12

### gtk_popover_set_transitions_enabled ()

    void
    gtk_popover_set_transitions_enabled (GtkPopover *popover,
                                         gboolean transitions_enabled);

Sets whether show/hide transitions are enabled on this popover

#### Parameters

popover | a GtkPopover |
transitions_enabled | Whether transitions are enabled |

Since: 3.16

### gtk_popover_get_transitions_enabled ()

    gboolean
    gtk_popover_get_transitions_enabled (GtkPopover *popover);

Returns whether show/hide transitions are enabled on this popover.

#### Parameters

popover | a GtkPopover |

#### Returns

TRUE if the show and hide transitions of the given popover are enabled, FALSE otherwise.

Since: 3.16

## Types and Values

### struct GtkPopover

    struct GtkPopover;

## Property Details

### The `“modal”` property

      “modal”                    gboolean

Sets whether the popover is modal (so other elements in the window do not receive input while the popover is visible).

Flags: Read / Write

Default value: TRUE

Since: 3.12

### The `“pointing-to”` property

      “pointing-to”              CairoRectangleInt *

Marks a specific rectangle to be pointed.

Flags: Read / Write

Since: 3.12

### The `“position”` property

      “position”                 GtkPositionType

Sets the preferred position of the popover.

Flags: Read / Write / Construct

Default value: GTK_POS_TOP

Since: 3.12

### The `“relative-to”` property

      “relative-to”              GtkWidget *

Sets the attached widget.

Flags: Read / Write

Since: 3.12

### The `“transitions-enabled”` property

      “transitions-enabled”      gboolean

Whether show/hide transitions are enabled for this popover.

Flags: Read / Write

Default value: TRUE

Since: 3.16

## Signal Details

### The `“closed”` signal

    void
    user_function (GtkPopover *popover,
                   gpointer    user_data)

Flags: Run Last