LToplevelRole Class Reference

Toplevel role for surfaces. More...

Inheritance diagram for LToplevelRole:

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

Public Types
enum	State : UInt16
	Flags indicating the possible states of a Toplevel. More...
enum	DecorationMode : UInt32
	Decoration mode. More...
enum	AtomChanges : UInt32
	Flags indicating which atomic properties have changed during an atomsChanged() event. More...
enum	Capabilities : UInt8
	Compositor capabilities flags. 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
	LToplevelRole (const void *params) noexcept
	Constructor of the LToplevelRole class. More...
	~LToplevelRole ()=default
	Destructor of the LToplevelRole class. More...
const Configuration *	findConfiguration (UInt32 serial) const noexcept
	Find configuration by serial number. More...
const Configuration &	pendingConfiguration () const noexcept
	Pending configuration. More...
void	configureState (LBitset< State > flags) noexcept
	Configure the toplevel state. More...
void	configureSize (const LSize &size) noexcept
	Configure the toplevel size. More...
void	configureSize (Int32 width, Int32 height) noexcept
	Configure the toplevel size. More...
void	configureDecorationMode (DecorationMode mode) noexcept
	Configure the toplevel decoration mode. More...
void	configureCapabilities (LBitset< Capabilities > caps) noexcept
	Notifies the toplevel about the compositor's capabilities. More...
void	configureBounds (const LSize &bounds) noexcept
	Asks the client to constrain its size to the specified bounds. More...
void	configureBounds (Int32 width, Int32 height) noexcept
	Asks the client to constrain its size to the specified bounds. More...
const Atoms &	atoms () const noexcept
	Current atomic properties. More...
LBitset< State >	state () const noexcept
	Current toplevel state. More...
LBitset< State >	supportedStates () const noexcept
	Returns the states supported by the toplevel. More...
bool	activated () const noexcept
	Checks if the toplevel state() includes the Activated flag. More...
bool	maximized () const noexcept
	Checks if the toplevel state() includes the Maximized flag. More...
bool	fullscreen () const noexcept
	Checks if the toplevel state() includes the Fullscreen flag. More...
bool	tiled () const noexcept
	Checks if the toplevel state() includes any of the tiled flags. More...
bool	resizing () const noexcept
	Checks if the toplevel state() includes the Resizing flag. More...
bool	suspended () const noexcept
	Checks if the toplevel state() includes the Suspended flag. More...
const LRect &	windowGeometry () const noexcept
	Window geometry in surface coordinates. More...
void	setExtraGeometry (const LMargins &margins) noexcept
	Sets extra geometry margins. More...
const LMargins &	extraGeometry () const noexcept
	Extra geometry margins. More...
const LSize &	minSize () const noexcept
	Gets the minimum size of the toplevel in surface coordinates. More...
const LSize &	maxSize () const noexcept
	Gets the maximum size of the toplevel in surface coordinates. More...
bool	sizeInRange (const LSize &size) const noexcept
	Check if the provided size falls within the range defined by minSize() and maxSize(). More...
LMargins	calculateConstraintsFromOutput (LOutput *output, bool includeExtraGeometry=true) const noexcept
	Constraints during move/resize sessions. More...
const LSize &	bounds () const noexcept
	Current bounds. More...
LBitset< Capabilities >	capabilities () const noexcept
	Current capabilities. More...
DecorationMode	decorationMode () const noexcept
	The current decoration mode. More...
DecorationMode	preferredDecorationMode () const noexcept
	Gets the preferred decoration mode set by the client. More...
bool	supportServerSideDecorations () const noexcept
	Check if the toplevel supports server-side decorations. More...
UInt32	serial () const noexcept
	Last configuration serial ACK by the client. More...
void	setExclusiveOutput (LOutput *output) noexcept
	Sets the exclusive output hint. More...
virtual LOutput *	exclusiveOutput () const override
	Exclusive output hint. More...
LToplevelMoveSession &	moveSession () const noexcept
	Utility for handling interactive moving sessions. More...
LToplevelResizeSession &	resizeSession () const noexcept
	Utility for handling interactive resizing sessions. More...
Protocols::XdgShell::RXdgToplevel *	xdgToplevelResource () const
	xdg_toplevel resource from the XDG Shell protocol. More...
Protocols::XdgShell::RXdgSurface *	xdgSurfaceResource () const
	xdg_surface resource from the XDG Shell protocol. More...
const std::string &	appId () const noexcept
	Gets the application ID associated with the toplevel window. More...
const std::string &	title () const noexcept
	Gets the window title of the toplevel. More...
void	close () noexcept
	Closes the toplevel. More...
const std::vector< LForeignToplevelController * > &	foreignControllers () const noexcept
	Vector of foreign controllers. More...
LForeignToplevelController *	requesterController () const noexcept
	LForeignToplevelController triggering a request. More...
const std::vector< Protocols::ForeignToplevelList::RForeignToplevelHandle * >	foreignHandles () const noexcept
	Vector of foreign handles. More...
const std::string &	foreignToplevelListIdentifier () const noexcept
	ID used by foreign clients to identify the toplevel. 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...

Public Attributes
LRect	prevRect
	Auxiliary previous rect. More...

Virtual Methods
virtual const LPoint &	rolePos () const override
	Position of the surface according to the role. More...
virtual void	configureRequest ()
	Configuration request. More...
virtual void	atomsChanged (LBitset< AtomChanges > changes, const Atoms &prevAtoms)
	Notifies a change in atomic properties. More...
virtual void	startMoveRequest (const LEvent &triggeringEvent)
	Client request to initiate an interactive move session. More...
virtual void	startResizeRequest (const LEvent &triggeringEvent, LBitset< LEdge > edge)
	Client request to initiate an interactive resize session. More...
virtual void	activateRequest ()
	Request to activate. More...
virtual void	setMaximizedRequest ()
	Request to maximize. More...
virtual void	unsetMaximizedRequest ()
	Request to unmaximize. More...
virtual void	setFullscreenRequest (LOutput *destOutput)
	Request to set fullscreen mode. More...
virtual void	unsetFullscreenRequest ()
	Request to unset fullscreen mode. More...
virtual void	setMinimizedRequest ()
	Minimize request. More...
virtual void	unsetMinimizedRequest ()
	Unminimize request. More...
virtual void	closeRequest ()
	Close request. More...
virtual bool	foreignControllerFilter (Protocols::ForeignToplevelManagement::GForeignToplevelManager *manager)
	Foreign toplevel controller filter. More...
virtual bool	foreignHandleFilter (Protocols::ForeignToplevelList::GForeignToplevelList *foreignList)
	Filter for foreign toplevel handle requests. More...
virtual void	showWindowMenuRequest (const LEvent &triggeringEvent, Int32 x, Int32 y)
	Show window menu request. More...
virtual void	titleChanged ()
	Notifies a change in the title string. More...
virtual void	appIdChanged ()
	Notifies a change in the App ID string. More...
virtual void	preferredDecorationModeChanged ()
	Notifies the client has changed its preferred decoration mode. 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...
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

Toplevel role for surfaces.

The toplevel surface role represents typical desktop windows that usually have a title and buttons to close, minimize, and maximize.

The toplevel role is part of the XDG Shell protocol.

Note

The Wayland protocol also provides its own toplevel role but it is considered obsolete and therefore not included in Louvre.

Configuration

When a client wants to map an LToplevelRole surface, it triggers a configureRequest(), where the compositor is expected to define the size, state, bounds, and other properties of the toplevel using different configure methods, such as configureSize(), configureState(), configureBounds(), etc.

The configuration is not applied immediately, the compositor must wait for the client to ACK the changes through the atomsChanged() event which is also triggered whenever one or more properties of the atoms() struct change, allowing to access previous values as well.

Note

The compositor can configure any parameters at any time, but should always wait for the atomsChanged() event to detect when they are actually applied.

State Change Requests

Depending on the flags set with configureCapabilities(), clients can request to minimize or change the state() of the toplevel to Maximized or Fullscreen through setMinimizedRequest(), set / unsetMaximizedRequest() and set / unsetFullscreenRequest(). The compositor is then expected to minimize or properly configure the state and size, but it's free to ignore the requests if desired.

Note

Minimized is not a toplevel State and can be applied immediately.

Foreign Toplevel Controllers and XDG Activation Tokens

Requests, including those previously mentioned as well as unsetMinimizedRequest(), activateRequest(), and closeRequest(), can be triggered by external clients through the Wlr Foreign Toplevel Management and the XDG Activation protocols. For a comprehensive understanding of this functionality, please refer to the LForeignToplevelController and LActivationTokenManager classes documentation.

Interactive Sessions

Clients can request to start interactive move and resize sessions through startMoveRequest() and startResizeRequest(). To properly handle such requests, each toplevel has an auxiliary moveSession() and resizeSession() which can handle the request for you and constrain the toplevel to the available geometry of outputs (LOutput::availableGeometry()) or to custom constraints specified by you. These are simply auxiliary and you are free to not use them if desired.

Decorations

By default, all clients draw their own decorations on the toplevel surface, such as shadows, and the windowGeometry() property indicates which part of the surface are decorations and which are the actual window content.

Some clients also supportServerSideDecorations() (SSD). To enable SSD, the compositor must send a configureDecorationMode() with the ServerSide value.
When the decorationMode() changes to ServerSide, the client does not draw any decorations, and the windowGeometry() equals the entire surface size.
If the compositor draws additional elements that are meant to be part of the geometry (such as a title bar), the setExtraGeometry() method can be employed, which allows for proper positioning of the toplevel and constraining it during interactive sessions.

Positioning

The toplevel position can be set with LSurface::setPos(). The default implementation of rolePos() then returns the given position minus the decoration part of windowGeometry() and adds the top and left margins of extraGeometry().

---

Class Documentation

Louvre::LToplevelRole::Atoms

struct Louvre::LToplevelRole::Atoms

Atomic properties.

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

See also

atoms()

Class Members
LBitset< State >	state	LToplevelRole::state()
LRect	windowGeometry	LToplevelRole::windowGeometry()
LSize	minSize	LToplevelRole::minSize()
LSize	maxSize	LToplevelRole::maxSize()
LSize	bounds	LToplevelRole::bounds()
LBitset< Capabilities >	capabilities	LToplevelRole::capabilities()
DecorationMode	decorationMode	LToplevelRole::decorationMode()
UInt32	serial	LToplevelRole::serial()

Louvre::LToplevelRole::Configuration

struct Louvre::LToplevelRole::Configuration

Configuration parameters sent to the client.

See also

pendingConfiguration()

findConfiguration()

Class Members
LBitset< State >	state	See also LToplevelRole::state() and configureState()
LSize	size	Size of the toplevel without decorations See also windowGeometry() and configureSize()
LSize	bounds	See also LToplevelRole::bounds() and configureBounds()
LBitset< Capabilities >	capabilities	See also LToplevelRole::capabilities() and configureCapabilities()
DecorationMode	decorationMode	See also LToplevelRole::decorationMode() and configureDecorationMode()
UInt32	serial	See also LToplevelRole::serial() and pendingConfiguration()

Member Enumeration Documentation

State

enum State : UInt16

Flags indicating the possible states of a Toplevel.

Enumerator
NoState	No state.
Maximized	Maximized.
Fullscreen	Fullscreen mode.
Resizing	In interactive resizing.
Activated	Activated (its decorations stand out from others) Only a single toplevel can be activated at a time. This is automatically handled by Louvre. See also LSeat::activeToplevel()
TiledLeft	Tiled left (since 2)
TiledRight	Tiled right (since 2)
TiledTop	Tiled top (since 2)
TiledBottom	Tiled bottom (since 2)
Suspended	Suspended (since 6)

DecorationMode

enum DecorationMode : UInt32

Decoration mode.

Enumerator
NoPreferredMode	The client has no preferred mode.
ClientSide	Decorations are drawn by the client.
ServerSide	Decorations are drawn by the compositor.

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.
MinSizeChanged	Indicates minSize() changed.
MaxSizeChanged	Indicates maxSize() changed.
StateChanged	Indicates state() changed.
BoundsChanged	Indicates bounds() changed.
CapabilitiesChanged	Indicates capabilities() changed.
DecorationModeChanged	Indicates decorationMode() changed.
SerialChanged	Indicates serial() changed.

Capabilities

enum Capabilities : UInt8

Compositor capabilities flags.

Flags indicating supported compositor features, notified to the client through the configureCapabilities() method.

Enumerator
WindowMenuCap	When set, the toplevel can trigger showWindowMenuRequest().
MaximizeCap	When set, the toplevel can trigger setMaximizedRequest() and unsetMaximizedRequest().
FullscreenCap	When set, the toplevel can trigger setFullscreenRequest() and unsetFullscreenRequest().
MinimizeCap	When set, the toplevel can trigger setMinimizedRequest().

Constructor & Destructor Documentation

LToplevelRole()

LToplevelRole ( const void *  params )

noexcept

Constructor of the LToplevelRole class.

Parameters

params

Internal parameters provided in LCompositor::createObjectRequest().

~LToplevelRole()

~LToplevelRole ( )

default

Destructor of the LToplevelRole class.

Invoked after LCompositor::onAnticipatedObjectDestruction().

Member Function Documentation

findConfiguration()

const LToplevelRole::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 configureState(), configureSize(), configureBounds(), etc.

The pending configuration parameters are sent to the client once per Louvre main loop iteration only if one of the configure variants was called.

The pending serial is 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.

configureState()

void configureState ( LBitset< State >  flags )

inlinenoexcept

Configure the toplevel state.

Asks the client to configure the toplevel with the given states and stores the flags in pendingConfiguration().
The state is not applied immediately, see atomsChanged() and state().

Note

A client may not support all states, in such cases unsupported states are filtered out. See supportedStates().

Parameters

flags

The state flags to set.

configureSize() [1/2]

void configureSize ( const LSize &  size )

inlinenoexcept

Configure the toplevel size.

Asks the client to configure the toplevel with the given size and stores it in pendingConfiguration().
The size is not applied immediately, see atomsChanged() and windowGeometry().

Parameters

size	The size is in surface coordinates and does not include decorations. If either width or height is 0, the client is free to pick its own size.

configureSize() [2/2]

void configureSize ( Int32  width, Int32  height  )

inlinenoexcept

Configure the toplevel size.

See also

configureSize()

configureDecorationMode()

void configureDecorationMode ( DecorationMode  mode )

inlinenoexcept

Configure the toplevel decoration mode.

Asks the client to configure the toplevel with the given decoration mode and stores it in pendingConfiguration().
The decoration mode is not applied immediately, see atomsChanged() and decorationMode().

Note

The decoration mode is ClientSide by default. If a client doesn't support ServerSide decorations, the configuration mode will fallback to ClientSide. See supportServerSideDecorations().

See also

preferredDecorationMode()

Parameters

mode	The decoration mode.

configureCapabilities()

void configureCapabilities ( LBitset< Capabilities >  caps )

inlinenoexcept

Notifies the toplevel about the compositor's capabilities.

Informs the toplevel which Capabilities are supported by the compositor and stores them in pendingConfiguration().
For example, if the MaximizeCap is not available, clients should hide the maximize button in their decorations. Additionally, requests such as setMaximizedRequest() and unsetMaximizedRequest() will not be triggered.

The capabilities are not applied immediately, see atomsChanged() and capabilities().

All capabilities are enabled by default.

Note

Some poorly behaved clients, such as Firefox, always expect the compositor to obey their requests and freeze when it does not. In such cases, it is better to leave MaximizeCap and FullscreenCap enabled.

Parameters

caps	The supported Capabilities flags.

configureBounds() [1/2]

void configureBounds ( const LSize &  bounds )

inlinenoexcept

Asks the client to constrain its size to the specified bounds.

Requests the client to prevent assigning a size to the toplevel surface larger than the given bounds, for example, to prevent exceeding the available geometry of an output.

The bounds are stored in pendingConfiguration() and not applied immediately, see atomsChanged() and bounds().

Note

This is merely a suggestion, clients are free to ignore it.

Parameters

bounds

The suggested maximum size. Setting a component to 0 disables the constraint for that component.

configureBounds() [2/2]

void configureBounds ( Int32  width, Int32  height  )

inlinenoexcept

Asks the client to constrain its size to the specified bounds.

See also

configureBounds()

atoms()

const Atoms& atoms ( ) const

inlinenoexcept

Current atomic properties.

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

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

state()

LBitset<State> state ( ) const

inlinenoexcept

Current toplevel state.

Flags representing the current toplevel State.

The state flags can also be checked via aliases such as activated(), maximized(), fullscreen(), etc.

See also

configureState().

Note

This is an alias for Atoms::state.

supportedStates()

LBitset<State> supportedStates ( ) const

inlinenoexcept

Returns the states supported by the toplevel.

• Activated, Maximized , Fullscreen , and Resizing are always supported.
• If any of the tiled states is supported, all are supported.
• The Suspended state support is independent of other states.

Returns

A bitset representing the supported states.

activated()

bool activated ( ) const

inlinenoexcept

Checks if the toplevel state() includes the Activated flag.

Returns

true if the flag is present, false otherwise.

maximized()

bool maximized ( ) const

inlinenoexcept

Checks if the toplevel state() includes the Maximized flag.

Returns

true if the flag is present, false otherwise.

fullscreen()

bool fullscreen ( ) const

inlinenoexcept

Checks if the toplevel state() includes the Fullscreen flag.

Returns

true if the flag is present, false otherwise.

tiled()

bool tiled ( ) const

inlinenoexcept

Checks if the toplevel state() includes any of the tiled flags.

Returns

true if any tiled flag is present, false otherwise.

resizing()

bool resizing ( ) const

inlinenoexcept

Checks if the toplevel state() includes the Resizing flag.

Returns

true if the flag is present, false otherwise.

suspended()

bool suspended ( ) const

inlinenoexcept

Checks if the toplevel state() includes the Suspended flag.

Returns

true if the flag is present, false otherwise.

windowGeometry()

const LRect& windowGeometry ( ) const

inlinenoexcept

Window geometry in surface coordinates.

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

Note

This is an alias for Atoms::windowGeometry.

setExtraGeometry()

void setExtraGeometry ( const LMargins &  margins )

inlinenoexcept

Sets extra geometry margins.

This optional method allows you to modify the extraGeometry() property, providing additional margins for each toplevel edge to be considered part of the geometry. For example, when using server-side decorations, the compositor could draw a custom title bar or borders that are not part of the client surfaces. This method allows you to define those sizes and avoids the need to override rolePos(), the move and resizing constraints, and other default implementations such as LOutput::geometryChanged().

Note

This does not affect the windowGeometry() property and the functioning of configureSize().

See also

extraGeometry()

Parameters

margins

Left, top, right, bottom margins.

extraGeometry()

const LMargins& extraGeometry ( ) const

inlinenoexcept

Extra geometry margins.

Set to (0,0,0,0) by default.

See also

setExtraGeometry()

minSize()

const LSize& minSize ( ) const

inlinenoexcept

Gets the minimum size of the toplevel in surface coordinates.

Components with a value of 0 indicate the limit is disabled.

maxSize()

const LSize& maxSize ( ) const

inlinenoexcept

Gets the maximum size of the toplevel in surface coordinates.

Components with a value of 0 indicate the limit is disabled.

sizeInRange()

bool sizeInRange ( const LSize &  size ) const

inlinenoexcept

Check if the provided size falls within the range defined by minSize() and maxSize().

Parameters

size	The size to be checked.

Returns

true if the size is within the specified range, false otherwise.

calculateConstraintsFromOutput()

LMargins calculateConstraintsFromOutput ( LOutput *  output, bool  includeExtraGeometry = true  ) const

noexcept

Constraints during move/resize sessions.

Returns the left, top, right, and bottom constraints in global-compositor coordinates during a moveSession() and resizeSession() so that the toplevel stays within the given LOutput::availableGeometry(). See LToplevelMoveSession::setConstraints() and LToplevelResizeSession::setConstraints()

Parameters

includeExtraGeometry

If true, extraGeometry() is considered.

bounds()

const LSize& bounds ( ) const

inlinenoexcept

Current bounds.

Suggested size constraints, notified to the client via configureBounds().

Note

This is an alias for Atoms::bounds.

capabilities()

LBitset<Capabilities> capabilities ( ) const

inlinenoexcept

Current capabilities.

Flags representing the Capabilities supported by the compositor, as notified to the client via configureCapabilities().

Note

This is an alias for Atoms::capabilities.

decorationMode()

DecorationMode decorationMode ( ) const

inlinenoexcept

The current decoration mode.

See also

configureDecorationMode()

atomsChanged()

Note

This is an alias for Atoms::decorationMode.

preferredDecorationMode()

DecorationMode preferredDecorationMode ( ) const

inlinenoexcept

Gets the preferred decoration mode set by the client.

Returns

The preferred decoration mode value.

supportServerSideDecorations()

bool supportServerSideDecorations ( ) const

inlinenoexcept

Check if the toplevel supports server-side decorations.

serial()

UInt32 serial ( ) const

inlinenoexcept

Last configuration serial ACK by the client.

See also

pendingConfiguration().

Note

This is an alias for Atoms::serial.

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 toplevel is positioned while maximized or in fullscreen mode.

The default implementation of LOutput::paintGL() uses this information to prevent displaying the given toplevel 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.

moveSession()

LToplevelMoveSession& moveSession ( ) const

inlinenoexcept

Utility for handling interactive moving sessions.

See also

startMoveRequest()

LSeat::toplevelMoveSessions()

resizeSession()

LToplevelResizeSession& resizeSession ( ) const

inlinenoexcept

Utility for handling interactive resizing sessions.

See also

startResizeRequest()

LSeat::toplevelResizeSessions()

xdgToplevelResource()

RXdgToplevel * xdgToplevelResource

(

)

const

xdg_toplevel resource from the XDG Shell protocol.

xdgSurfaceResource()

RXdgSurface * xdgSurfaceResource

(

)

const

xdg_surface resource from the XDG Shell protocol.

appId()

const std::string& appId ( ) const

inlinenoexcept

Gets the application ID associated with the toplevel window.

See also

appIdChanged()

Returns

A string containing the application ID (e.g., "org.cuarzosoftware.Desk").

title()

const std::string& title ( ) const

inlinenoexcept

Gets the window title of the toplevel.

See also

titleChanged()

Returns

A string representing the window title.

close()

void close ( )

noexcept

Closes the toplevel.

Requests the client to close the toplevel (equivalent to pressing the close button on the window).

Note

The client may choose to ignore this request, or show a dialog to ask the user to save their data, etc.

foreignControllers()

const std::vector<LForeignToplevelController*>& foreignControllers ( ) const

inlinenoexcept

Vector of foreign controllers.

See also

The LForeignToplevelController class for more details.

requesterController()

LForeignToplevelController* requesterController ( ) const

inlinenoexcept

LForeignToplevelController triggering a request.

If this method does not return nullptr during a state-changing request, it means it is being triggered by the specified LForeignToplevelController::client().

See also

LForeignToplevelController class for more details.

foreignHandles()

const std::vector<Protocols::ForeignToplevelList::RForeignToplevelHandle*> foreignHandles ( ) const

inlinenoexcept

Vector of foreign handles.

A vector containing all the handles used by foreign clients to identify this toplevel.

See also

foreignHandleFilter() class for more details.

foreignToplevelListIdentifier()

const std::string& foreignToplevelListIdentifier ( ) const

inlinenoexcept

ID used by foreign clients to identify the toplevel.

This ID is used by foreign clients using the Foreign Toplevel List protocol (see foreignHandleFilter() for details).

The string is initially empty and is updated after the toplevel is mapped or re-mapped.

rolePos()

virtual const LPoint& rolePos ( ) const

overridevirtual

Position of the surface according to the role.

Override this virtual method if you need to define your own logic for positioning the toplevel.

The default implementation returns the position set with LSurface::setPos() minus the decoration part of windowGeometry() and adds the top and left margins of extraGeometry().

Default Implementation

const LPoint &LToplevelRole::rolePos() const
{
    m_rolePos = surface()->pos() - windowGeometry().topLeft() + LPoint(extraGeometry().left, extraGeometry().top);
    return m_rolePos;
}

Implements LBaseSurfaceRole.

configureRequest()

virtual void configureRequest ( )

virtual

Configuration request.

This request is triggered each time the client intends to map the toplevel surface.

Default Implementation

void LToplevelRole::configureRequest()
{
    LOutput *output { cursor()->output() };
 
    if (output)
    {
        surface()->sendOutputEnterEvent(output);
        configureBounds(
            output->availableGeometry().size()
            - LSize(extraGeometry().left + extraGeometry().right, extraGeometry().top + extraGeometry().bottom));
    }
    else
        configureBounds(0, 0);
 
    configureSize(0,0);
    configureState(pendingConfiguration().state | Activated);
    configureDecorationMode(ClientSide);
    configureCapabilities(WindowMenuCap | FullscreenCap | MaximizeCap | MinimizeCap);
}

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 LToplevelRole::atomsChanged(LBitset<AtomChanges> changes, const Atoms &prevAtoms)
{
    surface()->repaintOutputs();
 
    if (!changes.check(StateChanged))
        return;
 
    const LBitset<State> stateChanges { state() ^ prevAtoms.state };
 
    if (stateChanges.check(Maximized))
    {
        if (maximized())
        {
            if (exclusiveOutput())
            {
                surface()->raise();
                surface()->setPos(exclusiveOutput()->pos() + exclusiveOutput()->availableGeometry().pos());
                surface()->setMinimized(false);
            }
            else
            {
                configureSize(0, 0);
                configureState(pendingConfiguration().state & ~Maximized);
            }
        }
        else
        {
            surface()->setPos(prevRect.pos());
        }
    }
 
    if (stateChanges.check(Fullscreen))
    {
        if (fullscreen())
        {
            if (exclusiveOutput())
            {
                surface()->setPos(exclusiveOutput()->pos());
                surface()->raise();
            }
            else
            {
                configureSize(0, 0);
                configureState(pendingConfiguration().state & ~Fullscreen);
            }
        }
        else
        {
            surface()->setPos(prevRect.pos());
        }
    }
 
    if (stateChanges.check(Activated) && activated())
    {
        surface()->setMinimized(false);
        surface()->raise();
    }
 
    if (stateChanges.check(Fullscreen | Maximized) && !pendingConfiguration().state.check(Fullscreen | Maximized))
        setExclusiveOutput(nullptr);
}

startMoveRequest()

virtual void startMoveRequest ( const LEvent &  triggeringEvent )

virtual

Client request to initiate an interactive move session.

The default implementation utilizes the moveSession() utility to handle the session, and ignores it if the toplevel is in Fullscreen mode.

The triggering event helps differentiate whether it is a pointer, touch, or other type of session.

Parameters

triggeringEvent

The event that triggered the move session.

See also

moveSession()

Default Implementation

void LToplevelRole::startMoveRequest(const LEvent &triggeringEvent)
{
    if (fullscreen())
        return;
 
    LOutput *activeOutput { cursor()->output() };
 
    if (triggeringEvent.type() == LEvent::Type::Touch)
    {
        if (triggeringEvent.subtype() != LEvent::Subtype::Down)
            return;
 
        if (!activeOutput)
            return;
 
        const LTouchDownEvent& touchDownEvent { static_cast<const LTouchDownEvent&>(triggeringEvent) };
        LTouchPoint *touchPoint { seat()->touch()->findTouchPoint(touchDownEvent.id()) };
 
        if (!touchPoint)
            return;
 
        if (touchPoint->surface() != surface())
            return;
 
        const LPoint initDragPoint { LTouch::toGlobal(activeOutput, touchPoint->pos()) };
 
        moveSession().start(triggeringEvent, initDragPoint);
    }
    else if (seat()->pointer()->focus()
             && (surface()->hasPointerFocus()
             || (seat()->pointer()->focus()->subsurface() && seat()->pointer()->focus()->isSubchildOf(surface()))))
    {
        moveSession().start(triggeringEvent, cursor()->pos());
    }
}

startResizeRequest()

virtual void startResizeRequest ( const LEvent &  triggeringEvent, LBitset< LEdge >  edge  )

virtual

Client request to initiate an interactive resize session.

The default implementation utilizes the resizeSession() utility to handle the session, and ignores it if the toplevel is in Fullscreen mode.

The triggering event helps differentiate whether it is a pointer, touch, or other type of session.

Parameters

triggeringEvent	The event that triggered the resize session.
edge	The edge or corner being dragged.

See also

resizeSession()

Default Implementation

void LToplevelRole::startResizeRequest(const LEvent &triggeringEvent, LBitset<LEdge> edge)
{
    if (fullscreen())
        return;
 
    LOutput *activeOutput { cursor()->output() };
 
    if (triggeringEvent.type() == LEvent::Type::Touch)
    {
        if (triggeringEvent.subtype() != LEvent::Subtype::Down)
            return;
 
        if (!activeOutput)
            return;
 
        const LTouchDownEvent &touchDownEvent { static_cast<const LTouchDownEvent&>(triggeringEvent) };
        LTouchPoint *touchPoint { seat()->touch()->findTouchPoint(touchDownEvent.id()) };
 
        if (!touchPoint)
            return;
 
        if (touchPoint->surface() != surface())
            return;
 
        const LPoint initDragPoint { LTouch::toGlobal(activeOutput, touchPoint->pos()) };
 
        resizeSession().start(triggeringEvent, edge, initDragPoint);
    }
    else if (seat()->pointer()->focus()
             && (surface()->hasPointerFocus()
                 || (seat()->pointer()->focus()->subsurface() && seat()->pointer()->focus()->isSubchildOf(surface()))))
        resizeSession().start(triggeringEvent, edge, cursor()->pos());
}

activateRequest()

virtual void activateRequest ( )

virtual

Request to activate.

Triggered by a an LActivationTokenManager::token() or requesterController() expecting the compositor to configure the toplevel with the Activated state.

See also

configureState(), requesterController() and LForeignToplevelController.

Note

The compositor is free to ignore this request.

Default Implementation

void LToplevelRole::activateRequest()
{
    /* This request is always triggered by a foreign client or
     * by the default implementation of LActivationTokenManager::activateSurfaceRequest() */
 
    configureState(pendingConfiguration().state | Activated);
}

setMaximizedRequest()

virtual void setMaximizedRequest ( )

virtual

Request to maximize.

Triggered by the client or a requesterController() expecting the compositor to configure the toplevel with the Maximized state. See configureState().

Note

This event is only triggered if the MaximizeCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Default Implementation

void LToplevelRole::setMaximizedRequest()
{
    LOutput *output { cursor()->output() };
 
    if (!output || maximized())
        return;
 
    if (!fullscreen())
        prevRect = LRect(surface()->pos(), windowGeometry().size());
 
    const LSize extraGeoSize {
        extraGeometry().left + extraGeometry().right,
        extraGeometry().top + extraGeometry().bottom };
 
    if (prevRect.area() == 0)
    {
        prevRect.setSize(output->availableGeometry().size() - extraGeoSize);
        prevRect.setPos(output->pos() + output->availableGeometry().pos());
    }
 
    setExclusiveOutput(output);
    configureSize(output->availableGeometry().size() - extraGeoSize);
    configureState(Activated | Maximized);
}

unsetMaximizedRequest()

virtual void unsetMaximizedRequest ( )

virtual

Request to unmaximize.

Triggered by the client or a requesterController() expecting the compositor to configure the toplevel without the Maximized state. See configureState().

Note

This event is only triggered if the MaximizeCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Default implementation

void LToplevelRole::unsetMaximizedRequest()
{
    if (!maximized())
        return;
 
    configureState(pendingConfiguration().state &~ Maximized);
    configureSize(prevRect.size());
}

setFullscreenRequest()

virtual void setFullscreenRequest ( LOutput *  destOutput )

virtual

Request to set fullscreen mode.

Triggered by the client or a requesterController() expecting the compositor to configure the toplevel with the Fullscreen state. See configureState().

Note

This event is only triggered if the FullscreenCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Parameters

destOutput

Output on which the client wishes to display the toplevel. If nullptr the compositor must choose the output.

Default implementation

void LToplevelRole::setFullscreenRequest(LOutput *preferredOutput)
{
    LOutput *output { preferredOutput != nullptr ? preferredOutput : cursor()->output()};
 
    if (!output || fullscreen())
        return;
 
    if (!maximized())
        prevRect = LRect(surface()->pos(), windowGeometry().size());
 
    if (prevRect.area() == 0)
    {
        prevRect.setSize(output->availableGeometry().size() - LSize(extraGeometry().left + extraGeometry().right, extraGeometry().top + extraGeometry().bottom));
        prevRect.setPos(output->pos() + output->availableGeometry().pos());
    }
 
    setExclusiveOutput(output);
    configureSize(output->size());
    configureState(Activated | Fullscreen);
}

unsetFullscreenRequest()

virtual void unsetFullscreenRequest ( )

virtual

Request to unset fullscreen mode.

Triggered by the client or a requesterController() expecting the compositor to configure the toplevel without the Fullscreen state. See configureState().

Note

This event is only triggered if the FullscreenCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Default implementation

void LToplevelRole::unsetFullscreenRequest()
{
    if (!fullscreen())
        return;
 
    configureState(pendingConfiguration().state &~ Fullscreen);
    configureSize(prevRect.size());
}

setMinimizedRequest()

virtual void setMinimizedRequest ( )

virtual

Minimize request.

Triggered by the client or a requesterController() expecting the compositor to minimize the toplevel window.

See also

LSurface::setMinimized(), requesterController() and LForeignToplevelController.

Note

This event is only triggered if the MinimizeCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Default implementation

void LToplevelRole::setMinimizedRequest()
{
    configureState(pendingConfiguration().state & ~Activated);
    surface()->setMinimized(true);
 
    if (surface()->hasPointerFocus())
        seat()->pointer()->setFocus(nullptr);
 
    if (surface()->hasKeyboardFocus())
        seat()->keyboard()->setFocus(nullptr);
 
    moveSession().stop();
    resizeSession().stop();
}

unsetMinimizedRequest()

virtual void unsetMinimizedRequest ( )

virtual

Unminimize request.

Triggered by a requesterController() expecting the compositor to unminimize the toplevel window.

See also

LSurface::setMinimized(), requesterController() and LForeignToplevelController.

Note

This event is only triggered if the MinimizeCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Default implementation

void LToplevelRole::unsetMinimizedRequest()
{
    /* This request is always triggered by a foreign client */
 
    surface()->setMinimized(false);
}

closeRequest()

virtual void closeRequest ( )

virtual

Close request.

Triggered by a requesterController() expecting the compositor to close() the toplevel window.

See also

close(), requesterController() and LForeignToplevelController.

Note

The compositor is free to ignore this request.

Default implementation

void LToplevelRole::closeRequest()
{
    /* This request is always triggered by a foreign client */
 
    close();
}

foreignControllerFilter()

virtual bool foreignControllerFilter ( Protocols::ForeignToplevelManagement::GForeignToplevelManager *  manager )

virtual

Foreign toplevel controller filter.

This method allows you to filter which foreign clients can control this toplevel. See LForeignToplevelController for more details.

If accepted, a new LForeignToplevelController object will be added to the foreignControllers() vector.

Parameters

manager

The GForeignToplevelManager resource requesting to control the toplevel.

Returns

true to allow the foreign client to control the toplevel, false to deny it.

Default implementation

bool LToplevelRole::foreignControllerFilter(Protocols::ForeignToplevelManagement::GForeignToplevelManager *manager)
{
    L_UNUSED(manager)
 
    /* Allow all foreign clients to control the toplevel */
    return true;
}

foreignHandleFilter()

virtual bool foreignHandleFilter ( Protocols::ForeignToplevelList::GForeignToplevelList *  foreignList )

virtual

Filter for foreign toplevel handle requests.

This method allows you to control which foreign clients can obtain a handle for this toplevel.

The handle enables clients to identify other clients' toplevels and, in conjunction with other protocols, perform operations such as selecting which toplevel to capture using protocols like Image Copy Capture.

If accepted, a new ForeignToplevelList::RForeignToplevelHandle object will be added to the foreignHandles() vector.
Alternatively, you can disable the protocol for specific clients using LCompositor::globalsFilter().

Note

This interface is related to the Foreign Toplevel List protocol. Do not confuse it with the Wlr Foreign Toplevel Management protocol (see foreignControllerFilter()).

This protocol can be tested with clients like lswt.

Parameters

foreignList

The GForeignToplevelList resource requesting to get a handle.

Returns

true to allow the foreign client to obtain a handle for this toplevel, false to deny it.

Default implementation

bool LToplevelRole::foreignHandleFilter(Protocols::ForeignToplevelList::GForeignToplevelList *foreignList)
{
    L_UNUSED(foreignList)
 
    /* Allow all clients to get a handle for this toplevel */
    return true;
}

showWindowMenuRequest()

virtual void showWindowMenuRequest ( const LEvent &  triggeringEvent, Int32  x, Int32  y  )

virtual

Show window menu request.

Triggered by the client expecting the compositor to display a popup menu with options for minimizing, maximizing and/or turning the toplevel into fullscreen mode.

Note

This event is only triggered if the WindowMenuCap is set. See configureCapabilities().

The compositor is free to ignore this request.

Default Implementation

void LToplevelRole::showWindowMenuRequest(const LEvent &triggeringEvent, Int32 x, Int32 y)
{
    L_UNUSED(triggeringEvent);
    L_UNUSED(x);
    L_UNUSED(y);
 
    /* Here the compositor should render a context menu showing
     * the minimize, maximize and fullscreen options */
}

titleChanged()

virtual void titleChanged ( )

virtual

Notifies a change in the title string.

See also

title()

Default Implementation

void LToplevelRole::titleChanged()
{
    /* No default implementation */
}

appIdChanged()

virtual void appIdChanged ( )

virtual

Notifies a change in the App ID string.

See also

appId()

Default Implementation

void LToplevelRole::appIdChanged()
{
    /* No default implementation */
}

preferredDecorationModeChanged()

virtual void preferredDecorationModeChanged ( )

virtual

Notifies the client has changed its preferred decoration mode.

See also

preferredDecorationMode()

Default Implementation

void LToplevelRole::preferredDecorationModeChanged()
{
    /* No default implementation */
}

Member Data Documentation

prevRect

LRect prevRect

Auxiliary previous rect.

This auxiliary rect is used by the default implementation to save the position and size of the toplevel window before it is maximized or switched to fullscreen, allowing it to be restored later.