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.
CSS nodes
GtkPopover has a single css node called popover. It always gets the
.background style class and it gets the .menu style class if it is
menu-like (e.g. GtkPopoverMenu or created using gtk_popover_new_from_model().
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.
Functions
gtk_popover_new ()
GtkWidget *
gtk_popover_new (GtkWidget *relative_to);
Creates a new popover to point to relative_to
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.
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.
Since: 3.12
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().
Since: 3.22
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().
Since: 3.22
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.
Since: 3.12
gtk_popover_get_relative_to ()
GtkWidget *
gtk_popover_get_relative_to (GtkPopover *popover);
Returns the widget popover
is currently attached 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.
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
Since: 3.12
gtk_popover_get_position ()
GtkPositionType
gtk_popover_get_position (GtkPopover *popover);
Returns the preferred position of popover
.
Returns
The preferred position.
gtk_popover_set_constrain_to ()
void
gtk_popover_set_constrain_to (GtkPopover *popover,
GtkPopoverConstraint constraint);
Sets a constraint for positioning this popover.
Note that not all platforms support placing popovers freely,
and may already impose constraints.
Since: 3.20
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.
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.
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
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.
Returns
TRUE if the show and hide transitions of the given
popover are enabled, FALSE otherwise.
Since: 3.16
gtk_popover_set_default_widget ()
void
gtk_popover_set_default_widget (GtkPopover *popover,
GtkWidget *widget);
Sets the widget that should be set as default widget while
the popover is shown (see gtk_window_set_default()). GtkPopover
remembers the previous default widget and reestablishes it
when the popover is dismissed.
Since: 3.18
gtk_popover_get_default_widget ()
GtkWidget *
gtk_popover_get_default_widget (GtkPopover *popover);
Gets the widget that should be set as the default while
the popover is shown.
Returns
the default widget,
or NULL if there is none.
[nullable][transfer none]
Since: 3.18
Property Details
The “constrain-to” property
“constrain-to” GtkPopoverConstraint
Sets a constraint for the popover position.
Owner: GtkPopover
Flags: Read / Write
Default value: GTK_POPOVER_CONSTRAINT_WINDOW
Since: 3.20
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).
Owner: GtkPopover
Flags: Read / Write
Default value: TRUE
Since: 3.12
The “pointing-to” property
“pointing-to” GdkRectangle *
Marks a specific rectangle to be pointed.
Owner: GtkPopover
Flags: Read / Write
Since: 3.12
The “position” property
“position” GtkPositionType
Sets the preferred position of the popover.
Owner: GtkPopover
Flags: Read / Write
Default value: GTK_POS_TOP
Since: 3.12
The “relative-to” property
“relative-to” GtkWidget *
Sets the attached widget.
Owner: GtkPopover
Flags: Read / Write
Since: 3.12
The “transitions-enabled” property
“transitions-enabled” gboolean
Whether show/hide transitions are enabled for this popover.
Owner: GtkPopover
Flags: Read / Write
Default value: TRUE
Since: 3.16