CtkPopover as menu replacement

CtkPopover is often used to replace menus. To facilitate this, it supports being populated from a GMenuModel, using ctk_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>

CSS nodes

CtkPopover 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. CtkPopoverMenu or created using ctk_popover_new_from_model().

Particular uses of CtkPopover, such as touch selection popups or magnifiers in CtkEntry or CtkTextView get style classes like .touch-selection or .magnifier to differentiate from plain popovers.

ctk_popover_new ()

CtkWidget *
ctk_popover_new (CtkWidget *relative_to);

Creates a new popover to point to relative_to

Since: 3.12

ctk_popover_new_from_model ()

CtkWidget *
ctk_popover_new_from_model (CtkWidget *relative_to,
                            GMenuModel *model);

Creates a CtkPopover 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 CtkApplicationWindow to which the popover belongs - typically by means of being attached to a widget that is contained within the CtkApplicationWindows widget hierarchy.

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

Since: 3.12

ctk_popover_bind_model ()

void
ctk_popover_bind_model (CtkPopover *popover,
                        GMenuModel *model,
                        const gchar *action_namespace);

Establishes a binding between a CtkPopover 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 CtkActionable 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 CtkMenuShell outside of a CtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using ctk_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

ctk_popover_popup ()

void
ctk_popover_popup (CtkPopover *popover);

Pops popover up. This is different than a ctk_widget_show() call in that it shows the popover with a transition. If you want to show the popover without a transition, use ctk_widget_show().

Since: 3.22

ctk_popover_popdown ()

void
ctk_popover_popdown (CtkPopover *popover);

Pops popover down.This is different than a ctk_widget_hide() call in that it shows the popover with a transition. If you want to hide the popover without a transition, use ctk_widget_hide().

Since: 3.22

ctk_popover_set_relative_to ()

void
ctk_popover_set_relative_to (CtkPopover *popover,
                             CtkWidget *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

ctk_popover_get_relative_to ()

CtkWidget *
ctk_popover_get_relative_to (CtkPopover *popover);

Returns the widget popover is currently attached to

Since: 3.12

ctk_popover_set_pointing_to ()

void
ctk_popover_set_pointing_to (CtkPopover *popover,
                             const CdkRectangle *rect);

Sets the rectangle that popover will point to, in the coordinate space of the widget popover is attached to, see ctk_popover_set_relative_to().

Since: 3.12

ctk_popover_get_pointing_to ()

gboolean
ctk_popover_get_pointing_to (CtkPopover *popover,
                             CdkRectangle *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.

ctk_popover_set_position ()

void
ctk_popover_set_position (CtkPopover *popover,
                          CtkPositionType 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 CtkPopover may choose to appear on the opposite side

Since: 3.12

ctk_popover_get_position ()

CtkPositionType
ctk_popover_get_position (CtkPopover *popover);

Returns the preferred position of popover .

ctk_popover_set_constrain_to ()

void
ctk_popover_set_constrain_to (CtkPopover *popover,
                              CtkPopoverConstraint 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

ctk_popover_get_constrain_to ()

CtkPopoverConstraint
ctk_popover_get_constrain_to (CtkPopover *popover);

Returns the constraint for placing this popover. See ctk_popover_set_constrain_to().

Since: 3.20

ctk_popover_set_modal ()

void
ctk_popover_set_modal (CtkPopover *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

ctk_popover_get_modal ()

gboolean
ctk_popover_get_modal (CtkPopover *popover);

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

Since: 3.12

ctk_popover_set_transitions_enabled ()

void
ctk_popover_set_transitions_enabled (CtkPopover *popover,
                                     gboolean transitions_enabled);

Sets whether show/hide transitions are enabled on this popover

Since: 3.16

ctk_popover_get_transitions_enabled ()

gboolean
ctk_popover_get_transitions_enabled (CtkPopover *popover);

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

Since: 3.16

ctk_popover_set_default_widget ()

void
ctk_popover_set_default_widget (CtkPopover *popover,
                                CtkWidget *widget);

Sets the widget that should be set as default widget while the popover is shown (see ctk_window_set_default()). CtkPopover remembers the previous default widget and reestablishes it when the popover is dismissed.

Since: 3.18

ctk_popover_get_default_widget ()

CtkWidget *
ctk_popover_get_default_widget (CtkPopover *popover);

Gets the widget that should be set as the default while the popover is shown.

Since: 3.18

struct CtkPopover

struct CtkPopover;

enum CtkPopoverConstraint

Describes constraints to positioning of popovers. More values may be added to this enumeration in the future.

Since: 3.20

The “constrain-to” property

  “constrain-to”             CtkPopoverConstraint

Sets a constraint for the popover position.

Owner: CtkPopover

Flags: Read / Write

Default value: CTK_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: CtkPopover

Flags: Read / Write

Default value: TRUE

Since: 3.12

The “pointing-to” property

  “pointing-to”              CdkRectangle *

Marks a specific rectangle to be pointed.

Owner: CtkPopover

Flags: Read / Write

Since: 3.12

The “position” property

  “position”                 CtkPositionType

Sets the preferred position of the popover.

Owner: CtkPopover

Flags: Read / Write

Default value: CTK_POS_TOP

Since: 3.12

The “relative-to” property

  “relative-to”              CtkWidget *

Sets the attached widget.

Owner: CtkPopover

Flags: Read / Write

Since: 3.12

The “transitions-enabled” property

  “transitions-enabled”      gboolean

Whether show/hide transitions are enabled for this popover.

Owner: CtkPopover

Flags: Read / Write

Default value: TRUE

Since: 3.16

The “closed” signal

void
user_function (CtkPopover *ctkpopover,
               gpointer    user_data)

This signal is emitted when the popover is dismissed either through API or user interaction.

Flags: Run Last

Since: 3.12