LPointer Class Reference

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

#include <LPointer.h>

Inheritance diagram for LPointer:

Public Member Functions
	LPointer (const void *params) noexcept
	LPointer class constructor.
	~LPointer ()
	LPointer class destructor.
LSurface *	focus () const noexcept
	Gets the focused surface.
void	setFocus (LSurface *surface, const LPoint &localPos) noexcept
	Sets the pointer focus.
void	setFocus (LSurface *surface) noexcept
	Sets the pointer focus.
void	setDraggingSurface (LSurface *surface) noexcept
	Keep track of the surface pressed by the main pointer button.
LSurface *	draggingSurface () const noexcept
	Surface being actively pressed by the main pointer button.
LSurface *	surfaceAt (const LPoint &point)
	Looks for a surface at the given position.
const std::vector< LPointerButtonEvent::Button > &	pressedKeys () const noexcept
	Vector of all currently pressed buttons.
bool	isButtonPressed (LPointerButtonEvent::Button button) const noexcept
	Checks if a button is pressed.
void	enableNaturalScrollingX (bool enabled) noexcept
	Toggles natural scrolling for the X axis.
void	enableNaturalScrollingY (bool enabled) noexcept
	Toggles natural scrolling for the Y axis.
bool	naturalScrollingXEnabled () const noexcept
	Checks if natural scrolling is enabled for the X axis.
bool	naturalScrollingYEnabled () const noexcept
	Checks if natural scrolling is enabled for the Y axis.
Public Member Functions inherited from LFactoryObject
Type	factoryObjectType () const noexcept
	Gets the base factory object type.
Public Member Functions inherited from LObject
	LObject (const LObject &) noexcept
	Copy constructor.
LObject &	operator= (const LObject &) noexcept
	Assignment operator (each object has its own individual LWeak reference count).
void	setUserData (UIntPtr data) const noexcept
	Store an unsigned integer value/pointer.
UIntPtr	userData () const noexcept
	Retrieves the stored unsigned integer value/pointer.

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 (const LPointerMoveEvent &event)
	Sends a pointer move event to the currently focused surface.
void	sendButtonEvent (const LPointerButtonEvent &event)
	Sends a pointer button event to the currently focused surface.
void	sendScrollEvent (const LPointerScrollEvent &event)
	Sends a scroll event to the currently focused surface.
void	sendSwipeBeginEvent (const LPointerSwipeBeginEvent &event)
	Sends a swipe begin gesture event to the currently focused surface.
void	sendSwipeUpdateEvent (const LPointerSwipeUpdateEvent &event)
	Sends a swipe update gesture event to the currently focused surface.
void	sendSwipeEndEvent (const LPointerSwipeEndEvent &event)
	Sends a swipe end gesture event to the currently focused surface.
void	sendPinchBeginEvent (const LPointerPinchBeginEvent &event)
	Sends a pinch begin gesture event to the currently focused surface.
void	sendPinchUpdateEvent (const LPointerPinchUpdateEvent &event)
	Sends a pinch update gesture event to the currently focused surface.
void	sendPinchEndEvent (const LPointerPinchEndEvent &event)
	Sends a pinch end gesture event to the currently focused surface.
void	sendHoldBeginEvent (const LPointerHoldBeginEvent &event)
	Sends a hold begin gesture event to the currently focused surface.
void	sendHoldEndEvent (const LPointerHoldEndEvent &event)
	Sends a hold end gesture event to the currently focused surface.

Virtual Methods
virtual void	pointerMoveEvent (const LPointerMoveEvent &event)
	Pointer move event generated by the input backend.
virtual void	pointerButtonEvent (const LPointerButtonEvent &event)
	Pointer button event generated by the input backend.
virtual void	pointerScrollEvent (const LPointerScrollEvent &event)
	Pointer scroll event generated by the input backend.
virtual void	pointerSwipeBeginEvent (const LPointerSwipeBeginEvent &event)
	Pointer swipe begin gesture event generated by the input backend.
virtual void	pointerSwipeUpdateEvent (const LPointerSwipeUpdateEvent &event)
	Pointer swipe update gesture event generated by the input backend.
virtual void	pointerSwipeEndEvent (const LPointerSwipeEndEvent &event)
	Pointer swipe end gesture event generated by the input backend.
virtual void	pointerPinchBeginEvent (const LPointerPinchBeginEvent &event)
	Pointer pinch begin gesture event generated by the input backend.
virtual void	pointerPinchUpdateEvent (const LPointerPinchUpdateEvent &event)
	Pointer pinch update gesture event generated by the input backend.
virtual void	pointerPinchEndEvent (const LPointerPinchEndEvent &event)
	Pointer pinch end gesture event generated by the input backend.
virtual void	pointerHoldBeginEvent (const LPointerHoldBeginEvent &event)
	Pointer hold begin gesture event generated by the input backend.
virtual void	pointerHoldEndEvent (const LPointerHoldEndEvent &event)
	Pointer hold end gesture event generated by the input backend.
virtual void	setCursorRequest (const LClientCursor &clientCursor)
	Set cursor request.

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.
virtual	~LObject () noexcept
	Destructor of the LObject class.
void	notifyDestruction () noexcept
	Notifies the object destruction.

Detailed Description

Class for handling events generated by pointing devices.

The LPointer class allows you to listen to input events generated by devices such as a mouse or touchpad and redirect them to client surfaces. There is 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.
Subsequently, all pointer events sent with any of the sendXXXEvent() methods are directed to the currently focused surface.

Constructor & Destructor Documentation

LPointer()

LPointer ( const void *  params )

noexcept

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::createObjectRequest() virtual constructor.

~LPointer()

~LPointer

(

)

LPointer class destructor.

Invoked after LCompositor::onAnticipatedObjectDestruction().

Member Function Documentation

focus()

LSurface * focus ( ) const

noexcept

Gets the focused surface.

This method returns the surface that has been assigned pointer focus using setFocus().

Note

Only the focused surface can receive pointer events.

Returns

The focused surface, or nullptr if no surface has pointer focus.

setFocus() [1/2]

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

noexcept

Sets the pointer focus.

This method assigns the pointer focus to the specified surface at the given local surface position within the surface.

If another surface already has pointer focus, it will lose it.

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 )

noexcept

Sets the pointer focus.

Sets the pointer focus to the provided surface based on the current LCursor position.

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 )

noexcept

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

This is just a utility 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.

Note

This is unrelated to drag & drop sessions.

Parameters

surface

The surface being pressed or nullptr to unset.

See also

draggingSurface()

draggingSurface()

LSurface * draggingSurface ( ) const

noexcept

Surface being actively pressed by the main pointer button.

This method returns the surface that is currently being actively pressed by the main pointer button.

Returns

The surface being pressed or nullptr.

See also

setDraggingSurface()

surfaceAt()

LSurface * surfaceAt

(

const LPoint &

point

)

Looks for a surface at the given position.

This method looks for the first mapped surface that contains the point given point.
It takes into account the surfaces rolePos(), size(), inputRegion() and the reverse order given by the LCompositor::surfaces() list.

Note

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-global coordinates.

Returns

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

pressedKeys()

const std::vector< LPointerButtonEvent::Button > & pressedKeys ( ) const

noexcept

Vector of all currently pressed buttons.

See also

isButtonPressed()

isButtonPressed()

bool isButtonPressed ( LPointerButtonEvent::Button  button ) const

noexcept

Checks if a button is pressed.

See also

pressedKeys()

enableNaturalScrollingX()

void enableNaturalScrollingX ( bool  enabled )

noexcept

Toggles natural scrolling for the X axis.

Note

This affects the way scroll events are sent to clients via sendPointerScrollEvent(), but not the events received from the input backend through pointerScrollEvent().

Disabled by default. See naturalScrollingXEnabled().

Parameters

enabled

Set to true to enable natural scrolling, or false to disable it.

enableNaturalScrollingY()

void enableNaturalScrollingY ( bool  enabled )

noexcept

Toggles natural scrolling for the Y axis.

Note

This affects the way scroll events are sent to clients via sendPointerScrollEvent(), but not the events received from the input backend through pointerScrollEvent().

Disabled by default. See naturalScrollingYEnabled().

Parameters

enabled

Set to true to enable natural scrolling, or false to disable it.

naturalScrollingXEnabled()

bool naturalScrollingXEnabled ( ) const

noexcept

Checks if natural scrolling is enabled for the X axis.

See also

enableNaturalScrollingX().

naturalScrollingYEnabled()

bool naturalScrollingYEnabled ( ) const

noexcept

Checks if natural scrolling is enabled for the Y axis.

See also

enableNaturalScrollingY().

sendMoveEvent()

void sendMoveEvent

(

const LPointerMoveEvent &

event

)

Sends a pointer move event to the currently focused surface.

Note

To specify the position within the surface modify the mutable LPointerMoveEvent::localPos property.

sendButtonEvent()

void sendButtonEvent

(

const LPointerButtonEvent &

event

)

Sends a pointer button event to the currently focused surface.

sendScrollEvent()

void sendScrollEvent

(

const LPointerScrollEvent &

event

)

Sends a scroll event to the currently focused surface.

See also

enableNaturalScrollingX() and enableNaturalScrollingY().

sendSwipeBeginEvent()

void sendSwipeBeginEvent

(

const LPointerSwipeBeginEvent &

event

)

Sends a swipe begin gesture event to the currently focused surface.

sendSwipeUpdateEvent()

void sendSwipeUpdateEvent

(

const LPointerSwipeUpdateEvent &

event

)

Sends a swipe update gesture event to the currently focused surface.

Note

A sendSwipeBeginEvent() should have been sent before, otherwise this is a no-op.

sendSwipeEndEvent()

void sendSwipeEndEvent

(

const LPointerSwipeEndEvent &

event

)

Sends a swipe end gesture event to the currently focused surface.

Note

A sendSwipeBeginEvent() should have been sent before, otherwise this is a no-op.
This event is automatically sent if a sendSwipeBeginEvent() was sent and the surface lost focus.

sendPinchBeginEvent()

void sendPinchBeginEvent

(

const LPointerPinchBeginEvent &

event

)

Sends a pinch begin gesture event to the currently focused surface.

sendPinchUpdateEvent()

void sendPinchUpdateEvent

(

const LPointerPinchUpdateEvent &

event

)

Sends a pinch update gesture event to the currently focused surface.

Note

A sendPinchBeginEvent() should have been sent before, otherwise this is a no-op.

sendPinchEndEvent()

void sendPinchEndEvent

(

const LPointerPinchEndEvent &

event

)

Sends a pinch end gesture event to the currently focused surface.

Note

A sendPinchBeginEvent() should have been sent before, otherwise this is a no-op.
This event is automatically sent if a sendPinchBeginEvent() was sent and the surface lost focus.

sendHoldBeginEvent()

void sendHoldBeginEvent

(

const LPointerHoldBeginEvent &

event

)

Sends a hold begin gesture event to the currently focused surface.

sendHoldEndEvent()

void sendHoldEndEvent

(

const LPointerHoldEndEvent &

event

)

Sends a hold end gesture event to the currently focused surface.

Note

A sendHoldBeginEvent() should have been sent before, otherwise this is a no-op.
This event is automatically sent if a sendHoldBeginEvent() was sent and the surface lost focus.

pointerMoveEvent()

virtual void pointerMoveEvent ( const LPointerMoveEvent &  event )

virtual

Pointer move event generated by the input backend.

Default Implementation

void LPointer::pointerMoveEvent(const LPointerMoveEvent &event)
{
    // Update the cursor position
    cursor()->move(event.delta().x(), event.delta().y());
 
    bool pointerConstrained { false };
 
    if (focus())
    {
        LPointF fpos { focus()->rolePos() };
 
        // Attempt to enable the pointer constraint mode if the cursor is within the constrained region.
        if (focus()->pointerConstraintMode() != LSurface::PointerConstraintMode::Free)
        {
            if (focus()->pointerConstraintRegion().containsPoint(cursor()->pos() - fpos))
                focus()->enablePointerConstraint(true);
        }
 
        if (focus()->pointerConstraintEnabled())
        {
            if (focus()->pointerConstraintMode() == LSurface::PointerConstraintMode::Lock)
            {
                if (focus()->lockedPointerPosHint().x() >= 0.f)
                    cursor()->setPos(fpos + focus()->lockedPointerPosHint());
                else
                {
                    cursor()->move(-event.delta().x(), -event.delta().y());
 
                    const LPointF closestPoint {
                        focus()->pointerConstraintRegion().closestPointFrom(cursor()->pos() - fpos)
                    };
 
                    cursor()->setPos(fpos + closestPoint);
                }
            }
            else /* Confined */
            {
                const LPointF closestPoint {
                    focus()->pointerConstraintRegion().closestPointFrom(cursor()->pos() - fpos)
                };
 
                cursor()->setPos(fpos + closestPoint);
            }
 
            pointerConstrained = true;
        }
    }
 
    // Schedule repaint on outputs that intersect with the cursor where hardware composition is not supported.
    cursor()->repaintOutputs(true);
 
    const bool sessionLocked { compositor()->sessionLockManager()->state() != LSessionLockManager::Unlocked };
    const bool activeDND { seat()->dnd()->dragging() && seat()->dnd()->triggeringEvent().type() != LEvent::Type::Touch };
 
    if (activeDND)
    {
        if (seat()->dnd()->icon())
        {
            seat()->dnd()->icon()->surface()->setPos(cursor()->pos());
            seat()->dnd()->icon()->surface()->repaintOutputs();
            cursor()->setCursor(seat()->dnd()->icon()->surface()->client()->lastCursorRequest());
        }
 
        seat()->keyboard()->setFocus(nullptr);
        setDraggingSurface(nullptr);
        setFocus(nullptr);
    }
 
    bool activeResizing { false };
 
    for (LToplevelResizeSession *session : seat()->toplevelResizeSessions())
    {
        if (session->triggeringEvent().type() != LEvent::Type::Touch)
        {
            activeResizing = true;
            session->updateDragPoint(cursor()->pos());
        }
    }
 
    if (activeResizing)
        return;
 
    bool activeMoving { false };
 
    for (LToplevelMoveSession *session : seat()->toplevelMoveSessions())
    {
        if (session->triggeringEvent().type() != LEvent::Type::Touch)
        {
            activeMoving = true;
            session->updateDragPoint(cursor()->pos());
            session->toplevel()->surface()->repaintOutputs();
 
            if (session->toplevel()->maximized())
                session->toplevel()->configureState(session->toplevel()->pendingConfiguration().state &~ LToplevelRole::Maximized);
        }
    }
 
    if (activeMoving)
        return;
 
    // If a surface had the left pointer button held down
    if (draggingSurface())
    {
        event.localPos = cursor()->pos() - draggingSurface()->rolePos();
        sendMoveEvent(event);
        return;
    }
 
    // Find the first surface under the cursor
    LSurface *surface { pointerConstrained ? focus() : surfaceAt(cursor()->pos()) };
 
    if (surface)
    {
        if (sessionLocked && surface->client() != sessionLockManager()->client())
            return;
 
        event.localPos = cursor()->pos() - surface->rolePos();
 
        if (activeDND)
        {
            if (seat()->dnd()->focus() == surface)
                seat()->dnd()->sendMoveEvent(event.localPos, event.ms());
            else
                seat()->dnd()->setFocus(surface, event.localPos);
        }
        else
        {
            if (focus() == surface)
                sendMoveEvent(event);
            else
                setFocus(surface, event.localPos);
        }
 
        cursor()->setCursor(surface->client()->lastCursorRequest());
    }
    else
    {
        if (activeDND)
            seat()->dnd()->setFocus(nullptr, LPointF());
        else
        {
            setFocus(nullptr);
            cursor()->useDefault();
            cursor()->setVisible(true);
        }
    }
}

pointerButtonEvent()

virtual void pointerButtonEvent ( const LPointerButtonEvent &  event )

virtual

Pointer button event generated by the input backend.

Default Implementation

void LPointer::pointerButtonEvent(const LPointerButtonEvent &event)
{
    const bool sessionLocked { sessionLockManager()->state() != LSessionLockManager::Unlocked };
    const bool activeDND { seat()->dnd()->dragging() && seat()->dnd()->triggeringEvent().type() != LEvent::Type::Touch };
 
    if (activeDND)
    {
        if (event.state() == LPointerButtonEvent::Released &&
            event.button() == LPointerButtonEvent::Left)
            seat()->dnd()->drop();
 
        seat()->keyboard()->setFocus(nullptr);
        setFocus(nullptr);
        setDraggingSurface(nullptr);
        return;
    }
 
    if (!focus())
    {
        LSurface *surface { surfaceAt(cursor()->pos()) };
 
        if (surface)
        {
            if (sessionLocked && surface->client() != sessionLockManager()->client())
                return;
 
            cursor()->setCursor(surface->client()->lastCursorRequest());
            seat()->keyboard()->setFocus(surface);
            setFocus(surface);
            sendButtonEvent(event);
 
            if (!surface->popup() && !surface->isPopupSubchild())
                seat()->dismissPopups();
        }
        else
        {
            seat()->keyboard()->setFocus(nullptr);
            seat()->dismissPopups();
        }
 
        return;
    }
 
    if (event.button() != LPointerButtonEvent::Left)
    {
        sendButtonEvent(event);
        return;
    }
 
    // Left button pressed
    if (event.state() == LPointerButtonEvent::Pressed)
    {
        // Keep a ref to continue sending it events after the cursor
        // leaves, if the left button remains pressed
        setDraggingSurface(focus());
 
        if (!seat()->keyboard()->focus() || !focus()->isSubchildOf(seat()->keyboard()->focus()))
        {
            seat()->keyboard()->setFocus(focus());
 
            // Pointer focus may have changed within LKeyboard::focusChanged()
            if (!focus())
                return;
        }
 
        sendButtonEvent(event);
 
        if (focus()->toplevel() && !focus()->toplevel()->activated())
            focus()->toplevel()->configureState(focus()->toplevel()->pendingConfiguration().state | LToplevelRole::Activated);
 
        if (!focus()->popup() && !focus()->isPopupSubchild())
            seat()->dismissPopups();
 
        if (!focus() || focus() == compositor()->surfaces().back())
            return;
 
        if (focus()->parent())
            focus()->topmostParent()->raise();
        else
            focus()->raise();
    }
    // Left button released
    else
    {
        sendButtonEvent(event);
 
        // Stop pointer toplevel resizing sessions
        for (auto it = seat()->toplevelResizeSessions().begin(); it != seat()->toplevelResizeSessions().end();)
        {
            if ((*it)->triggeringEvent().type() != LEvent::Type::Touch)
                it = (*it)->stop();
            else
                it++;
        }
 
        // Stop pointer toplevel moving sessions
        for (auto it = seat()->toplevelMoveSessions().begin(); it != seat()->toplevelMoveSessions().end();)
        {
            if ((*it)->triggeringEvent().type() != LEvent::Type::Touch)
                it = (*it)->stop();
            else
                it++;
        }
 
        // We stop sending events to the surface on which the left button was being held down
        setDraggingSurface(nullptr);
 
        if (!focus()->pointerConstraintEnabled() && !focus()->inputRegion().containsPoint(cursor()->pos() - focus()->rolePos()))
        {
            setFocus(nullptr);
            cursor()->useDefault();
            cursor()->setVisible(true);
        }
    }
}

pointerScrollEvent()

virtual void pointerScrollEvent ( const LPointerScrollEvent &  event )

virtual

Pointer scroll event generated by the input backend.

Default Implementation

void LPointer::pointerScrollEvent(const LPointerScrollEvent &event)
{
    sendScrollEvent(event);
}

pointerSwipeBeginEvent()

virtual void pointerSwipeBeginEvent ( const LPointerSwipeBeginEvent &  event )

virtual

Pointer swipe begin gesture event generated by the input backend.

Default Implementation

void LPointer::pointerSwipeBeginEvent(const LPointerSwipeBeginEvent &event)
{
    sendSwipeBeginEvent(event);
}

pointerSwipeUpdateEvent()

virtual void pointerSwipeUpdateEvent ( const LPointerSwipeUpdateEvent &  event )

virtual

Pointer swipe update gesture event generated by the input backend.

Default Implementation

void LPointer::pointerSwipeUpdateEvent(const LPointerSwipeUpdateEvent &event)
{
    sendSwipeUpdateEvent(event);
}

pointerSwipeEndEvent()

virtual void pointerSwipeEndEvent ( const LPointerSwipeEndEvent &  event )

virtual

Pointer swipe end gesture event generated by the input backend.

Default Implementation

void LPointer::pointerSwipeEndEvent(const LPointerSwipeEndEvent &event)
{
    sendSwipeEndEvent(event);
}

pointerPinchBeginEvent()

virtual void pointerPinchBeginEvent ( const LPointerPinchBeginEvent &  event )

virtual

Pointer pinch begin gesture event generated by the input backend.

Default Implementation

void LPointer::pointerPinchBeginEvent(const LPointerPinchBeginEvent &event)
{
    sendPinchBeginEvent(event);
}

pointerPinchUpdateEvent()

virtual void pointerPinchUpdateEvent ( const LPointerPinchUpdateEvent &  event )

virtual

Pointer pinch update gesture event generated by the input backend.

Default Implementation

void LPointer::pointerPinchUpdateEvent(const LPointerPinchUpdateEvent &event)
{
    sendPinchUpdateEvent(event);
}

pointerPinchEndEvent()

virtual void pointerPinchEndEvent ( const LPointerPinchEndEvent &  event )

virtual

Pointer pinch end gesture event generated by the input backend.

Default Implementation

void LPointer::pointerPinchEndEvent(const LPointerPinchEndEvent &event)
{
    sendPinchEndEvent(event);
}

pointerHoldBeginEvent()

virtual void pointerHoldBeginEvent ( const LPointerHoldBeginEvent &  event )

virtual

Pointer hold begin gesture event generated by the input backend.

Default Implementation

void LPointer::pointerHoldBeginEvent(const LPointerHoldBeginEvent &event)
{
    sendHoldBeginEvent(event);
}

pointerHoldEndEvent()

virtual void pointerHoldEndEvent ( const LPointerHoldEndEvent &  event )

virtual

Pointer hold end gesture event generated by the input backend.

Default Implementation

void LPointer::pointerHoldEndEvent(const LPointerHoldEndEvent &event)
{
    sendHoldEndEvent(event);
}

setCursorRequest()

virtual void setCursorRequest ( const LClientCursor &  clientCursor )

virtual

Set cursor request.

Triggered when a client requests to set the cursor texture, hotspot or hide it.

See also

LCursor::setCursor()

LClient::lastCursorRequest().

Default Implementation

void LPointer::setCursorRequest(const LClientCursor &clientCursor)
{
    /* During a non-touch drag & drop session, the source client typically updates the cursor to
     * reflect the DND action (e.g., copy, move, not supported, etc.)
     */
    if (seat()->dnd()->dragging() && seat()->dnd()->triggeringEvent().type() != LEvent::Type::Touch)
    {
        if (seat()->dnd()->origin()->client() == clientCursor.client())
            cursor()->setCursor(clientCursor);
 
        return;
    }
 
    /* Allow the client to set the cursor only if one of its surfaces has pointer focus */
    if (focus() && focus()->client() == clientCursor.client())
        cursor()->setCursor(clientCursor);
}