LForeignToplevelController Class Reference

Foreign Toplevel Controller. More...

Inheritance diagram for LForeignToplevelController:

Public Member Functions
	LForeignToplevelController (const void *params) noexcept
	Constructor of the LForeignToplevelController class. More...
	~LForeignToplevelController () noexcept
	Destructor of the LForeignToplevelController class. More...
LClient *	client () const noexcept
	Client controlling the given toplevelRole(). More...
Protocols::ForeignToplevelManagement::RForeignToplevelHandle &	resource () const noexcept
	Wayland resource. More...
LToplevelRole *	toplevelRole () const noexcept
	Toplevel window being controlled. More...
LSurface *	taskbar () const noexcept
	Taskbar surface. More...
const LRect &	taskbarIconRect () const noexcept
	Rectangle within the taskbar where the toplevel is represented. More...
virtual void	taskbarChanged ()
	Notifies that taskbar() and/or taskbarIconRect() changed. 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...

Additional Inherited Members
Public Types inherited from LFactoryObject
enum class	Type : Int32
	Base factory object types. 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...

Detailed Description

Foreign Toplevel Controller.

Clients using the Wlr Foreign Toplevel Management protocol can receive information about all open toplevel windows within the compositor and request to modify their state, such as activating, minimizing, maximizing them, and more.

It is typically used by dock/panel applications to display open windows within a taskbar and control their state.

This class represents a single toplevel being controlled by a specific client using the protocol and provides information such as the controller client(), the toplevelRole() it is controlling, and the taskbar() and taskbarIconRect() properties, which indicate where the toplevelRole() is being represented (e.g., as a tab, icon, etc.) within one of the controller client surfaces (dock, panel, etc).

Note

All LForeignToplevelController objects created for a specific toplevel window can be accessed from LToplevelRole::foreignControllers().

Requests

Clients using this protocol can trigger the following LToplevelRole class requests:

• LToplevelRole::setMaximizedRequest() and LToplevelRole::unsetMaximizedRequest()
• LToplevelRole::setFullscreenRequest() and LToplevelRole::unsetFullscreenRequest()
• LToplevelRole::setMinimizedRequest() and LToplevelRole::unsetMinimizedRequest()
• LToplevelRole::activateRequest() and LToplevelRole::closeRequest()

To distinguish who is triggering a request, LToplevelRole::requesterController() can be employed:

• If LToplevelRole::requesterController() returns nullptr during a request, it means the client owner of the toplevel is triggering it.
• Otherwise, it means the request is triggered by the given LForeignToplevelController client returned by LToplevelRole::requesterController().

Whenever properties of a toplevel, such as its state, title, appId, etc change, Louvre automatically notifies its LToplevelRole::foreignControllers().

Security

For security reasons, a compositor should only allow well-known clients to use this protocol. Check LCompositor::globalsFilter() to see how to accomplish that.

Note

To disable this protocol remove its global from LCompositor::createGlobalsRequest().

There are also two ways to prevent specific toplevels from being controlled. One way is through LToplevelRole::foreignControllerFilter(), and a second way is calling finished() for a specific global resource within LClient::foreignToplevelManagerGlobals(), which prevents the resource from receiving information from newly created toplevels and from controlling them.

Constructor & Destructor Documentation

LForeignToplevelController()

LForeignToplevelController ( const void *  params )

noexcept

Constructor of the LForeignToplevelController class.

Parameters

params

Internal parameters provided in LCompositor::createObjectRequest().

~LForeignToplevelController()

~LForeignToplevelController ( )

noexcept

Destructor of the LForeignToplevelController class.

Invoked after LCompositor::onAnticipatedObjectDestruction().

Member Function Documentation

client()

LClient * client ( ) const

noexcept

Client controlling the given toplevelRole().

resource()

Protocols::ForeignToplevelManagement::RForeignToplevelHandle& resource ( ) const

inlinenoexcept

Wayland resource.

See also

zwlr_foreign_toplevel_handle_v1

toplevelRole()

LToplevelRole * toplevelRole ( ) const

noexcept

Toplevel window being controlled.

Returns

It can return nullptr if the toplevel has been destroyed.

taskbar()

LSurface* taskbar ( ) const

inlinenoexcept

Taskbar surface.

This property, along with taskbarIconRect(), indicates where the toplevelRole() is represented (e.g., as a tab, icon, etc.), which can be utilized, for example, for minimizing animations.

See also

taskbarChanged()

Returns

The surface where the toplevel is being represented, or nullptr if not set.

taskbarIconRect()

const LRect& taskbarIconRect ( ) const

inlinenoexcept

Rectangle within the taskbar where the toplevel is represented.

Defines a rectangle within taskbar(), in surface-local coordinates, where the toplevel is being represented.

See also

taskbarChanged()

Warning

This value is meaningless if taskbar() is nullptr.

taskbarChanged()

virtual void taskbarChanged ( )

virtual

Notifies that taskbar() and/or taskbarIconRect() changed.

Default Implementation

void LForeignToplevelController::taskbarChanged()
{
    /* No default implementation */
}