Gtk.Popover

Gtk.Popover — Context dependent bubbles

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.Popover
                        ╰── Gtk.PopoverMenu

Functions:

Signals:

  • “closed” (popover, user_data)

Description:

Gtk.Popover 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, 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.

Gtk.Popover as menu replacement

Gtk.Popover is often used to replace menus. To facilitate this, it supports being populated from a Gio.MenuModel, 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.

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

Function Details:

new()

new (relative_to:Gtk.Widget=None) -> Gtk.Widget

Creates a new popover to point to relative_to

  • Returns: a new Gtk.Popover

  • Since: 3.12

new_from_model()

new_from_model (relative_to:Gtk.Widget=None, model:Gio.MenuModel) -> Gtk.Widget

Creates a Gtk.Popover and populates it according tomodel. The popover is pointed to the relative_to widget. The created buttons are connected to actions found in theGtk.ApplicationWindow to which the popover belongs - typicallyby means of being attached to a widget that is contained withinthe Gtk.ApplicationWindows 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.

  • Returns: the new Gtk.Popover

  • Since: 3.12

bind_model()

bind_model (self, model:Gio.MenuModel=None, action_namespace:str=None)

Establishes a binding between a Gtk.Popover and a GMenuModel. The contents of popover are removed and then refilled with menu itemsaccording to model. When model changes, popover is updated.Calling this function twice on popover with different model willcause the first binding to be replaced with a binding to the newmodel. If model is None then any previous binding is undone andall children are removed. If action_namespace is non-None then the effect is as if allactions mentioned in the model have their names prefixed with thenamespace, plus a dot. For example, if the action “quit” ismentioned and action_namespace is “app” then the effective actionname is “app.quit”. This function uses Gtk.Actionable to define the action name andtarget values on the created menu items. If you want to use anaction group other than “app” and “win”, or if you want to use aGtk.MenuShell outside of a Gtk.ApplicationWindow, then you will needto attach your own action group to the widget hierarchy using`Gtk.Widget:insert_action_group()`. As an example, if you created agroup with a “quit” action and inserted it with the name “mygroup”then you would use the action name “mygroup.quit” in yourGMenuModel.

  • Since: 3.12

set_relative_to()

set_relative_to (self, relative_to:Gtk.Widget=None)

Sets a new widget to be attached to popover. If popover isvisible, the position will be updated. Note: the ownership of popovers is always given to their relative_towidget, so if relative_to is set to None on an attached popover, itwill be detached from its previous widget, and consequently destroyedunless extra references are kept.

  • Since: 3.12

get_relative_to()

get_relative_to (self) -> Gtk.Widget

Returns the widget popover is currently attached to

  • Returns: a Gtk.Widget.

  • Since: 3.12

set_pointing_to()

set_pointing_to (self, rect:Gdk.Rectangle)

Sets the rectangle that popover will point to, in thecoordinate space of the widget popover is attached to,see Gtk.Popover:set_relative_to().

  • Since: 3.12

get_pointing_to()

get_pointing_to (self) -> bool, rect:Gdk.Rectangle

If a rectangle to point to has been set, this function willreturn True and fill in rect with such rectangle, otherwiseit will return FALSE and fill in rect with the attachedwidget coordinates.

  • Returns: True if a rectangle to point to was set.

set_position()

set_position (self, position:Gtk.PositionType)

Sets the preferred position for popover to appear. If the popoveris currently visible, it will be immediately updated. This preference will be respected where possible, althoughon lack of space (eg. if close to the window edges), theGtk.Popover may choose to appear on the opposite side

  • Since: 3.12

get_position()

get_position (self) -> Gtk.PositionType

Returns the preferred position of popover.

  • Returns: The preferred position.

set_modal()

set_modal (self, modal:bool)

Sets whether popover is modal, a modal popover will grab all inputwithin the toplevel and grab the keyboard focus on it when beingdisplayed. Clicking outside the popover area or pressing Esc willdismiss the popover and ungrab input.

  • Since: 3.12

get_modal()

get_modal (self) -> bool

Returns whether the popover is modal, see Gtk.Popover:set_modal tosee the implications of this.

  • Returns: True if popoveris modal

  • Since: 3.12

set_transitions_enabled()

set_transitions_enabled (self, transitions_enabled:bool)

Sets whether show/hide transitions are enabled on this popover

  • Since: 3.16

get_transitions_enabled()

get_transitions_enabled (self) -> bool

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

  • Returns: True if the show and hide transitions of the givenpopover are enabled, FALSE otherwise.

  • Since: 3.16

set_default_widget()

set_default_widget (self, widget:Gtk.Widget=None)

Sets the widget that should be set as default widget whilethe popover is shown (see `Gtk.Window:set_default()).Gtk.Popoverremembers` the previous default widget and reestablishes itwhen the popover is dismissed.

  • Since: 3.18

get_default_widget()

get_default_widget (self) -> Gtk.Widget

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

  • Returns: the default widget, or None if there is none.

  • Since: 3.18

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class CheckButtonPopover(Gtk.Popover):
    def __init__(self, relate_widget):
        super().__init__()
        self.set_position(Gtk.PositionType.RIGHT)
        self.set_relative_to(relate_widget)

        box = Gtk.Box()
        box.set_spacing(5)
        box.set_orientation(Gtk.Orientation.VERTICAL)
        self.add(box)

        label = Gtk.Label("A Label widget")
        box.add(label)

        checkbutton = Gtk.CheckButton("A CheckButton widget")
        box.add(checkbutton)

class PopoverWin(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("Popover")
        self.set_default_size(250, 250)
        self.connect("destroy", Gtk.main_quit)

        box = Gtk.Box()
        box.set_orientation(Gtk.Orientation.VERTICAL)
        self.add(box)

        button = Gtk.Button("Popover Launcher")
        button.connect("clicked", self.on_popover_clicked)
        box.add(button)

        self.popover = CheckButtonPopover(button)


    def on_popover_clicked(self, button):
        self.popover.show_all()

window = PopoverWin()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""