Gtk.Popover¶

Subclasses:: Gtk.EmojiChooser, Gtk.PopoverMenu

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Native (6)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`get_autohide` ()
	`get_cascade_popdown` ()
	`get_child` ()
	`get_has_arrow` ()
	`get_mnemonics_visible` ()
	`get_offset` ()
	`get_pointing_to` ()
	`get_position` ()
	`popdown` ()
	`popup` ()
	`present` ()
	`set_autohide` (autohide)
	`set_cascade_popdown` (cascade_popdown)
	`set_child` (child)
	`set_default_widget` (widget)
	`set_has_arrow` (has_arrow)
	`set_mnemonics_visible` (mnemonics_visible)
	`set_offset` (x_offset, y_offset)
	`set_pointing_to` (rect)
	`set_position` (position)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.ShortcutManager (2)

	`do_activate_default` ()
	`do_closed` ()

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags
`autohide`	`bool`	r/w/en
`cascade-popdown`	`bool`	r/w/en
`child`	`Gtk.Widget`	r/w/en
`default-widget`	`Gtk.Widget`	r/w/en
`has-arrow`	`bool`	r/w/en
`mnemonics-visible`	`bool`	r/w/en
`pointing-to`	`Gdk.Rectangle`	r/w
`position`	`Gtk.PositionType`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`activate-default`	Emitted whend the user activates the default widget.
`closed`	Emitted when the popover is closed.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Type	Access	Description
parent	`Gtk.Widget`	r

Class Details¶

class Gtk.Popover(**kwargs)¶

Bases:: Gtk.Widget, Gtk.Native, Gtk.ShortcutManager
Abstract:: No
Structure:: Gtk.PopoverClass

GtkPopover is a bubble-like context popup.

An example Gtk.Popover

It is primarily meant to provide context-dependent information or options. Popovers are attached to a parent widget. By default, they point to the whole widget area, although this behavior can be changed with [method`Gtk`.Popover.set_pointing_to].

The position of a popover relative to the widget it is attached to can also be changed with [method`Gtk`.Popover.set_position]

By default, GtkPopover performs a 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 Escape key being pressed). If no such modal behavior is desired on a popover, [method`Gtk`.Popover.set_autohide] may be called on it to tweak its behavior.

Gtk.Popover as menu replacement

GtkPopover is often used to replace menus. The best was to do this is to use the [class`Gtk`.PopoverMenu] subclass which supports being populated from a GMenuModel with [ctor`Gtk`.PopoverMenu.new_from_model].

``xml <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

`` popover.background[.menu] ├── arrow ╰── contents

╰── <child>

``

GtkPopover has a main node with name popover, an arrow with name arrow, and another node for the content named contents. The popover node always gets the .background style class. It also gets the .menu style class if the popover is menu-like, e.g. is a [class`Gtk`.PopoverMenu].

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.

When styling a popover directly, the popover node should usually not have any background. The visible part of the popover can have a shadow. To specify it in CSS, set the box-shadow of the contents node.

Note that, in order to accomplish appropriate arrow visuals, GtkPopover uses custom drawing for the arrow node. This makes it possible for the arrow to change its shape dynamically, but it also limits the possibilities of styling it using CSS. In particular, the arrow gets drawn over the content node’s border and shadow, so they look like one shape, which means that the border width of the content node and the arrow node should be the same. The arrow also does not support any border shape other than solid, no border-radius, only one border width (border-bottom-width is used) and no box-shadow.

classmethod new()[source]¶

Returns:: the new GtkPopover
Return type:: Gtk.Widget

Creates a new GtkPopover.

get_autohide()[source]¶

Returns:: True if self is modal
Return type:: bool

Returns whether the popover is modal.

See [method`Gtk`.Popover.set_autohide] for the implications of this.

get_cascade_popdown()[source]¶

Returns:: True if self will close after a modal child.
Return type:: bool

Returns whether the popover will close after a modal child is closed.

get_child()[source]¶

Returns:: the child widget of self
Return type:: Gtk.Widget or None

Gets the child widget of self.

get_has_arrow()[source]¶

Returns:: whether the popover has an arrow
Return type:: bool

Gets whether this popover is showing an arrow pointing at the widget that it is relative to.

get_mnemonics_visible()[source]¶

Returns:: True if mnemonics are supposed to be visible in this popover
Return type:: bool

Gets whether mnemonics are visible.

get_offset()[source]¶

Returns:

x_offset:: a location for the x_offset
y_offset:: a location for the y_offset

Return type:

(x_offset: int, y_offset: int)

Gets the offset previous set with [method`Gtk`.Popover.set_offset()].

get_pointing_to()[source]¶

Returns:

True if a rectangle to point to was set.

rect:: location to store the rectangle

Return type:

(bool, rect: Gdk.Rectangle)

Gets the rectangle that the popover points to.

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 parent widget coordinates.

get_position()[source]¶

Returns:: The preferred position.
Return type:: Gtk.PositionType

Returns the preferred position of self.

popdown()[source]¶

Pops self down.

This may have the side-effect of closing a parent popover as well. See [property`Gtk`.Popover:cascade-popdown].

popup()[source]¶: Pops self up.

present()[source]¶

Allocate a size for the GtkPopover.

This function needs to be called in size-allocate by widgets who have a GtkPopover as child. When using a layout manager, this is happening automatically.

To make a popover appear on screen, use [method`Gtk`.Popover.popup].

set_autohide(autohide)[source]¶

Parameters:: autohide (bool) – True to dismiss the popover on outside clicks

Sets whether self is modal.

A modal popover will grab the keyboard focus on it when being displayed. Focus will wrap around within the popover. Clicking outside the popover area or pressing Esc will dismiss the popover.

Called this function on an already showing popup with a new autohide value different from the current one, will cause the popup to be hidden.

set_cascade_popdown(cascade_popdown)[source]¶

Parameters:: cascade_popdown (bool) – True if the popover should follow a child closing

If cascade_popdown is True, the popover will be closed when a child modal popover is closed.

If False, self will stay visible.

set_child(child)[source]¶

Parameters:: child (Gtk.Widget or None) – the child widget

Sets the child widget of self.

set_default_widget(widget)[source]¶

Parameters:: widget (Gtk.Widget or None) – a child widget of self to set as the default, or None to unset the default widget for the popover

Sets the default widget of a GtkPopover.

The default widget is the widget that’s activated when the user presses Enter in a dialog (for example). This function sets or unsets the default widget for a GtkPopover.

set_has_arrow(has_arrow)[source]¶

Parameters:: has_arrow (bool) – True to draw an arrow

Sets whether this popover should draw an arrow pointing at the widget it is relative to.

set_mnemonics_visible(mnemonics_visible)[source]¶

Parameters:: mnemonics_visible (bool) – the new value

Sets whether mnemonics should be visible.

set_offset(x_offset, y_offset)[source]¶

Parameters:

x_offset (int) – the x offset to adjust the position by
y_offset (int) – the y offset to adjust the position by

Sets the offset to use when calculating the position of the popover.

These values are used when preparing the [struct`Gdk`.PopupLayout] for positioning the popover.

set_pointing_to(rect)[source]¶

Parameters:: rect (Gdk.Rectangle or None) – rectangle to point to

Sets the rectangle that self points to.

This is in the coordinate space of the self parent.

set_position(position)[source]¶

Parameters:: position (Gtk.PositionType) – preferred popover position

Sets the preferred position for self to appear.

If the self 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.

do_activate_default() virtual¶

do_closed() virtual¶

Signal Details¶

Gtk.Popover.signals.activate_default(popover)¶

Signal Name:: activate-default
Flags:: RUN_LAST, ACTION
Parameters:: popover (Gtk.Popover) – The object which received the signal

Emitted whend the user activates the default widget.

This is a keybinding signal.

Gtk.Popover.signals.closed(popover)¶

Signal Name:: closed
Flags:: RUN_LAST
Parameters:: popover (Gtk.Popover) – The object which received the signal

Emitted when the popover is closed.

Property Details¶

Gtk.Popover.props.autohide¶

Name:: autohide
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to dismiss the popover on outside clicks.

Gtk.Popover.props.cascade_popdown¶

Name:: cascade-popdown
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the popover pops down after a child popover.

This is used to implement the expected behavior of submenus.

Gtk.Popover.props.child¶

Name:: child
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The child widget.

Gtk.Popover.props.default_widget¶

Name:: default-widget
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The default widget inside the popover.

Gtk.Popover.props.has_arrow¶

Name:: has-arrow
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to draw an arrow.

Gtk.Popover.props.mnemonics_visible¶

Name:: mnemonics-visible
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether mnemonics are currently visible in this popover.

Gtk.Popover.props.pointing_to¶

Name:: pointing-to
Type:: Gdk.Rectangle
Default Value:: None
Flags:: READABLE, WRITABLE

Rectangle in the parent widget that the popover points to.

Gtk.Popover.props.position¶

Name:: position
Type:: Gtk.PositionType
Default Value:: Gtk.PositionType.BOTTOM
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

How to place the popover, relative to its parent.