LPositioner Class Reference

Positioning rules for LPopupRole surfaces. More...

Public Types
enum	Anchor : UInt32
	Anchor point. More...
enum	Gravity : UInt32
	Gravity. More...
enum	ConstraintAdjustments : UInt32
	Constraint adjustments. More...

Public Member Functions
const LSize &	size () const
	Size in surface coordinates. More...
const LRect &	anchorRect () const
	Anchor rect in surface coordinates. More...
const LPoint &	offset () const noexcept
	Additional offset in surface coordinates. More...
Anchor	anchor () const noexcept
	Anchor point. More...
Gravity	gravity () const noexcept
	Popup gravity. More...
LBitset< ConstraintAdjustments >	constraintAdjustments () const noexcept
	Constraint adjustment rules. More...
bool	reactive () const noexcept
	Determines if the popup should be reconfigured, for example, when the parent surface moves. More...
bool	hasParentSize () const noexcept
	Checks if the popup is being repositioned according to a future parent size. More...
const LSize &	parentSize () const noexcept
	Parent size. More...
bool	hasParentConfigureSerial () const noexcept
	Checks if the popup is being repositioned according to a future parent configuration. More...
UInt32	parentConfigureSerial () const noexcept
	Parent configuration serial. More...

Detailed Description

Positioning rules for LPopupRole surfaces.

The LPositioner class defines the rules by which a popup should be positioned relative to the anchor point of its parent.
Each LPopupRole has its own LPositioner accessible through LPopupRole::positioner().

Anchor Rect

The anchorRect() defines a sub-rectangle within the parent surface's window geometry. Within this sub-rectangle, an anchor point is specified, which the popup uses as a reference for positioning itself.

The anchor point can be located at the center, the corners, or the midpoints of the edges of the anchor rectangle (indicated by gray and blue points).

For example, in the following image, a popup is positioned using the anchor points AnchorRight and AnchorBottomLeft.

Gravity

The gravity() of the popup indicates the direction in which it tries to move.

You can visualize the anchor point as a "nail" and the popup as a frame composed only of edges. If the gravity is down, the top edge of the popup will collide with the nail, preventing it from moving further.

In the following image, a popup is shown with gravity set to GravityBottomRight and GravityTopLeft .

Constraint Adjustments

You might be wondering why such complex rules are used to position popups. The answer is that these rules simplify repositioning popups when their initial position causes constraints (e.g., when they appear outside the visible area of the screen).

The specific rules for adjusting the position of popups when they are constrained are defined by the client in constraintAdjustments(). Typically, the process involves the following steps:

1. Inverting the gravity and anchor point on the axes where the constraint occurs (useful in nested context menus).
2. Sliding the popup along the relevant axes if it remains constrained.
3. Adjusting the popup's size if sliding does not resolve the issue.
4. Reverting to the original position if none of the above options work.

For more information on LPositioner rules, consult the documentation of the xdg_shell::positioner interface.

Member Enumeration Documentation

Anchor

enum Anchor : UInt32

Anchor point.

Enumerator
NoAnchor	Center of the anchor rect.
AnchorTop	Center of the top edge.
AnchorBottom	Center of the bottom edge.
AnchorLeft	Center of the left edge.
AnchorRight	Center of the right edge.
AnchorTopLeft	Top-left corner.
AnchorBottomLeft	Bottom-left corner.
AnchorTopRight	Top-right corner.
AnchorBottomRight	Bottom-right corner.

Gravity

enum Gravity : UInt32

Gravity.

The direction in which the popup tries to move.

Enumerator
NoGravity	Centered.
GravityTop	Upwards.
GravityBottom	Downwards.
GravityLeft	Leftwards.
GravityRight	Rightwards.
GravityTopLeft	Upwards and Leftwards.
GravityBottomLeft	Downwards and Leftwards.
GravityTopRight	Upwards and Rightwards.
GravityBottomRight	Downwards and Rightwards.

ConstraintAdjustments

enum ConstraintAdjustments : UInt32

Constraint adjustments.

Rules for handling a constrained popup.

Enumerator
NoAdjustment	Original position is not modified.
SlideX	Horizontally slide.
SlideY	Vertically slide.
FlipX	Invert horizontal component of gravity and anchor point.
FlipY	Invert vertical component of gravity and anchor point.
ResizeX	Scale Popup horizontally.
ResizeY	Scale Popup vertically.

Member Function Documentation

size()

const LSize& size ( ) const

inline

Size in surface coordinates.

Size of the popup to be positioned (window geometry size) in surface coordinates.

anchorRect()

const LRect& anchorRect ( ) const

inline

Anchor rect in surface coordinates.

Anchor rect relative to the parent window geometry in surface coordinates.

offset()

const LPoint& offset ( ) const

inlinenoexcept

Additional offset in surface coordinates.

Additional offset in surface coordinates added to the final calculated position.

anchor()

Anchor anchor ( ) const

inlinenoexcept

Anchor point.

Edge or corner within the anchorRect() the popup is positioned relative to.

gravity()

Gravity gravity ( ) const

inlinenoexcept

Popup gravity.

Direction in which the popup is trying to move, defined in LPositioner::Gravity.

constraintAdjustments()

LBitset<ConstraintAdjustments> constraintAdjustments ( ) const

inlinenoexcept

Constraint adjustment rules.

Flags with rules used to unconstrain the popup.

reactive()

bool reactive ( ) const

inlinenoexcept

Determines if the popup should be reconfigured, for example, when the parent surface moves.

This method checks whether the popup needs to be reconfigured in response to changes in the parent surface, such as movement or other configuration changes.

Returns

true if the popup should be reconfigured, false otherwise.

hasParentSize()

bool hasParentSize ( ) const

inlinenoexcept

Checks if the popup is being repositioned according to a future parent size.

The compositor may use parentConfigureSerial() together with parentSize() to determine what future state the popup should be constrained using during an LPopupRole::configureRequest().

See also

parentConfigureSerial()

LPopupRole::configureRequest()

Returns

true if the popup is being repositioned due to a parent configure change, false otherwise.

parentSize()

const LSize& parentSize ( ) const

inlinenoexcept

Parent size.

See also

hasParentSize().

hasParentConfigureSerial()

bool hasParentConfigureSerial ( ) const

inlinenoexcept

Checks if the popup is being repositioned according to a future parent configuration.

The compositor may use parentConfigureSerial() together with parentSize() to determine what future state the popup should be constrained using during an LPopupRole::configureRequest().

See also

parentConfigureSerial()

LPopupRole::configureRequest()

Returns

true if the popup is being repositioned according to a future parent configuration, false otherwise.

parentConfigureSerial()

UInt32 parentConfigureSerial ( ) const

inlinenoexcept

Parent configuration serial.

See also

hasParentConfigureSerial().