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.Gtk_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, Gtk.Popover.Gtk_Popover 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 Glib.Menu_Model.Gmenu_Model, using Gtk.Popover.Gtk_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.
<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
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. Gtk.Popover_Menu.Gtk_Popover_Menu or created using Gtk.Popover.Gtk_New_From_Model.
Particular uses of GtkPopover, such as touch selection popups or magnifiers in Gtk.GEntry.Gtk_Entry or Gtk.Text_View.Gtk_Text_View get style classes like .touch-selection or .magnifier to differentiate from plain popovers.
function "+"
(Widget : access Gtk_Popover_Record'Class)
return Gtk.Buildable.Gtk_Buildable
function "-"
(Interf : Gtk.Buildable.Gtk_Buildable)
return Gtk_Popover
procedure Bind_Model
(Self : not null access Gtk_Popover_Record;
Model : access Glib.Menu_Model.Gmenu_Model_Record'Class;
Action_Namespace : UTF8_String := "")
Establishes a binding between a Gtk.Popover.Gtk_Popover and a Glib.Menu_Model.Gmenu_Model. 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 Gtk.Actionable.Gtk_Actionable 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 Gtk.Menu_Shell.Gtk_Menu_Shell outside of a Gtk.Application_Window.Gtk_Application_Window, 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 Glib.Menu_Model.Gmenu_Model. Since: gtk+ 3.12
the Glib.Menu_Model.Gmenu_Model to bind to or null to remove binding
the namespace for actions in Model
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
type Cb_Gtk_Popover_Void is not null access procedure (Self : access Gtk_Popover_Record'Class);
Constrain_To_Property : constant Gtk.Enums.Property_Gtk_Popover_Constraint;
Sets a constraint for the popover position.
function Get_Constrain_To
(Self : not null access Gtk_Popover_Record)
return Gtk.Enums.Gtk_Popover_Constraint
Returns the constraint for placing this popover. See Gtk.Popover.Set_Constrain_To. Since: gtk+ 3.20
the constraint for placing this popover.
function Get_Default_Widget
(Self : not null access Gtk_Popover_Record)
return Gtk.Widget.Gtk_Widget
Gets the widget that should be set as the default while the popover is shown. Since: gtk+ 3.18
the default widget, or null if there is none
function Get_Modal
(Self : not null access Gtk_Popover_Record) return Boolean
Returns whether the popover is modal, see gtk_popover_set_modal to see the implications of this. Since: gtk+ 3.12
TRUE if Popover is modal
function Get_Pointing_To
(Self : not null access Gtk_Popover_Record;
Rect : access Gdk.Rectangle.Gdk_Rectangle) return Boolean
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.
location to store the rectangle
True if a rectangle to point to was set.
function Get_Position
(Self : not null access Gtk_Popover_Record)
return Gtk.Enums.Gtk_Position_Type
Returns the preferred position of Popover.
The preferred position.
function Get_Relative_To
(Self : not null access Gtk_Popover_Record)
return Gtk.Widget.Gtk_Widget
Returns the widget Popover is currently attached to Since: gtk+ 3.12
a Gtk.Widget.Gtk_Widget
function Get_Transitions_Enabled
(Self : not null access Gtk_Popover_Record) return Boolean
Returns whether show/hide transitions are enabled on this popover. Since: gtk+ 3.16 Deprecated since 3.22, 1
TRUE if the show and hide transitions of the given popover are enabled, FALSE otherwise.
function Get_Type return Glib.GType
procedure Gtk_New
(Self : out Gtk_Popover;
Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class)
Creates a new popover to point to Relative_To Since: gtk+ 3.12 Initialize does nothing if the object was already created with another call to Initialize* or G_New.
Gtk.Widget.Gtk_Widget the popover is related to
procedure Gtk_New_From_Model
(Self : out Gtk_Popover;
Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class;
Model : not null access Glib.Menu_Model.Gmenu_Model_Record'Class)
Creates a Gtk.Popover.Gtk_Popover 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 Gtk.Application_Window.Gtk_Application_Window to which the popover belongs - typically by means of being attached to a widget that is contained within the Gtk_Application_Windows 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: gtk+ 3.12 Initialize_From_Model does nothing if the object was already created with another call to Initialize* or G_New.
Gtk.Widget.Gtk_Widget the popover is related to
a Glib.Menu_Model.Gmenu_Model
type Gtk_Popover is access all Gtk_Popover_Record'Class;
function Gtk_Popover_New
(Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class)
return Gtk_Popover
Creates a new popover to point to Relative_To Since: gtk+ 3.12
Gtk.Widget.Gtk_Widget the popover is related to
function Gtk_Popover_New_From_Model
(Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class;
Model : not null access Glib.Menu_Model.Gmenu_Model_Record'Class)
return Gtk_Popover
Creates a Gtk.Popover.Gtk_Popover 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 Gtk.Application_Window.Gtk_Application_Window to which the popover belongs - typically by means of being attached to a widget that is contained within the Gtk_Application_Windows 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: gtk+ 3.12
Gtk.Widget.Gtk_Widget the popover is related to
a Glib.Menu_Model.Gmenu_Model
type Gtk_Popover_Record is new Gtk_Bin_Record with null record;
package Implements_Gtk_Buildable is new Glib.Types.Implements
(Gtk.Buildable.Gtk_Buildable, Gtk_Popover_Record, Gtk_Popover);
procedure Initialize
(Self : not null access Gtk_Popover_Record'Class;
Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class)
Creates a new popover to point to Relative_To Since: gtk+ 3.12 Initialize does nothing if the object was already created with another call to Initialize* or G_New.
Gtk.Widget.Gtk_Widget the popover is related to
procedure Initialize_From_Model
(Self : not null access Gtk_Popover_Record'Class;
Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class;
Model : not null access Glib.Menu_Model.Gmenu_Model_Record'Class)
Creates a Gtk.Popover.Gtk_Popover 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 Gtk.Application_Window.Gtk_Application_Window to which the popover belongs - typically by means of being attached to a widget that is contained within the Gtk_Application_Windows 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: gtk+ 3.12 Initialize_From_Model does nothing if the object was already created with another call to Initialize* or G_New.
Gtk.Widget.Gtk_Widget the popover is related to
a Glib.Menu_Model.Gmenu_Model
Modal_Property : constant Glib.Properties.Property_Boolean;
Sets whether the popover is modal (so other elements in the window do not receive input while the popover is visible).
procedure On_Closed
(Self : not null access Gtk_Popover_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
This signal is emitted when the popover is dismissed either through API or user interaction.
procedure On_Closed
(Self : not null access Gtk_Popover_Record;
Call : Cb_Gtk_Popover_Void;
After : Boolean := False)
This signal is emitted when the popover is dismissed either through API or user interaction.
Pointing_To_Property : constant Glib.Properties.Property_Boxed;
Type: Gdk.Rectangle Marks a specific rectangle to be pointed.
procedure Popdown (Self : not null access Gtk_Popover_Record)
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: gtk+ 3.22
procedure Popup (Self : not null access Gtk_Popover_Record)
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: gtk+ 3.22
Position_Property : constant Gtk.Enums.Property_Gtk_Position_Type;
Sets the preferred position of the popover.
Relative_To_Property : constant Glib.Properties.Property_Object;
Type: Gtk.Widget.Gtk_Widget Sets the attached widget.
procedure Set_Constrain_To
(Self : not null access Gtk_Popover_Record;
Constraint : Gtk.Enums.Gtk_Popover_Constraint)
Sets a constraint for positioning this popover. Note that not all platforms support placing popovers freely, and may already impose constraints. Since: gtk+ 3.20
the new constraint
procedure Set_Default_Widget
(Self : not null access Gtk_Popover_Record;
Widget : access Gtk.Widget.Gtk_Widget_Record'Class)
Sets the widget that should be set as default widget while the popover is shown (see Gtk.Window.Set_Default). Gtk.Popover.Gtk_Popover remembers the previous default widget and reestablishes it when the popover is dismissed. Since: gtk+ 3.18
the new default widget, or null
procedure Set_Modal
(Self : not null access Gtk_Popover_Record;
Modal : Boolean)
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: gtk+ 3.12
TRUE to make popover claim all input within the toplevel
procedure Set_Pointing_To
(Self : not null access Gtk_Popover_Record;
Rect : Gdk.Rectangle.Gdk_Rectangle)
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. Since: gtk+ 3.12
rectangle to point to
procedure Set_Position
(Self : not null access Gtk_Popover_Record;
Position : Gtk.Enums.Gtk_Position_Type)
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 Gtk.Popover.Gtk_Popover may choose to appear on the opposite side Since: gtk+ 3.12
preferred popover position
procedure Set_Relative_To
(Self : not null access Gtk_Popover_Record;
Relative_To : access Gtk.Widget.Gtk_Widget_Record'Class)
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: gtk+ 3.12
a Gtk.Widget.Gtk_Widget
procedure Set_Transitions_Enabled
(Self : not null access Gtk_Popover_Record;
Transitions_Enabled : Boolean)
Sets whether show/hide transitions are enabled on this popover Since: gtk+ 3.16 Deprecated since 3.22, 1
Whether transitions are enabled
Signal_Closed : constant Glib.Signal_Name := "closed";
This signal is emitted when the popover is dismissed either through API or user interaction.
Transitions_Enabled_Property : constant Glib.Properties.Property_Boolean;
Whether show/hide transitions are enabled for this popover.