Base class for surface roles. More...

Inheritance diagram for LBaseSurfaceRole:

Public Types
enum	CommitOrigin
	Commit origin. More...

Public Types inherited from LFactoryObject
enum class	Type : Int32
	Base factory object types. More...

Public Member Functions
	LBaseSurfaceRole (LFactoryObject::Type type, LResource resource, LSurface surface, UInt32 roleId) noexcept
	Constructor of LBaseSurfaceRole class. More...

	~LBaseSurfaceRole ()
	The LBaseSurfaceRole class destructor. More...

virtual const LPoint &	rolePos () const =0
	Position of the surface given its role. More...

virtual LOutput *	exclusiveOutput () const
	The output to which the surface should be constrained. 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...

Protected Member Functions
virtual bool	acceptCommitRequest (CommitOrigin origin)
	Asks if the surface commit should be processed. More...

virtual void	handleSurfaceCommit (CommitOrigin origin)
	Notifies a surface commit. 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
LPoint	m_rolePos
	Variable that stores the surface position given the role. More...

Detailed Description

Base class for surface roles.

A role defines the type and functionality of a surface. Some commonly known roles are LToplevelRole and LPopupRole.

Note: This class is primarily for library maintainers or individuals who wish to implement additional roles beyond those provided by the library.

This class is responsible, among other things, for:

Creating the surface role (returned in LSurface::role()).
Assigning the role's unique ID (returned in LSurface::roleId()).
Assigning the surface position according to the role's protocol (returned in LSurface::rolePos()).
Providing access to native requests of the wl_surface interface.

Creating a Custom Role

The steps for creating a custom role are as follows:

Implement the native protocol interfaces of the role protocol.
Create an LResource wrapper for the role's wl_resource, or use LSurface::surfaceResource() if the role does not have its own wl_resource.
Create a subclass of LBaseSurfaceRole.
Select a unique role ID.
Override the LBaseSurfaceRole::rolePos() method and implement the positioning logic of the role.
Override any other protected methods in LBaseSurfaceRole to handle native requests of the wl_surface interface.

To assign the custom role to a surface at runtime, follow these steps:

Create an instance of your custom LBaseSurfaceRole.
Call the setPendingRole() method (private) on the target surface, passing the custom role instance.
Call the applyPendingRole() method (private) to apply the pending role change. This will trigger the LSurface::roleChanged() event automatically.

By following these steps, you can create a custom role and assign it to a surface dynamically during runtime.

Member Enumeration Documentation

◆ CommitOrigin

enum CommitOrigin

Commit origin.

Enumerator
Itself	The commit is requested by the surface itself.
Parent	The commit is requested by the parent surface.

Constructor & Destructor Documentation

◆ LBaseSurfaceRole()

LBaseSurfaceRole	(	LFactoryObject::Type	type,
		LResource *	resource,
		LSurface *	surface,
		UInt32	roleId
	)

noexcept

Constructor of LBaseSurfaceRole class.

Parameters

resource	Resource granted by the role's protocol interface. If the role does not have a resource, the one accessible with LSurface::surfaceResource() should be passed.
surface	Surface that will acquire the role.
roleId	ID of the role, later accessible with the LSurface::roleId() method. Must be a value greater than 1000.

Note: The ID range [0,1000] is reserved for roles offered by the library.

◆ ~LBaseSurfaceRole()

~LBaseSurfaceRole ( )

The LBaseSurfaceRole class destructor.

Member Function Documentation

◆ rolePos()

virtual const LPoint& rolePos ( ) const

pure virtual

Position of the surface given its role.

This method must return the m_rolePos variable. It should be overridden to return the position of the surface according to the logic given by the role protocol.
The LSurface class returns the position given by this method when calling LSurface::rolePos().

See the default implementation of this method in the roles offered by the library for more information.

Implemented in LToplevelRole, LSubsurfaceRole, LSessionLockRole, LPopupRole, LLayerRole, LDNDIconRole, and LCursorRole.

◆ exclusiveOutput()

virtual LOutput* exclusiveOutput ( ) const

inlinevirtual

The output to which the surface should be constrained.

When this property is set, the surface should be displayed only on the specified output.
Surfaces with the LSessionLockRole or LLayerRole explicitly indicate the output on which the surface should be displayed. This property is also useful for LToplevelRole surfaces when they are maximized or in fullscreen mode.

Note: This is a hint, you may choose to ignore it.

Returns: The output the surface should be constrained to, or nullptr if not constrained to any output.

Reimplemented in LToplevelRole, LSessionLockRole, LPopupRole, and LLayerRole.

◆ roleId()

UInt32 roleId ( ) const

inlinenoexcept

Role ID.

Returns the ID of the role given in the constructor argument. The LSurface class returns this value with the LSurface::roleId() method.

◆ surface()

LSurface* surface ( ) const

inlinenoexcept

Returns the surface that has acquired the role provided in the constructor.

◆ resource()

LResource* resource ( ) const

inline

Returns the Wayland resource for this role given in the constructor.

◆ client()

LClient * client ( ) const

noexcept

Client owner of the surface role.

◆ acceptCommitRequest()

bool acceptCommitRequest ( CommitOrigin origin )

protectedvirtual

Asks if the surface commit should be processed.

The commit is processed only if true is returned.

Parameters

origin Origin of the request. In some protocols the commit is called by other surfaces. For example, surfaces with the subsurface role only accept commits from their parent if they are in synchronous mode.

◆ handleSurfaceCommit()

void handleSurfaceCommit ( CommitOrigin origin )

protectedvirtual

Notifies a surface commit.

Access to the wl_surface::commit request of the surface. It should be used by protocols that require atomic changes via commits.

◆ handleSurfaceBufferAttach()

void handleSurfaceBufferAttach	(	wl_resource *	buffer,
		Int32	x,
		Int32	y
	)

protectedvirtual

Notifies a new surface buffer attachment.

Access to the wl_surface::attach request of the surface.

Parameters

buffer	The Wayland buffer resource.
x	X-coordinate offset.
y	Y-coordinate offset.

◆ handleSurfaceOffset()

void handleSurfaceOffset	(	Int32	x,
		Int32	y
	)

protectedvirtual

Notifies a surface buffer offset change.

Provides access to the offset generated by the wl_surface::attach and wl_surface::offset requests.

◆ handleParentCommit()

void handleParentCommit ( )

protectedvirtual

Notifies a parent surface commit.

Access to the wl_surface::commit request of the parent surface.

◆ handleParentMappingChange()

void handleParentMappingChange ( )

protectedvirtual

Notifies when the mapping state of the parent surface changes.

◆ handleParentChange()

void handleParentChange ( )

protectedvirtual

Notifies when the parent surface changes.

Member Data Documentation

◆ m_rolePos

LPoint m_rolePos

mutableprotected

Variable that stores the surface position given the role.

Variable to store the position of the surface according to its role. It must be assigned and returned in the implementation of the LBaseSurfaceRole::rolePos() method.

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Creating a Custom Role

Member Enumeration Documentation

◆ CommitOrigin

Constructor & Destructor Documentation

◆ LBaseSurfaceRole()

◆ ~LBaseSurfaceRole()

Member Function Documentation

◆ rolePos()

◆ exclusiveOutput()

◆ roleId()

◆ surface()

◆ resource()

◆ client()

◆ acceptCommitRequest()

◆ handleSurfaceCommit()

◆ handleSurfaceBufferAttach()

◆ handleSurfaceOffset()

◆ handleParentCommit()

◆ handleParentMappingChange()

◆ handleParentChange()

Member Data Documentation

◆ m_rolePos