GI.Gtk.Objects.Popover

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 popoverNew, or updated afterwards through popoverSetRelativeTo, by default they will point to the whole widget area, although this behavior can be changed through popoverSetPointingTo.

The position of a popover relative to the widget it is attached to can also be changed through popoverSetPosition.

By default, 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, popoverSetModal 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 MenuModel, using popoverNewFromModel. 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. PopoverMenu or created using popoverNewFromModel.

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

Since: 3.12

Exported types

newtype Popover

Memory-managed wrapper type.

Constructors

Popover (ManagedPtr Popover)

Instances

Eq Popover

Defined in GI.Gtk.Objects.Popover

Methods

(==) :: Popover -> Popover -> Bool

(/=) :: Popover -> Popover -> Bool

IsGValue Popover

Convert Popover to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Objects.Popover

Methods

toGValue :: Popover -> IO GValue

fromGValue :: GValue -> IO Popover

GObject Popover

Defined in GI.Gtk.Objects.Popover

Methods

gobjectType :: IO GType

HasParentTypes Popover

Defined in GI.Gtk.Objects.Popover

type ParentTypes Popover

Defined in GI.Gtk.Objects.Popover

type ParentTypes Popover = '[Bin, Container, Widget, Object, ImplementorIface, Buildable]

class (GObject o, IsDescendantOf Popover o) => IsPopover o

Type class for types which can be safely cast to Popover, for instance with toPopover.

Instances

(GObject o, IsDescendantOf Popover o) => IsPopover o

Defined in GI.Gtk.Objects.Popover

toPopover :: (MonadIO m, IsPopover o) => o -> m Popover

Cast to Popover, for types for which this is known to be safe. For general casts, use castTo.

noPopover :: Maybe Popover

A convenience alias for Nothing :: Maybe Popover.

Methods

Overloaded methods

bindModel

popoverBindModel

Arguments

:: (HasCallStack, MonadIO m, IsPopover a, IsMenuModel b)

=> a

popover: a Popover

-> Maybe b

model: the MenuModel to bind to or Nothing to remove binding

-> Maybe Text

actionNamespace: the namespace for actions in model

-> m ()

Establishes a binding between a Popover and a MenuModel.

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 Nothing then any previous binding is undone and all children are removed.

If actionNamespace is non-Nothing 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 actionNamespace is “app” then the effective action name is “app.quit”.

This function uses 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 MenuShell outside of a ApplicationWindow, then you will need to attach your own action group to the widget hierarchy using widgetInsertActionGroup. 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 MenuModel.

Since: 3.12

getConstrainTo

popoverGetConstrainTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m PopoverConstraint

Returns: the constraint for placing this popover.

Returns the constraint for placing this popover. See popoverSetConstrainTo.

Since: 3.20

getDefaultWidget

popoverGetDefaultWidget

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m (Maybe Widget)

Returns: the default widget, or Nothing if there is none

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

Since: 3.18

getModal

popoverGetModal

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m Bool

Returns: TRUE if popover is modal

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

Since: 3.12

getPointingTo

popoverGetPointingTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m (Bool, Rectangle)

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

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.

getPosition

popoverGetPosition

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m PositionType

Returns: The preferred position.

Returns the preferred position of popover.

getRelativeTo

popoverGetRelativeTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m Widget

Returns: a Widget

Returns the widget popover is currently attached to

Since: 3.12

getTransitionsEnabled

popoverGetTransitionsEnabled

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m Bool

Returns: TRUE if the show and hide transitions of the given popover are enabled, FALSE otherwise.

Deprecated: (Since version 3.22)You can show or hide the popover without transitions using widgetShow and widgetHide while popoverPopup and popoverPopdown will use transitions.

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

Since: 3.16

new

popoverNew

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> Maybe a

relativeTo: Widget the popover is related to

-> m Popover

Returns: a new Popover

Creates a new popover to point to relativeTo

Since: 3.12

newFromModel

popoverNewFromModel

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsMenuModel b)

=> Maybe a

relativeTo: Widget the popover is related to

-> b

model: a MenuModel

-> m Popover

Returns: the new Popover

Creates a Popover and populates it according to model. The popover is pointed to the relativeTo widget.

The created buttons are connected to actions found in the ApplicationWindow 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 widgetInsertActionGroup on the menus attach widget or on any of its parent widgets.

Since: 3.12

popdown

popoverPopdown

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m ()

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

Since: 3.22

popup

popoverPopup

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> m ()

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

Since: 3.22

setConstrainTo

popoverSetConstrainTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> PopoverConstraint

constraint: the new constraint

-> m ()

Sets a constraint for positioning this popover.

Note that not all platforms support placing popovers freely, and may already impose constraints.

Since: 3.20

setDefaultWidget

popoverSetDefaultWidget

Arguments

:: (HasCallStack, MonadIO m, IsPopover a, IsWidget b)

=> a

popover: a Popover

-> Maybe b

widget: the new default widget, or Nothing

-> m ()

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

Since: 3.18

setModal

popoverSetModal

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> Bool

modal: TRUE to make popover claim all input within the toplevel

-> m ()

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

setPointingTo

popoverSetPointingTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> Rectangle

rect: rectangle to point to

-> m ()

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

Since: 3.12

setPosition

popoverSetPosition

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> PositionType

position: preferred popover position

-> m ()

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 Popover may choose to appear on the opposite side

Since: 3.12

setRelativeTo

popoverSetRelativeTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a, IsWidget b)

=> a

popover: a Popover

-> Maybe b

relativeTo: a Widget

-> m ()

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 relativeTo widget, so if relativeTo is set to Nothing on an attached popover, it will be detached from its previous widget, and consequently destroyed unless extra references are kept.

Since: 3.12

setTransitionsEnabled

popoverSetTransitionsEnabled

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a Popover

-> Bool

transitionsEnabled: Whether transitions are enabled

-> m ()

Deprecated: (Since version 3.22)You can show or hide the popover without transitions using widgetShow and widgetHide while popoverPopup and popoverPopdown will use transitions.

Sets whether show/hide transitions are enabled on this popover

Since: 3.16

Properties

constrainTo

Sets a constraint for the popover position.

Since: 3.20

constructPopoverConstrainTo :: IsPopover o => PopoverConstraint -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “constrain-to” property. This is rarely needed directly, but it is used by new.

getPopoverConstrainTo :: (MonadIO m, IsPopover o) => o -> m PopoverConstraint

Get the value of the “constrain-to” property. When overloading is enabled, this is equivalent to

get popover #constrainTo

setPopoverConstrainTo :: (MonadIO m, IsPopover o) => o -> PopoverConstraint -> m ()

Set the value of the “constrain-to” property. When overloading is enabled, this is equivalent to

set popover [ #constrainTo := value ]

modal

Sets whether the popover is modal (so other elements in the window do not receive input while the popover is visible).

Since: 3.12

constructPopoverModal :: IsPopover o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “modal” property. This is rarely needed directly, but it is used by new.

getPopoverModal :: (MonadIO m, IsPopover o) => o -> m Bool

Get the value of the “modal” property. When overloading is enabled, this is equivalent to

get popover #modal

setPopoverModal :: (MonadIO m, IsPopover o) => o -> Bool -> m ()

Set the value of the “modal” property. When overloading is enabled, this is equivalent to

set popover [ #modal := value ]

pointingTo

Marks a specific rectangle to be pointed.

Since: 3.12

constructPopoverPointingTo :: IsPopover o => Rectangle -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “pointing-to” property. This is rarely needed directly, but it is used by new.

getPopoverPointingTo :: (MonadIO m, IsPopover o) => o -> m (Maybe Rectangle)

Get the value of the “pointing-to” property. When overloading is enabled, this is equivalent to

get popover #pointingTo

setPopoverPointingTo :: (MonadIO m, IsPopover o) => o -> Rectangle -> m ()

Set the value of the “pointing-to” property. When overloading is enabled, this is equivalent to

set popover [ #pointingTo := value ]

position

Sets the preferred position of the popover.

Since: 3.12

constructPopoverPosition :: IsPopover o => PositionType -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “position” property. This is rarely needed directly, but it is used by new.

getPopoverPosition :: (MonadIO m, IsPopover o) => o -> m PositionType

Get the value of the “position” property. When overloading is enabled, this is equivalent to

get popover #position

setPopoverPosition :: (MonadIO m, IsPopover o) => o -> PositionType -> m ()

Set the value of the “position” property. When overloading is enabled, this is equivalent to

set popover [ #position := value ]

relativeTo

Sets the attached widget.

Since: 3.12

clearPopoverRelativeTo :: (MonadIO m, IsPopover o) => o -> m ()

Set the value of the “relative-to” property to Nothing. When overloading is enabled, this is equivalent to

clear #relativeTo

constructPopoverRelativeTo :: (IsPopover o, IsWidget a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “relative-to” property. This is rarely needed directly, but it is used by new.

getPopoverRelativeTo :: (MonadIO m, IsPopover o) => o -> m Widget

Get the value of the “relative-to” property. When overloading is enabled, this is equivalent to

get popover #relativeTo

setPopoverRelativeTo :: (MonadIO m, IsPopover o, IsWidget a) => o -> a -> m ()

Set the value of the “relative-to” property. When overloading is enabled, this is equivalent to

set popover [ #relativeTo := value ]

transitionsEnabled

Whether show/hide transitions are enabled for this popover.

Since: 3.16

constructPopoverTransitionsEnabled :: IsPopover o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “transitions-enabled” property. This is rarely needed directly, but it is used by new.

getPopoverTransitionsEnabled :: (MonadIO m, IsPopover o) => o -> m Bool

Get the value of the “transitions-enabled” property. When overloading is enabled, this is equivalent to

get popover #transitionsEnabled

setPopoverTransitionsEnabled :: (MonadIO m, IsPopover o) => o -> Bool -> m ()

Set the value of the “transitions-enabled” property. When overloading is enabled, this is equivalent to

set popover [ #transitionsEnabled := value ]

Signals

closed

type C_PopoverClosedCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type PopoverClosedCallback = IO ()

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

Since: 3.12

afterPopoverClosed :: (IsPopover a, MonadIO m) => a -> PopoverClosedCallback -> m SignalHandlerId

Connect a signal handler for the closed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after popover #closed callback

genClosure_PopoverClosed :: MonadIO m => PopoverClosedCallback -> m (GClosure C_PopoverClosedCallback)

Wrap the callback into a GClosure.

mk_PopoverClosedCallback :: C_PopoverClosedCallback -> IO (FunPtr C_PopoverClosedCallback)

Generate a function pointer callable from C code, from a C_PopoverClosedCallback.

noPopoverClosedCallback :: Maybe PopoverClosedCallback

A convenience synonym for Nothing :: Maybe PopoverClosedCallback.

onPopoverClosed :: (IsPopover a, MonadIO m) => a -> PopoverClosedCallback -> m SignalHandlerId

Connect a signal handler for the closed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on popover #closed callback

wrap_PopoverClosedCallback :: PopoverClosedCallback -> C_PopoverClosedCallback

Wrap a PopoverClosedCallback into a C_PopoverClosedCallback.