LPointer Class Reference

#include <LPointer.h>

Class for handling events generated by pointing devices. More...

Detailed Description

Class for handling events generated by pointing devices.

The LPointer class allows you to handle pointer events generated by devices such as a mouse or touchpad.
It provides utility methods for interactive tasks like moving and resizing toplevel surfaces, sending pointer events to client surfaces, and more.
There is always a single instance of LPointer, which can be accessed through LSeat::pointer().

Wayland Events

To send pointer events to clients, you must first assign focus to a surface using one of the setFocus() variants.
This action automatically removes focus from any previously focused surface. Subsequently, all pointer events are directed to the currently focused surface.

Public Types
enum	Button : UInt32
	Pointer buttons. More...
enum	ButtonState : UInt32
	Pointer button states. More...
enum	AxisSource : UInt32
	Source of a scroll event. More...
enum	ResizeEdgeSize : Int32
	Edge constraint when resizing a Toplevel. More...

Public Member Functions
	LPointer (const void *params)
	LPointer class constructor. More...
virtual	~LPointer ()
	LPointer class destructor. More...
LSurface *	focus () const
	Get the surface with pointer focus. More...
void	setFocus (LSurface *surface, const LPoint &localPos)
	Set the pointer focus to a specific surface. More...
void	setFocus (LSurface *surface)
	Set the pointer focus to a specific surface. More...
void	setDraggingSurface (LSurface *surface)
	Keep track of the surface pressed by the left pointer button. More...
LSurface *	draggingSurface () const
	Surface being actively pressed by the left pointer button. More...
LSurface *	surfaceAt (const LPoint &point)
	Look for a surface. More...
LCursorRole *	lastCursorRequest () const
	Retrieve the last LCursorRole provided in the most recent setCursorRequest() call. More...
bool	lastCursorRequestWasHide () const
	Determine if the intention of the most recent setCursorRequest() was to hide the cursor. More...
void	dismissPopups ()
	Close all popups. More...
const std::vector< Button > &	pressedKeys () const
	Vector of pressed buttons. More...
bool	isButtonPressed (Button button) const
	Check if a button is pressed. More...
Client Events
These methods allow you to send pointer events to clients. Note Pointer events are sent to the currently focused surface set with setFocus(). If no surface has focus, calling these methods has no effect.
void	sendMoveEvent ()
	Send a pointer move event to the surface with focus. More...
void	sendMoveEvent (const LPoint &localPos)
	Send a pointer move event to the surface with focus. More...
void	sendButtonEvent (Button button, ButtonState state)
	Send a pointer button event to the surface with focus. More...
void	sendAxisEvent (Float64 axisX, Float64 axisY, Int32 discreteX, Int32 discreteY, AxisSource source)
	Send a scroll event to the focused surface. More...
Interactive Toplevel Resizing
These utility methods simplify the management of interactive toplevel resizing sessions. Note Using these methods is optional. See also LToplevelRole::startResizeRequest() LToplevelRole::geometryChanged()
void	startResizingToplevel (LToplevelRole *toplevel, LToplevelRole::ResizeEdge edge, const LPoint &pointerPos, const LSize &minSize=LSize(0, 0), Int32 L=EdgeDisabled, Int32 T=EdgeDisabled, Int32 R=EdgeDisabled, Int32 B=EdgeDisabled)
	Start an interactive toplevel resizing session. More...
void	updateResizingToplevelSize (const LPoint &pointerPos)
	Update the size of a toplevel during an interactive resizing session. More...
void	updateResizingToplevelPos ()
	Update the position of a toplevel during an interactive resizing session. More...
void	stopResizingToplevel ()
	End an interactive toplevel resizing session. More...
LToplevelRole *	resizingToplevel () const
	Get the current toplevel in an interactive resizing session. More...
Interactive toplevel Movement
These utility methods simplify the management of interactive toplevel moving sessions. Note Using these methods is optional. See also LToplevelRole::startMoveRequest()
void	startMovingToplevel (LToplevelRole *toplevel, const LPoint &pointerPos, Int32 L=EdgeDisabled, Int32 T=EdgeDisabled, Int32 R=EdgeDisabled, Int32 B=EdgeDisabled)
	Initiate an interactive toplevel moving session. More...
void	updateMovingToplevelPos (const LPoint &pointerPos)
	Update the position of a toplevel during an interactive moving session. More...
void	stopMovingToplevel ()
	Conclude an interactive moving session. More...
LToplevelRole *	movingToplevel () const
	Get the toplevel surface involved in an interactive moving session. More...
const LPoint &	movingToplevelInitPos () const
	Retrieve the initial position of a toplevel during an interactive moving session. More...
const LPoint &	movingToplevelInitPointerPos () const
	Retrieve the initial pointer position during a toplevel interactive moving session. More...
Virtual Methods
virtual void	pointerMoveEvent (Float32 x, Float32 y, bool absolute)
	Pointer move event. More...
virtual void	pointerButtonEvent (Button button, ButtonState state)
	Pointer button event. More...
virtual void	pointerAxisEvent (Float64 axisX, Float64 axisY, Int32 discreteX, Int32 discreteY, AxisSource source)
	Pointer scroll event. More...
virtual void	setCursorRequest (LCursorRole *cursorRole)
	Set cursor request. More...
Public Member Functions inherited from LObject
	LObject ()=default
	Constructor of the LObject class. More...
	~LObject ()
	Destructor of the LObject class. More...
std::shared_ptr< const bool >	isAlive () const
	Object's liveness status. More...

Additional Inherited Members
Static Public Member Functions inherited from LObject
static LCompositor *	compositor ()
	Quick access to the global compositor instance. More...
static LSeat *	seat ()
	Quick access to the global seat instance. More...
static LCursor *	cursor ()
	Quick access to the global cursor instance. More...

Member Enumeration Documentation

Button

enum Button : UInt32

Pointer buttons.

Enumeration of common pointer buttons.

You can find the complete list of pointer button codes in the <linux/input-event-codes.h> header.

Enumerator
Left	Left button.
Right	Right button.
Middle	Middle button.
Side	Side button.
Extra	Extra button.
Forward	Forward button.
Back	Back button.
Task	Task button.

ButtonState

enum ButtonState : UInt32

Pointer button states.

Possible states of a pointer button.

Enumerator
Released	Button released.
Pressed	Button pressed.

AxisSource

enum AxisSource : UInt32

Source of a scroll event.

Possible sources of a scroll event.

Enumerator
Wheel	Mouse wheel (discrete)
Finger	Trackpad swipe (continuous)
Continuous	Continuous movement (with unspecified source)
WheelTilt	Side movement of a mouse wheel (since 6)

ResizeEdgeSize

enum ResizeEdgeSize : Int32

Edge constraint when resizing a Toplevel.

Enumerator
EdgeDisabled	Disables the constraint on the specified edge.

Constructor & Destructor Documentation

LPointer()

LPointer

(

const void *

params

)

LPointer class constructor.

There is a single instance of LPointer, which can be accessed from LSeat::pointer().

Parameters

params

Internal library parameters provided in the LCompositor::createPointerRequest() virtual constructor.

~LPointer()

~LPointer ( )

virtual

LPointer class destructor.

Invoked internally by the library after notification of its destruction with LCompositor::destroyPointerRequest().

Member Function Documentation

focus()

LSurface * focus

(

)

const

Get the surface with pointer focus.

This method returns the surface that has been assigned pointer focus using setFocus().
Only surfaces with pointer focus can receive pointer events.

Returns

A pointer to the focused surface, or nullptr if no surface has pointer focus.

setFocus() [1/2]

void setFocus	(	LSurface *	surface,
		const LPoint &	localPos
	)

Set the pointer focus to a specific surface.

This method assigns the pointer focus to the specified surface at the given local surface position within the surface.
If a surface already had pointer focus, it will lose it.

Passing nullptr removes pointer focus from all surfaces.

Parameters

surface	Surface to which the pointer focus will be assigned, or nullptr to remove focus from all surfaces.
localPos	Local position within the surface where the pointer enters.

setFocus() [2/2]

void setFocus

(

LSurface *

surface

)

Set the pointer focus to a specific surface.

This method sets the pointer focus to the provided surface based on the current LCursor position.
If a surface already had pointer focus, it will lose it.

Passing nullptr removes pointer focus from all surfaces.

Note

This method internally transforms the LCursor position to the local coordinates of the focused surface, taking into account the surface's role position.

Parameters

surface

The surface to which you want to assign the pointer focus or nullptr to remove focus from all surfaces.

setDraggingSurface()

void setDraggingSurface

(

LSurface *

surface

)

Keep track of the surface pressed by the left pointer button.

This is just a utility method used by the default LPointer implementation to ensure that pointer focus remains on a surface while it's being actively pressed by the left pointer button, for example, during text selection, even if the pointer moves outside the surface boundaries.
The draggingSurface() property is automatically set to nullptr if the given surface is destroyed.

Note

This method is unrelated to drag & drop sessions.

Parameters

surface

The surface being pressed or nullptr to unset.

See also

draggingSurface()

draggingSurface()

LSurface * draggingSurface

(

)

const

Surface being actively pressed by the left pointer button.

This method returns the surface that is currently being actively pressed by the left pointer button. It is set using the setDraggingSurface() utility method to ensure that pointer focus remains on the surface even if the pointer moves outside its boundaries during interaction.

Returns

The surface being pressed or nullptr.

See also

setDraggingSurface()

surfaceAt()

LSurface * surfaceAt

(

const LPoint &

point

)

Look for a surface.

This method looks for the first mapped surface that contains the point given by the point parameter.
It takes into account the surfaces role position (LSurface::rolePos()), their input region (LSurface::inputRegion()) and the order given by the list of surfaces of the compositor (LCompositor::surfaces()).
Some surface roles do not have an input region such as LCursorRole or LDNDIconRole so these surfaces are always ignored.

Parameters

point

Point in compositor coordinates.

Returns

Returns the first surface that contains the point or nullptr if no surface is found.

lastCursorRequest()

LCursorRole * lastCursorRequest

(

)

const

Retrieve the last LCursorRole provided in the most recent setCursorRequest() call.

If the cursor role has been destroyed or if a client has requested to hide the cursor, this method returns nullptr.

Returns

A pointer to the last LCursorRole, or nullptr if the cursor role has been destroyed or the client requested to hide the cursor.

Note

To distinguish whether the last cursor was destroyed or the request was to hide it, use the lastCursorRequestWasHide() method.

lastCursorRequestWasHide()

bool lastCursorRequestWasHide

(

)

const

Determine if the intention of the most recent setCursorRequest() was to hide the cursor.

This method returns true if the most recent setCursorRequest() was intended to hide the cursor; otherwise, it returns false.

Returns

true if the last cursor request was to hide the cursor; otherwise, false.

dismissPopups()

void dismissPopups

(

)

Close all popups.

This method closes all active Popup surfaces in reverse order of creation.

See also

LPopupRole::sendPopupDoneEvent()

pressedKeys()

const std::vector< LPointer::Button > & pressedKeys

(

)

const

Vector of pressed buttons.

isButtonPressed()

bool isButtonPressed

(

Button

button

)

const

Check if a button is pressed.

sendMoveEvent() [1/2]

void sendMoveEvent

(

)

Send a pointer move event to the surface with focus.

This method sends the current pointer position to the surface with pointer focus.

Note

This method internally transforms the LCursor position to the local coordinates of the focused surface, taking into account the surface's role position.

sendMoveEvent() [2/2]

void sendMoveEvent

(

const LPoint &

localPos

)

Send a pointer move event to the surface with focus.

This method sends the current pointer position, provided as 'localPos', to the surface with pointer focus.

Parameters

localPos

Pointer position relative to the top-left corner of the surface in surface coordinates.

sendButtonEvent()

void sendButtonEvent	(	Button	button,
		ButtonState	state
	)

Send a pointer button event to the surface with focus.

This method sends a pointer button event with the specified 'button' code and 'state' to the surface currently in focus.

Parameters

button	Button code.
state	State of the button.

sendAxisEvent()

void sendAxisEvent	(	Float64	axisX,
		Float64	axisY,
		Int32	discreteX,
		Int32	discreteY,
		AxisSource	source
	)

Send a scroll event to the focused surface.

This method sends a scroll event to the currently focused surface.

Parameters

axisX	The horizontal continous scroll axis value.
axisY	The vertical continous scroll axis value.
discreteX	The discrete horizontal scroll value.
discreteY	The discrete vertical scroll value.
source	The source of the scroll event (one of the values from LPointer::AxisSource).

startResizingToplevel()

void startResizingToplevel	(	LToplevelRole *	toplevel,
		LToplevelRole::ResizeEdge	edge,
		const LPoint &	pointerPos,
		const LSize &	minSize = LSize(0, 0),
		Int32	L = EdgeDisabled,
		Int32	T = EdgeDisabled,
		Int32	R = EdgeDisabled,
		Int32	B = EdgeDisabled
	)

Start an interactive toplevel resizing session.

This method starts an interactive resizing session on a toplevel surface from one of its edges or corners.
You can restrict the space in which the surface expands by defining a rectangle given by the L, T, R, and B values.
If you do not want to restrict an edge, assign its value to LPointer::EdgeDisabled.

To update the position and size of the Toplevel, call updateResizingToplevelSize() when the pointer moves and updateResizingToplevelPos() when the toplevel size changes.
Once finished, call stopResizingToplevel() to end the session.

Note

The session will automatically cease if the toplevel is destroyed.

See also

See an example of its use in LToplevelRole::startResizeRequest().

Parameters

toplevel	Toplevel that will change size.
edge	Edge or corner from which the resizing will be performed.
pointerPos	Current pointer position.
minSize	Minimum toplevel size.
L	Restriction of the left edge.
T	Restriction of the top edge.
R	Restriction of the right edge.
B	Restriction of the bottom edge.

updateResizingToplevelSize()

void updateResizingToplevelSize

(

const LPoint &

pointerPos

)

Update the size of a toplevel during an interactive resizing session.

This method should be called each time the pointer position changes.

Parameters

pointerPos

Current pointer position.

See also

See an example of its use in the default implementation of pointerPosChangeEvent().

updateResizingToplevelPos()

void updateResizingToplevelPos

(

)

Update the position of a toplevel during an interactive resizing session.

This method should be called each time the toplevel size changes.

See also

See an example of its use in the default implementation of LToplevelRole::geometryChanged().

stopResizingToplevel()

void stopResizingToplevel

(

)

End an interactive toplevel resizing session.

This method is used to end the resizing session. Should be used for example when releasing the left pointer button.

See also

See an example of its use in the default implementation of pointerButtonEvent().

resizingToplevel()

LToplevelRole * resizingToplevel

(

)

const

Get the current toplevel in an interactive resizing session.

Returns

A pointer to the current toplevel being resized, or nullptr if there is no active resizing session.

startMovingToplevel()

void startMovingToplevel	(	LToplevelRole *	toplevel,
		const LPoint &	pointerPos,
		Int32	L = EdgeDisabled,
		Int32	T = EdgeDisabled,
		Int32	R = EdgeDisabled,
		Int32	B = EdgeDisabled
	)

Initiate an interactive toplevel moving session.

This method initiates an interactive moving session for a toplevel surface.
You can confine the Toplevel's placement within a rectangle by specifying values for L, T, R, and B.
If you don't wish to restrict any edges, set their values to LPointer::EdgeDisabled.

To update the Toplevel's position, use the updateMovingToplevelPos() method. Once the position change is complete, use the stopMovingToplevel() method to conclude the session.

Note

The session will automatically cease if the toplevel is destroyed.

See also

See an example of its use in LToplevelRole::startMoveRequest().

Parameters

toplevel	The toplevel whose size will change.
pointerPos	Current pointer position.
L	Restriction for the left edge.
T	Restriction for the top edge.
R	Restriction for the right edge.
B	Restriction for the bottom edge.

updateMovingToplevelPos()

void updateMovingToplevelPos

(

const LPoint &

pointerPos

)

Update the position of a toplevel during an interactive moving session.

Call this method when the pointer position changes.

See also

See an example of its usage in the default implementation of pointerPosChangeEvent().

Parameters

pointerPos

The current pointer position.

stopMovingToplevel()

void stopMovingToplevel

(

)

Conclude an interactive moving session.

Use this method to conclude a moving toplevel session, for example, when releasing the left pointer button.

See also

See an example of its usage in the default implementation of pointerButtonEvent().

movingToplevel()

LToplevelRole * movingToplevel

(

)

const

Get the toplevel surface involved in an interactive moving session.

Returns

A pointer to the toplevel surface, or nullptr if there is no ongoing interactive moving session.

movingToplevelInitPos()

const LPoint & movingToplevelInitPos

(

)

const

Retrieve the initial position of a toplevel during an interactive moving session.

This method provides the initial position of a toplevel surface when an interactive moving session begins.

movingToplevelInitPointerPos()

const LPoint & movingToplevelInitPointerPos

(

)

const

Retrieve the initial pointer position during a toplevel interactive moving session.

This method provides the initial pointer position when an interactive moving session of a toplevel surface starts.

pointerMoveEvent()

virtual void pointerMoveEvent ( Float32  x, Float32  y, bool  absolute  )

virtual

Pointer move event.

This virtual method notifies of pointer movement generated by the input backend.
Override this virtual method if you need to be informed when the pointer changes its position.

Parameters

x	The x-component of the new pointer position or delta from its previous position.
y	The y-component of the new pointer position or delta from its previous position.
absolute	If true, the (x, y) values represent absolute coordinates; if false, they are deltas from the previous position.

Default Implementation

void LPointer::pointerMoveEvent(Float32 x, Float32 y, bool absolute)
{
    if (absolute)
        cursor()->setPos(x, y);
    else
        cursor()->move(x, y);
 
    // Repaint outputs that intersect with the cursor if hardware composition is not supported.
    cursor()->repaintOutputs(true);
 
    // Update the drag & drop icon position
    if (seat()->dndManager()->icon())
    {
        seat()->dndManager()->icon()->surface()->setPos(cursor()->pos());
        seat()->dndManager()->icon()->surface()->repaintOutputs();
    }
 
    if (resizingToplevel())
    {
        updateResizingToplevelSize(cursor()->pos());
        return;
    }
 
    if (movingToplevel())
    {
        updateMovingToplevelPos(cursor()->pos());
 
        movingToplevel()->surface()->repaintOutputs();
 
        if (movingToplevel()->maximized())
            movingToplevel()->configure(movingToplevel()->pendingStates() &~ LToplevelRole::Maximized);
 
        return;
    }
 
    // If we are in a drag & drop session, we call setDraggingSurface(nullptr)
    // to prevent the current surface from retaining focus.
    if (seat()->dndManager()->dragging())
        setDraggingSurface(nullptr);
 
    // If a surface had the left pointer button held down
    if (draggingSurface())
    {
        sendMoveEvent();
        return;
    }
 
    // Find the first surface under the cursor
    LSurface *surface { surfaceAt(cursor()->pos()) };
 
    if (surface)
    {
        if (focus() == surface)
            sendMoveEvent();
        else
            setFocus(surface);
    }
    else
    {
        setFocus(nullptr);
        cursor()->useDefault();
        cursor()->setVisible(true);
    }
}

pointerButtonEvent()

virtual void pointerButtonEvent ( Button  button, ButtonState  state  )

virtual

Pointer button event.

This virtual method notifies of a change in the state of a pointer button generated by the input backend.
Override this virtual method if you need to be informed when a pointer button changes its state.

Parameters

button	The code of the pressed button.
state	The state of the button (LPointer::Pressed or LPointer::Released).

Default Implementation

void LPointer::pointerButtonEvent(Button button, ButtonState state)
{
    if (state == Released && button == Left)
        seat()->dndManager()->drop();
 
    if (!focus())
    {
        LSurface *surface { surfaceAt(cursor()->pos()) };
 
        if (surface)
        {
            seat()->keyboard()->setFocus(surface);
            setFocus(surface);
            sendButtonEvent(button, state);
 
            if (!surface->popup())
                dismissPopups();
        }
        else
        {
            seat()->keyboard()->setFocus(nullptr);
            dismissPopups();
        }
 
        return;
    }
 
    sendButtonEvent(button, state);
 
    if (button != Left)
        return;
 
    // Left button pressed
    if (state == Pressed)
    {
        // We save the pointer focus surface to continue sending events to it even when the cursor
        // is outside of it (while the left button is being held down)
        setDraggingSurface(focus());
 
        if (!seat()->keyboard()->focus() || !focus()->isSubchildOf(seat()->keyboard()->focus()))
            seat()->keyboard()->setFocus(focus());
 
        if (focus()->toplevel() && !focus()->toplevel()->activated())
            focus()->toplevel()->configure(focus()->toplevel()->pendingStates() | LToplevelRole::Activated);
 
        if (!focus()->popup())
            dismissPopups();
 
        if (focus() == compositor()->surfaces().back())
            return;
 
        if (focus()->parent())
            focus()->topmostParent()->raise();
        else
            focus()->raise();
    }
    // Left button released
    else
    {
        stopResizingToplevel();
        stopMovingToplevel();
 
        // We stop sending events to the surface on which the left button was being held down
        setDraggingSurface(nullptr);
 
        if (!focus()->inputRegion().containsPoint(cursor()->pos() - focus()->rolePos()))
        {
            setFocus(nullptr);
            cursor()->useDefault();
            cursor()->setVisible(true);
        }
    }
}

pointerAxisEvent()

virtual void pointerAxisEvent ( Float64  axisX, Float64  axisY, Int32  discreteX, Int32  discreteY, AxisSource  source  )

virtual

Pointer scroll event.

This virtual method notifies about a pointer scroll event generated by the input backend.
Override this virtual method if you need to handle scroll events.

Parameters

axisX	The direction and magnitude of the scroll on the x component.
axisY	The direction and magnitude of the scroll on the y component.
discreteX	The discrete scroll step on the x component.
discreteY	The discrete scroll step on the y component.
source	The source of the event.

Default Implementation

void LPointer::pointerAxisEvent(Float64 axisX, Float64 axisY, Int32 discreteX, Int32 discreteY, AxisSource source)
{
    // Invert the scroll axis for natural scrolling
    sendAxisEvent(-axisX, -axisY, -discreteX, -discreteY, source);
}

setCursorRequest()

virtual void setCursorRequest ( LCursorRole *  cursorRole )

virtual

Set cursor request.

This virtual method is triggered when a client requests to set the cursor texture and hotspot or hide it.
If you want to assign the cursor texture as requested by the client, override this method.

Note

Only clients with a focused surface can request to set the cursor texture.

Parameters

cursorRole

Surface role to use as a cursor. If it is nullptr, it indicates that the client wants to hide the cursor.

See also

lastCursorRequest()

lastCursorRequestWasHide()

Default Implementation

void LPointer::setCursorRequest(LCursorRole *cursorRole)
{
    if (cursorRole)
    {
        cursor()->setTextureB(
                    cursorRole->surface()->texture(),
                    cursorRole->hotspotB());
 
        cursor()->setVisible(true);
    }
    // If `nullptr` is provided, it indicates that the client intends to hide the cursor.
    else
        cursor()->setVisible(false);
}