LPopupRole Class Reference

Popup role for surfaces. More...

Inheritance diagram for LPopupRole:

Classes
struct	Atoms
	Atomic properties. More...
struct	Configuration
	Configuration parameters sent to the client. More...

Public Types
enum	AtomChanges : UInt32
	Flags indicating which atomic properties have changed during an atomsChanged() event. More...
Public Types inherited from LBaseSurfaceRole
enum	CommitOrigin
	Commit origin. More...
Public Types inherited from LFactoryObject
enum class	Type : Int32
	Base factory object types. More...

Public Member Functions
	LPopupRole (const void *params) noexcept
	Constructor of the LPopupRole class. More...
	~LPopupRole ()
	Destructor of the LPopupRole class. More...
const Configuration *	findConfiguration (UInt32 serial) const noexcept
	Find configuration by serial number. More...
const Configuration &	pendingConfiguration () const noexcept
	Pending configuration. More...
void	configureRect (const LRect &rect) const noexcept
	Configures the popup local position and size. More...
LRect	calculateUnconstrainedRect (const LPoint *futureParentPos=nullptr) const noexcept
	Calculates the size and parent-local position the popup should be configured to in order to be unconstrained. More...
void	setBounds (const LRect &bounds) noexcept
	Set the positioning bounds constraints for the popup. More...
const LRect &	bounds () const noexcept
	Gets the constraint bounds. More...
LBitset< LEdge >	constrainedEdges (const LRect &rect) const noexcept
	Checks which toplevel edges would be constrained if the popup is positioned within the given rect. More...
const Atoms &	atoms () const noexcept
	Current atomic properties. More...
const LRect &	windowGeometry () const noexcept
	Window geometry in surface coordinates. More...
const LPoint &	localPos () const noexcept
	Retrieves the current local position relative to the parent window geometry. More...
const LPositioner &	positioner () const
	Gets the positioning rules for the popup. More...
void	dismiss ()
	Dismiss the popup. More...
bool	isTopmostPopup () const noexcept
	Check if this oopup is the topmost withing the same client. More...
void	setExclusiveOutput (LOutput *output) noexcept
	Sets the exclusive output hint. More...
virtual LOutput *	exclusiveOutput () const override
	Exclusive output hint. More...
Protocols::XdgShell::RXdgPopup *	xdgPopupResource () const noexcept
	xdg_popup resource from the XDG Shell protocol. More...
Protocols::XdgShell::RXdgSurface *	xdgSurfaceResource () const noexcept
	xdg_surface resource from the XDG Shell protocol. More...
Public Member Functions inherited from LBaseSurfaceRole
	LBaseSurfaceRole (LFactoryObject::Type type, LResource *resource, LSurface *surface, UInt32 roleId) noexcept
	Constructor of LBaseSurfaceRole class. More...
	~LBaseSurfaceRole ()
	The LBaseSurfaceRole class destructor. More...
UInt32	roleId () const noexcept
	Role ID. More...
LSurface *	surface () const noexcept
	Returns the surface that has acquired the role provided in the constructor. More...
LResource *	resource () const
	Returns the Wayland resource for this role given in the constructor. More...
LClient *	client () const noexcept
	Client owner of the surface role. More...
Public Member Functions inherited from LFactoryObject
Type	factoryObjectType () const noexcept
	Gets the base factory object type. More...
Public Member Functions inherited from LObject
	LObject (const LObject &) noexcept
	Copy constructor. More...
LObject &	operator= (const LObject &) noexcept
	Assignment operator (each object has its own individual LWeak reference count). More...
void	setUserData (UIntPtr data) const noexcept
	Store an unsigned integer value/pointer. More...
UIntPtr	userData () const noexcept
	Retrieves the stored unsigned integer value/pointer. More...

Virtual Methods
virtual const LPoint &	rolePos () const override
	Position of the popup surface according to the role. More...
virtual void	configureRequest ()
	Handles client requests for configuring the popup. More...
virtual void	atomsChanged (LBitset< AtomChanges > changes, const Atoms &prevAtoms)
	Notifies a change in atomic properties. More...
virtual void	grabKeyboardRequest (const LEvent &triggeringEvent)
	Request to grab the keyboard. More...

Additional Inherited Members
Protected Member Functions inherited from LBaseSurfaceRole
virtual bool	acceptCommitRequest (CommitOrigin origin)
	Asks if the surface commit should be processed. More...
virtual void	handleSurfaceBufferAttach (wl_resource *buffer, Int32 x, Int32 y)
	Notifies a new surface buffer attachment. More...
virtual void	handleSurfaceOffset (Int32 x, Int32 y)
	Notifies a surface buffer offset change. More...
virtual void	handleParentCommit ()
	Notifies a parent surface commit. More...
virtual void	handleParentMappingChange ()
	Notifies when the mapping state of the parent surface changes. More...
virtual void	handleParentChange ()
	Notifies when the parent surface changes. More...
Protected Member Functions inherited from LObject
	LObject () noexcept=default
	Constructor of the LObject class. More...
virtual	~LObject () noexcept
	Destructor of the LObject class. More...
void	notifyDestruction () noexcept
	Notifies the object destruction. More...
Protected Attributes inherited from LBaseSurfaceRole
LPoint	m_rolePos
	Variable that stores the surface position given the role. More...

Detailed Description

Popup role for surfaces.

The LPopupRole class is a role for surfaces commonly used by clients to display context menus and tooltips.

The popup role is part of the XDG Shell. The Wayland protocol also has its own popup role, but it is considered obsolete and therefore not included in the library.

---

Class Documentation

Louvre::LPopupRole::Atoms

struct Louvre::LPopupRole::Atoms

Atomic properties.

This struct contains all LPopupRole properties that should be handled simultaneously during an atomsChanged() event.

See also

atoms()

Class Members
LRect	windowGeometry	LPopupRole::windowGeometry()
LPoint	localPos	LPopupRole::localPos()
UInt32	serial	LPopupRole::serial()

Louvre::LPopupRole::Configuration

struct Louvre::LPopupRole::Configuration

Configuration parameters sent to the client.

See also

configureRect()

pendingConfiguration()

findConfiguration()

Class Members
LRect	rect	Local position and size. See localPos() and windowGeometry().
UInt32	serial	See also LPopupRole::serial() and pendingConfiguration()

Member Enumeration Documentation

AtomChanges

enum AtomChanges : UInt32

Flags indicating which atomic properties have changed during an atomsChanged() event.

See also

Atoms

atoms()

atomsChanged()

Enumerator
WindowGeometryChanged	Indicates windowGeometry() changed.
LocalPosChanged	Indicates localPos() changed.
SerialChanged	Indicates serial() changed.

Constructor & Destructor Documentation

LPopupRole()

LPopupRole ( const void *  params )

noexcept

Constructor of the LPopupRole class.

Parameters

params

Internal parameters provided in LCompositor::createObjectRequest().

~LPopupRole()

~LPopupRole ( )

inline

Destructor of the LPopupRole class.

Invoked after LCompositor::onAnticipatedObjectDestruction().

Member Function Documentation

findConfiguration()

const LPopupRole::Configuration * findConfiguration ( UInt32  serial ) const

noexcept

Find configuration by serial number.

Warning

The returned configuration must not be deleted.

Returns

A pointer to the configuration if found, otherwise nullptr.

pendingConfiguration()

const Configuration& pendingConfiguration ( ) const

inlinenoexcept

Pending configuration.

This struct holds the last configuration parameters assigned with configureRect().

The pending configuration parameters are sent to the client at most once per Louvre main loop iteration.

The pending serial is also updated at most once per loop iteration if a configure was done.

If the pending configuration serial is equal to serial() it means the last configuration was ACK by the client and there is no pending configuration.

See also

atomsChanged() to detect when the serial and other parameters change.

configureRect()

void configureRect ( const LRect &  rect ) const

noexcept

Configures the popup local position and size.

This method instructs the client to set the size and local position of the popup and stores the value in pendingConfiguration().
The position is relative to its parent's window geometry, and the size does not include the popup decorations, see windowGeometry().

See also

calculateUnconstrainedRect().

calculateUnconstrainedRect()

LRect calculateUnconstrainedRect ( const LPoint *  futureParentPos = nullptr ) const

noexcept

Calculates the size and parent-local position the popup should be configured to in order to be unconstrained.

Note

Ensure that bounds() is properly set before using this method.

Parameters

futureParentPos

The future position of the parent surface, or nullptr to use the current position. See LPositioner::hasParentConfigureSerial() and LPositioner::hasParentSize().

Returns

The calculated rect representing the unconstrained size and position.

setBounds()

void setBounds ( const LRect &  bounds )

inlinenoexcept

Set the positioning bounds constraints for the popup.

This method is used to define the area within which the popup must be positioned.

Parameters

bounds

The constraint rect in compositor-global coordinates. Providing a rect with zero area deactivates the constraint.

bounds()

const LRect& bounds ( ) const

inlinenoexcept

Gets the constraint bounds.

This method returns the constraint bounds for positioning the popup which can be set using setBounds().

constrainedEdges()

LBitset< LEdge > constrainedEdges ( const LRect &  rect ) const

noexcept

Checks which toplevel edges would be constrained if the popup is positioned within the given rect.

Parameters

rect	The bounds in compositor-global coordinates.

Returns

A bitset indicating the constrained edges.

atoms()

const Atoms& atoms ( ) const

inlinenoexcept

Current atomic properties.

This struct contains all the current popup atomic properties, which are updated each time atomsChanged() is triggered.

The current properties can also be accessed via aliases such as windowGeometry(), localPos(), serial(), etc.

windowGeometry()

const LRect& windowGeometry ( ) const

inlinenoexcept

Window geometry in surface coordinates.

The window geometry is a rect within the popups's surface that excludes its decorations (typically shadows).

Note

This is an alias for Atoms::windowGeometry.

localPos()

const LPoint& localPos ( ) const

inlinenoexcept

Retrieves the current local position relative to the parent window geometry.

Returns the last configured local position acknowledged by the client.
Initially set to (0,0).

See also

configureRect()

Note

This is an alias for Atoms::localPos.

positioner()

const LPositioner& positioner ( ) const

inline

Gets the positioning rules for the popup.

dismiss()

void dismiss

(

)

Dismiss the popup.

This method closes the popup along with all its children, starting from the topmost and descending downwards.

isTopmostPopup()

bool isTopmostPopup ( ) const

noexcept

Check if this oopup is the topmost withing the same client.

Returns

true if it's the topmost popup, false otherwise.

setExclusiveOutput()

void setExclusiveOutput ( LOutput *  output )

noexcept

Sets the exclusive output hint.

This is an optional hint that can be used to keep a reference of in which LOutput a popup is positioned.

The default implementation of LOutput::paintGL() uses this information to prevent displaying the given popup on other outputs.

See also

exclusiveOutput()

Parameters

output

The given output or nullptr to unset.

exclusiveOutput()

virtual LOutput* exclusiveOutput ( ) const

inlineoverridevirtual

Exclusive output hint.

Returns the exclusive output hint set with setExclusiveOutput(), or nullptr if unset.

Reimplemented from LBaseSurfaceRole.

xdgPopupResource()

XdgShell::RXdgPopup * xdgPopupResource ( ) const

noexcept

xdg_popup resource from the XDG Shell protocol.

xdgSurfaceResource()

XdgShell::RXdgSurface * xdgSurfaceResource ( ) const

noexcept

xdg_surface resource from the XDG Shell protocol.

rolePos()

virtual const LPoint& rolePos ( ) const

overridevirtual

Position of the popup surface according to the role.

See also

configureRect()

Default Implementation

const LPoint &LPopupRole::rolePos() const
{
    /* Just in case this method is called while the popup is being destroyed */
    if (!surface()->parent())
        return m_rolePos;
 
    m_rolePos = surface()->parent()->rolePos() + localPos() - windowGeometry().topLeft();
 
    if (surface()->parent()->toplevel())
        m_rolePos += surface()->parent()->toplevel()->windowGeometry().pos();
    else if (surface()->parent()->popup())
        m_rolePos += surface()->parent()->popup()->windowGeometry().pos();
 
    return m_rolePos;
}

Implements LBaseSurfaceRole.

configureRequest()

virtual void configureRequest ( )

virtual

Handles client requests for configuring the popup.

This method is triggered before the client maps the popup surface and each time the client updates the positioner() rules.

Default Implementation

void LPopupRole::configureRequest()
{
    // Ensure the Popup stays within the boundaries of the current output where the cursor is positioned
    setBounds(cursor()->output() != nullptr ? cursor()->output()->rect() : LRect(0,0,0,0));
    configureRect(calculateUnconstrainedRect());
}

atomsChanged()

virtual void atomsChanged ( LBitset< AtomChanges >  changes, const Atoms &  prevAtoms  )

virtual

Notifies a change in atomic properties.

This event is triggered each time one or more of the atoms() change.

Parameters

changes	Flags indicating which properties in atoms() have changed.
prevAtoms	Structure containing the previous values of atoms().

Default Implementation

void LPopupRole::atomsChanged(LBitset<AtomChanges> changes, const Atoms &prevAtoms)
{
    L_UNUSED(changes)
    L_UNUSED(prevAtoms)
}

grabKeyboardRequest()

virtual void grabKeyboardRequest ( const LEvent &  triggeringEvent )

virtual

Request to grab the keyboard.

Client request to redirect all keyboard events to the popup. See LKeyboard::setGrab().
During a keyboard grab, no other surfaces can acquire keyboard focus.
Additionally, if the surface undergoing the grab is destroyed, the keyboard grab is transferred to its parent surface.

Note

If the keyboard grab is not set, the popup is dismissed immediately.

Parameters

triggeringEvent

The input event that triggered the grab request.

Default Implementation

void LPopupRole::grabKeyboardRequest(const LEvent &triggeringEvent)
{
    if (sessionLockManager()->state() != LSessionLockManager::Unlocked && sessionLockManager()->client() != client())
        return;
 
    if (triggeringEvent.type() == LEvent::Type::Pointer)
    {
        if (!seat()->pointer()->focus())
            return;
 
        if (seat()->pointer()->focus()->client() != surface()->client())
            return;
    }
    else if (triggeringEvent.type() == LEvent::Type::Keyboard)
    {
        if (!seat()->keyboard()->focus())
            return;
 
        if (seat()->keyboard()->focus()->client() != surface()->client())
            return;
    }
    else if (triggeringEvent.type() == LEvent::Type::Touch)
    {
        if (triggeringEvent.subtype() != LEvent::Subtype::Down)
            return;
 
        const auto &touchDownEvent { (const LTouchDownEvent &)triggeringEvent };
        const auto *touchPoint { seat()->touch()->findTouchPoint(touchDownEvent.id()) };
 
        if (!touchPoint->surface())
            return;
 
        if (touchPoint->surface()->client() != surface()->client())
            return;
    }
 
    seat()->keyboard()->setGrab(surface());
}