KisTouchHoldEventsPostponer Class Reference

#include <KisTouchHoldEventsPostponer.h>

Inheritance diagram for KisTouchHoldEventsPostponer:

Public Types
enum	State { WaitingForHold , HoldCompleted , HoldCancelled }

Signals
void	sigHoldCompleted ()

Public Member Functions
void	cancelHoldWait ()
	KisTouchHoldEventsPostponer (const KisTouchHoldEventsPostponer &rhs)=delete
	KisTouchHoldEventsPostponer (qreal maxHoldDistance, int holdTimeout)
QVector< QTouchEvent * >	postponedEvents ()
void	pushThrough (QTouchEvent *event)
State	state () const
	~KisTouchHoldEventsPostponer ()

Private Slots
void	slotHoldCompletionTimeout ()

Private Member Functions
void	enqueueEvent (QTouchEvent *event)
bool	qualifyForPostponing (QTouchEvent *event)

Private Attributes
qreal	m_maxHoldDistance {20.0}
QVector< QTouchEvent * >	m_postponedEvents
State	m_state { WaitingForHold }
QTimer	m_timer

Detailed Description

The object to store and manage postponed events while waiting for a touch-hold shortcut to trigger. Currently, it supports single- finger touch actions only.

Usage:

// in the class
std::optional<KisTouchHoldEventsPostponer> postponer;
 
// on action start
postponer.emplace(20, 1000);
 
// on any touch event (including the first)
if (postponer) {
    postponer->pushThrough(event);
    if (postponer->state() == KisTouchHoldEventsPostponer::HoldCancelled) {
        Q_FOREACH (QTouchEvent *event, postponer->postponedEvents()) {
            // ... deliver the event ...
        }
        postponer.reset();
    }
}
 
// on sigHoldCompleted()
QTouchEvent *tiggeringEvent = postponer->postponedEvents().front();
// ... start operation using the very first as the rule ...

Definition at line 47 of file KisTouchHoldEventsPostponer.h.

Member Enumeration Documentation

State

enum KisTouchHoldEventsPostponer::State

Enumerator
WaitingForHold
HoldCompleted	the postponer is still accumulating the events
HoldCancelled	the hold action has been detected, the accumulated events should be dropped and the hold action should be started hold action has been cancelled, the accumulated events should be fired to the consumers

Definition at line 51 of file KisTouchHoldEventsPostponer.h.

               {
        WaitingForHold, 
        HoldCompleted, 
        HoldCancelled 
    };

Constructor & Destructor Documentation

KisTouchHoldEventsPostponer() [1/2]

KisTouchHoldEventsPostponer::KisTouchHoldEventsPostponer	(	qreal	maxHoldDistance,
		int	holdTimeout )

Createa touch-hold postponer with maxHoldDistance used as a threshold for hold/drag and holdTimeout as a timeout to consider the hold operation completed

Definition at line 25 of file KisTouchHoldEventsPostponer.cpp.

    : m_maxHoldDistance(maxHoldDistance)
{
    connect(&m_timer, &QTimer::timeout, this, &KisTouchHoldEventsPostponer::slotHoldCompletionTimeout);
 
    m_timer.setSingleShot(true);
#ifdef Q_OS_WIN
    // on Windows, the coarse timers are too coarse for running is a unitest, so we should
    // switch to a precise one inside unittests; for normal user-facing runs the precision
    // is not necessary
    m_timer.setTimerType(QStandardPaths::isTestModeEnabled() ? Qt::PreciseTimer : Qt::CoarseTimer);
#else
    m_timer.setTimerType(Qt::CoarseTimer);
#endif
    m_timer.setInterval(holdTimeout);
    m_timer.start();
}

References m_timer, and slotHoldCompletionTimeout().

KisTouchHoldEventsPostponer() [2/2]

KisTouchHoldEventsPostponer::KisTouchHoldEventsPostponer ( const KisTouchHoldEventsPostponer & rhs )

delete

~KisTouchHoldEventsPostponer()

KisTouchHoldEventsPostponer::~KisTouchHoldEventsPostponer

(

)

Definition at line 43 of file KisTouchHoldEventsPostponer.cpp.

{
    qDeleteAll(m_postponedEvents);
}

References m_postponedEvents.

Member Function Documentation

cancelHoldWait()

void KisTouchHoldEventsPostponer::cancelHoldWait

(

)

Cancel waiting for a touch hold. The state will transition into HoldCancelled

Definition at line 67 of file KisTouchHoldEventsPostponer.cpp.

{
    m_state = HoldCancelled;
    m_timer.stop();
}

References HoldCancelled, m_state, and m_timer.

enqueueEvent()

void KisTouchHoldEventsPostponer::enqueueEvent ( QTouchEvent * event )

private

Make a clone of the event and add to the queue. Can be removed after we stop supporting Qt5.

Definition at line 107 of file KisTouchHoldEventsPostponer.cpp.

{
#if (QT_VERSION < QT_VERSION_CHECK(6, 0, 0))
    // TODO: change QScopedPointer -> std::unique_ptr
    QScopedPointer<QEvent> clonedTouchEvent;
    KoPointerEvent::copyQtPointerEvent(event, clonedTouchEvent);
    m_postponedEvents.append(static_cast<QTouchEvent *>(clonedTouchEvent.take()));
#else
    m_postponedEvents.append(static_cast<QTouchEvent *>(event->clone()));
#endif
}

References m_postponedEvents.

postponedEvents()

QVector< QTouchEvent * > KisTouchHoldEventsPostponer::postponedEvents

(

)

Returns

the clones of all the postponed events, potentially including the one that caused the cancellation of the hold-wait. The postponer owns all the postponed events.

Definition at line 73 of file KisTouchHoldEventsPostponer.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_NOOP(m_state != WaitingForHold);
    return m_postponedEvents;
}

References KIS_SAFE_ASSERT_RECOVER_NOOP, m_postponedEvents, m_state, and WaitingForHold.

pushThrough()

void KisTouchHoldEventsPostponer::pushThrough

(

QTouchEvent *

event

)

Push a new event through the postponer. The method should be called in WaitingForHold state only. In all other states the postponer is not considered as active anymore.

If event does not qualify as an event for touch-hold, then the state of the postponer will be switched into HoldCancelled, which should be handled by the called on exiting pushThrough().

Note: the event that caused the state transition into HoldCancelled state will still be added to the queue, so that it could be managed uniformely with the rest of the postponed events.

Definition at line 53 of file KisTouchHoldEventsPostponer.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_RETURN(m_state == WaitingForHold);
 
    if (qualifyForPostponing(event)) {
        enqueueEvent(event);
    } else {
        // enqueue the event to make sure it is delivered via
        // the "deliver all the postponed events" mechanism
        enqueueEvent(event);
        cancelHoldWait();
    }
}

References cancelHoldWait(), enqueueEvent(), KIS_SAFE_ASSERT_RECOVER_RETURN, m_state, qualifyForPostponing(), and WaitingForHold.

qualifyForPostponing()

bool KisTouchHoldEventsPostponer::qualifyForPostponing ( QTouchEvent * event )

private

Returns

if event can be considered as a touch-hold event

It is currently hardcoded to support only single-finger touch-holds.

Definition at line 94 of file KisTouchHoldEventsPostponer.cpp.

{
    const int numPressedPoints = KisTouchShortcut::countTouchPoints(event, KisTouchShortcut::pressedOnlyTouchStates());
    if (numPressedPoints > 1)
        return false;
 
    const qreal pressDistance = KisTouchShortcut::touchDragDistance(event, KisTouchShortcut::pressedOnlyTouchStates());
    if (pressDistance > m_maxHoldDistance)
        return false;
 
    return true;
}

References KisTouchShortcut::countTouchPoints(), m_maxHoldDistance, KisTouchShortcut::pressedOnlyTouchStates(), and KisTouchShortcut::touchDragDistance().

sigHoldCompleted

void KisTouchHoldEventsPostponer::sigHoldCompleted ( )

signal

Emitted when the postponed has detected a touch-and-hold action

slotHoldCompletionTimeout

void KisTouchHoldEventsPostponer::slotHoldCompletionTimeout ( )

privateslot

Definition at line 79 of file KisTouchHoldEventsPostponer.cpp.

{
    // it might happen that the timer event has been emitted before
    // a cancellation touch event was delivered, then the timer event
    // may come "late"
    if (m_state != WaitingForHold) {
        // the caller should have processed all the postponed events in this case
        KIS_SAFE_ASSERT_RECOVER_NOOP(m_postponedEvents.isEmpty());
        return;
    }
 
    m_state = HoldCompleted;
    Q_EMIT sigHoldCompleted();
}

References HoldCompleted, KIS_SAFE_ASSERT_RECOVER_NOOP, m_postponedEvents, m_state, sigHoldCompleted(), and WaitingForHold.

state()

KisTouchHoldEventsPostponer::State KisTouchHoldEventsPostponer::state

(

)

const

Returns

the current state of the postponer

Definition at line 48 of file KisTouchHoldEventsPostponer.cpp.

{
    return m_state;
}

References m_state.

Member Data Documentation

m_maxHoldDistance

qreal KisTouchHoldEventsPostponer::m_maxHoldDistance {20.0}

private

Definition at line 125 of file KisTouchHoldEventsPostponer.h.

{20.0} ;

m_postponedEvents

QVector<QTouchEvent*> KisTouchHoldEventsPostponer::m_postponedEvents

private

Definition at line 124 of file KisTouchHoldEventsPostponer.h.

m_state

State KisTouchHoldEventsPostponer::m_state { WaitingForHold }

private

Definition at line 123 of file KisTouchHoldEventsPostponer.h.

{ WaitingForHold };

m_timer

QTimer KisTouchHoldEventsPostponer::m_timer

private

Definition at line 122 of file KisTouchHoldEventsPostponer.h.

---

The documentation for this class was generated from the following files:

• libs/ui/input/KisTouchHoldEventsPostponer.h
• libs/ui/input/KisTouchHoldEventsPostponer.cpp