GI.Gtk.Objects.Popover

GtkPopover is a bubble-like context popup.

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

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

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, popoverSetAutohide may be called on it to tweak its behavior.

GtkPopover as menu replacement

GtkPopover is often used to replace menus. The best was to do this is to use the PopoverMenu subclass which supports being populated from a GMenuModel with popoverMenuNewFromModel.

xml code

<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[.menu]
├── arrow
╰── contents.background
    ╰── <child>

The contents child node always gets the .background style class and the popover itself gets the .menu style class if the popover is menu-like (i.e. GtkPopoverMenu).

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.

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

GObject Popover

Defined in GI.Gtk.Objects.Popover

ManagedPtrNewtype Popover

Defined in GI.Gtk.Objects.Popover

Methods

toManagedPtr :: Popover -> ManagedPtr Popover

TypedObject Popover

Defined in GI.Gtk.Objects.Popover

Methods

glibType :: IO GType

HasParentTypes Popover

Defined in GI.Gtk.Objects.Popover

IsGValue (Maybe Popover)

Convert Popover to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.Popover

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Popover -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Popover)

type ParentTypes Popover

Defined in GI.Gtk.Objects.Popover

type ParentTypes Popover = '[Widget, Object, Accessible, Buildable, ConstraintTarget, Native, ShortcutManager]

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.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, popdown, popup, present, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAutohide, getBuildableId, getCanFocus, getCanTarget, getCascadePopdown, getChild, getChildVisible, getClipboard, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasArrow, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getMnemonicsVisible, getName, getNative, getNextSibling, getOffset, getOpacity, getOverflow, getPangoContext, getParent, getPointingTo, getPosition, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRenderer, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getSurface, getSurfaceTransform, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

Setters

setAutohide, setCanFocus, setCanTarget, setCascadePopdown, setChild, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDefaultWidget, setDirection, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasArrow, setHasTooltip, setHexpand, setHexpandSet, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setMnemonicsVisible, setName, setOffset, setOpacity, setOverflow, setParent, setPointingTo, setPosition, setProperty, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

getAutohide

popoverGetAutohide

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m Bool

Returns: True if popover is modal

Returns whether the popover is modal.

See popoverSetAutohide for the implications of this.

getCascadePopdown

popoverGetCascadePopdown

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m Bool

Returns: True if popover will close after a modal child.

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

getChild

popoverGetChild

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m (Maybe Widget)

Returns: the child widget of popover

Gets the child widget of popover.

getHasArrow

popoverGetHasArrow

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m Bool

Returns: whether the popover has an arrow

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

getMnemonicsVisible

popoverGetMnemonicsVisible

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m Bool

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

Gets whether mnemonics are visible.

getOffset

popoverGetOffset

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m (Int32, Int32)

Gets the offset previous set with popoverSetOffset.

getPointingTo

popoverGetPointingTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m (Bool, Rectangle)

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

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.

getPosition

popoverGetPosition

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m PositionType

Returns: The preferred position.

Returns the preferred position of popover.

new

popoverNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Popover

Returns: the new GtkPopover

Creates a new GtkPopover.

popdown

popoverPopdown

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m ()

Pops popover down.

This may have the side-effect of closing a parent popover as well. See Popover:cascadePopdown.

popup

popoverPopup

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m ()

Pops popover up.

present

popoverPresent

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> m ()

Presents the popover to the user.

setAutohide

popoverSetAutohide

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> Bool

autohide: True to dismiss the popover on outside clicks

-> m ()

Sets whether popover 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.

setCascadePopdown

popoverSetCascadePopdown

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: A GtkPopover

-> Bool

cascadePopdown: True if the popover should follow a child closing

-> m ()

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

If False, popover will stay visible.

setChild

popoverSetChild

Arguments

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

=> a

popover: a GtkPopover

-> Maybe b

child: the child widget

-> m ()

Sets the child widget of popover.

setDefaultWidget

popoverSetDefaultWidget

Arguments

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

=> a

popover: a GtkPopover

-> Maybe b

widget: a child widget of popover to set as the default, or Nothing to unset the default widget for the popover

-> m ()

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.

setHasArrow

popoverSetHasArrow

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> Bool

hasArrow: True to draw an arrow

-> m ()

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

setMnemonicsVisible

popoverSetMnemonicsVisible

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> Bool

mnemonicsVisible: the new value

-> m ()

Sets whether mnemonics should be visible.

setOffset

popoverSetOffset

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> Int32

xOffset: the x offset to adjust the position by

-> Int32

yOffset: the y offset to adjust the position by

-> m ()

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

These values are used when preparing the [structgdk.PopupLayout] for positioning the popover.

setPointingTo

popoverSetPointingTo

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

-> Rectangle

rect: rectangle to point to

-> m ()

Sets the rectangle that popover points to.

This is in the coordinate space of the popover parent.

setPosition

popoverSetPosition

Arguments

:: (HasCallStack, MonadIO m, IsPopover a)

=> a

popover: a GtkPopover

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

Properties

autohide

Whether to dismiss the popover on outside clicks.

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

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

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

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

get popover #autohide

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

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

set popover [ #autohide := value ]

cascadePopdown

Whether the popover pops down after a child popover.

This is used to implement the expected behavior of submenus.

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

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

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

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

get popover #cascadePopdown

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

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

set popover [ #cascadePopdown := value ]

child

The child widget.

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

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

clear #child

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

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

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

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

get popover #child

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

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

set popover [ #child := value ]

defaultWidget

The default widget inside the popover.

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

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

clear #defaultWidget

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

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

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

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

get popover #defaultWidget

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

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

set popover [ #defaultWidget := value ]

hasArrow

Whether to draw an arrow.

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

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

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

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

get popover #hasArrow

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

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

set popover [ #hasArrow := value ]

mnemonicsVisible

Whether mnemonics are currently visible in this popover.

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

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

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

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

get popover #mnemonicsVisible

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

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

set popover [ #mnemonicsVisible := value ]

pointingTo

Rectangle in the parent widget that the popover points to.

constructPopoverPointingTo :: (IsPopover o, MonadIO m) => Rectangle -> m (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

How to place the popover, relative to its parent.

constructPopoverPosition :: (IsPopover o, MonadIO m) => PositionType -> m (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 ]

Signals

activateDefault

type PopoverActivateDefaultCallback = IO ()

Emitted whend the user activates the default widget.

This is a keybinding signal.

afterPopoverActivateDefault :: (IsPopover a, MonadIO m) => a -> ((?self :: a) => PopoverActivateDefaultCallback) -> m SignalHandlerId

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

after popover #activateDefault callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onPopoverActivateDefault :: (IsPopover a, MonadIO m) => a -> ((?self :: a) => PopoverActivateDefaultCallback) -> m SignalHandlerId

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

on popover #activateDefault callback

closed

type PopoverClosedCallback = IO ()

Emitted when the popover is closed.

afterPopoverClosed :: (IsPopover a, MonadIO m) => a -> ((?self :: 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

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onPopoverClosed :: (IsPopover a, MonadIO m) => a -> ((?self :: 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