#include <KoInteractionTool.h>

Inheritance diagram for KoInteractionTool:

Public Member Functions
void	keyPressEvent (QKeyEvent *event) override

void	keyReleaseEvent (QKeyEvent *event) override

	KoInteractionTool (KoCanvasBase *canvas)

void	mouseMoveEvent (KoPointerEvent *event) override

void	mousePressEvent (KoPointerEvent *event) override

void	mouseReleaseEvent (KoPointerEvent *event) override

void	paint (QPainter &painter, const KoViewConverter &converter) override

	~KoInteractionTool () override

Public Member Functions inherited from KoToolBase
QAction *	action (const QString &name) const

KoCanvasBase *	canvas () const
	Returns the canvas the tool is working on.

virtual void	copy () const

QCursor	cursor () const
	return the last emitted cursor

virtual void	customMoveEvent (KoPointerEvent *event)

virtual void	customPressEvent (KoPointerEvent *event)

virtual void	customReleaseEvent (KoPointerEvent *event)

virtual void	cut ()

virtual QRectF	decorationsRect () const

int	decorationThickness () const
	decorationThickness The minimum thickness for tool decoration lines, this is derived from the screen magnification, thus the HiDPI settings. Note: to use this effectively, also set the pen to isCosmetic(true);

virtual void	deleteSelection ()

virtual void	deselect ()
	deselect the tool should clear the selection if it has one.

virtual void	dragLeaveEvent (QDragLeaveEvent *event)

virtual void	dragMoveEvent (QDragMoveEvent *event, const QPointF &point)

virtual void	dropEvent (QDropEvent *event, const QPointF &point)

virtual void	explicitUserStrokeEndRequest ()
	explicitUserStrokeEndRequest is called by the input manager when the user presses Enter key or any equivalent. This callback comes before requestStrokeEnd(), which comes from a different source.

KoToolFactoryBase *	factory () const

virtual void	focusInEvent (QFocusEvent *event)

virtual void	focusOutEvent (QFocusEvent *event)

virtual bool	hasSelection ()

virtual void	inputMethodEvent (QInputMethodEvent *event)

virtual QVariant	inputMethodQuery (Qt::InputMethodQuery query) const

bool	isInTextMode () const

bool	isOpacityPresetMode () const

	KoToolBase (KoCanvasBase *canvas)

bool	maskSyntheticEvents () const

virtual void	mouseDoubleClickEvent (KoPointerEvent *event)

virtual void	mouseTripleClickEvent (KoPointerEvent *event)

QList< QPointer< QWidget > >	optionWidgets ()

virtual bool	paste ()

virtual QMenu *	popupActionsMenu ()

virtual KisPopupWidgetInterface *	popupWidget ()

virtual bool	selectAll ()
	selectAll select all data the tool can select.

virtual KoToolSelection *	selection ()

Q_INVOKABLE QString	toolId () const

virtual bool	wantsAutoScroll () const

	~KoToolBase () override

Protected Member Functions
void	addInteractionFactory (KoInteractionStrategyFactory *factory)

void	cancelCurrentStrategy ()
	Cancels the current strategy and deletes it.

virtual KoInteractionStrategy *	createStrategy (KoPointerEvent *event)=0

KoInteractionStrategy *	createStrategyBase (KoPointerEvent *event)

KoInteractionStrategy *	currentStrategy ()

bool	hasInteractionFactory (const QString &id)

	KoInteractionTool (KoInteractionToolPrivate &dd)

void	removeInteractionFactory (const QString &id)

bool	tryUseCustomCursor ()

Protected Member Functions inherited from KoToolBase
virtual QWidget *	createOptionWidget ()

virtual QList< QPointer< QWidget > >	createOptionWidgets ()

int	grabSensitivity () const
	Convenience function to get the current grab sensitivity.

qreal	handleDocRadius () const

QRectF	handleGrabRect (const QPointF &position) const

QRectF	handlePaintRect (const QPointF &position) const

int	handleRadius () const
	Convenience function to get the current handle radius.

bool	isActivated () const

	KoToolBase (KoToolBasePrivate &dd)

KoPointerEvent *	lastDeliveredPointerEvent () const

void	setAbstractResource (KoAbstractCanvasResourceInterfaceSP abstractResource)

void	setConverter (KoDerivedResourceConverterSP converter)

void	setIsOpacityPresetMode (bool value)

void	setMaskSyntheticEvents (bool value)

void	setTextMode (bool value)

QHash< int, KoAbstractCanvasResourceInterfaceSP >	toolAbstractResources ()

QHash< int, KoDerivedResourceConverterSP >	toolConverters ()

void	useCursor (const QCursor &cursor)

Private Member Functions
	KoInteractionTool (const KoInteractionTool &)

KoInteractionTool &	operator= (const KoInteractionTool &)

Additional Inherited Members
Public Slots inherited from KoToolBase
virtual void	activate (const QSet< KoShape * > &shapes)

virtual void	canvasResourceChanged (int key, const QVariant &res)

virtual void	deactivate ()

virtual void	documentResourceChanged (int key, const QVariant &res)

virtual void	repaintDecorations ()

virtual void	requestRedoDuringStroke ()

virtual void	requestStrokeCancellation ()

virtual void	requestStrokeEnd ()

virtual void	requestUndoDuringStroke ()

void	setStatusText (const QString &statusText)

void	updateOptionsWidgetIcons ()

Signals inherited from KoToolBase
void	activateTool (const QString &id)

void	cursorChanged (const QCursor &cursor)

void	selectionChanged (bool hasSelection)

void	statusTextChanged (const QString &statusText)

void	textModeChanged (bool inTextMode)

Protected Attributes inherited from KoToolBase
KoToolBasePrivate *	d_ptr

Detailed Description

The interaction tool adds to the normal KoToolBase class the concept of strategies as a means to get one tool to have different actions the user can perform using the mouse. Each time the user presses the mouse until she releases the mouse a strategy object will be created, used and discarded. If the usage of a tool fits this pattern you need to inherit from this class instead of the plain KoToolBase and reimplement your createStrategy() method which returns a tool-specific strategy where all the real interaction code is placed. A tool can then become as simple as this;

class MyTool : public KoInteractionTool
{
public:
    MyTool::MyTool(KoCanvasBase *canvas) : KoInteractionTool( canvas ) { }
 
    KoInteractionStrategy *MyTool::createStrategy(KoPointerEvent *event) {
        return new MyStrategy(this, m_canvas, event->point);
    }
};

Whereas your strategy (MyStrategy in the example) will contain the interaction code.

Definition at line 43 of file KoInteractionTool.h.

Constructor & Destructor Documentation

◆ KoInteractionTool() [1/3]

KoInteractionTool::KoInteractionTool ( KoCanvasBase * canvas )

explicit

Constructor for basic interaction tool where user actions are translated and handled by interaction strategies of type KoInteractionStrategy.

Parameters

canvas the canvas this tool will be working for.

Definition at line 20 of file KoInteractionTool.cpp.

    : KoToolBase(*(new KoInteractionToolPrivate(this, canvas)))
{
}

◆ ~KoInteractionTool()

KoInteractionTool::~KoInteractionTool ( )

override

Definition at line 25 of file KoInteractionTool.cpp.

26{

27}

◆ KoInteractionTool() [2/3]

KoInteractionTool::KoInteractionTool ( KoInteractionToolPrivate & dd )

protected

Definition at line 204 of file KoInteractionTool.cpp.

    : KoToolBase(dd)
{
}

◆ KoInteractionTool() [3/3]

KoInteractionTool::KoInteractionTool ( const KoInteractionTool & )

private

Member Function Documentation

◆ addInteractionFactory()

void KoInteractionTool::addInteractionFactory ( KoInteractionStrategyFactory * factory )

protected

Definition at line 149 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
 
    Q_FOREACH (auto f, d->interactionFactories) {
        KIS_SAFE_ASSERT_RECOVER_RETURN(f->id() != factory->id());
    }
 
    d->interactionFactories.append(toQShared(factory));
    std::sort(d->interactionFactories.begin(),
          d->interactionFactories.end(),
          KoInteractionStrategyFactory::compareLess);
}

References KoInteractionStrategyFactory::compareLess(), KoToolBase::factory(), KoToolFactoryBase::id, KIS_SAFE_ASSERT_RECOVER_RETURN, and toQShared().

◆ cancelCurrentStrategy()

void KoInteractionTool::cancelCurrentStrategy ( )

protected

Cancels the current strategy and deletes it.

Definition at line 125 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    if (d->currentStrategy) {
        d->currentStrategy->cancelInteraction();
        delete d->currentStrategy;
        d->currentStrategy = 0;
    }
}

◆ createStrategy()

virtual KoInteractionStrategy * KoInteractionTool::createStrategy ( KoPointerEvent * event )

protectedpure virtual

Implemented in KoZoomTool, and DefaultTool.

◆ createStrategyBase()

KoInteractionStrategy * KoInteractionTool::createStrategyBase ( KoPointerEvent * event )

protected

Reimplement this factory method to create your strategy to be used for mouse interaction.

Returns: a new strategy, or 0 when there is nothing to do.

Definition at line 135 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
 
    Q_FOREACH (KoInteractionStrategyFactorySP factory, d->interactionFactories) {
        KoInteractionStrategy *strategy = factory->createStrategy(event);
        if (strategy) {
            return strategy;
        }
    }
 
    return createStrategy(event);
}

References createStrategy(), and KoToolBase::factory().

◆ currentStrategy()

KoInteractionStrategy * KoInteractionTool::currentStrategy ( )

protected

the strategy that is 'in progress'

Definition at line 119 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    return d->currentStrategy;
}

◆ hasInteractionFactory()

bool KoInteractionTool::hasInteractionFactory ( const QString & id )

protected

Definition at line 178 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
 
    Q_FOREACH (auto f, d->interactionFactories) {
        if (f->id() == id) {
            return true;
        }
    }
 
    return false;
}

◆ keyPressEvent()

void KoInteractionTool::keyPressEvent ( QKeyEvent * event )

overridevirtual

Called when a key is pressed. Implementors should call event->ignore() if they do not actually use the event. Default implementation ignores this event.

Parameters

event state and reason of this key press

Reimplemented from KoToolBase.

Reimplemented in KoZoomTool.

Definition at line 87 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    event->ignore();
    if (d->currentStrategy &&
            (event->key() == Qt::Key_Control ||
             event->key() == Qt::Key_Alt || event->key() == Qt::Key_Shift ||
             event->key() == Qt::Key_Meta)) {
        d->currentStrategy->handleMouseMove(d->lastPoint, event->modifiers());
        event->accept();
    }
}

◆ keyReleaseEvent()

void KoInteractionTool::keyReleaseEvent ( QKeyEvent * event )

overridevirtual

Called when a key is released Implementors should call event->ignore() if they do not actually use the event. Default implementation ignores this event.

Parameters

event state and reason of this key release

Reimplemented from KoToolBase.

Reimplemented in KoZoomTool.

Definition at line 100 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
 
    if (!d->currentStrategy) {
        KoToolBase::keyReleaseEvent(event);
        return;
    }
 
    if (event->key() == Qt::Key_Escape) {
        cancelCurrentStrategy();
        event->accept();
    } else if (event->key() == Qt::Key_Control ||
               event->key() == Qt::Key_Alt || event->key() == Qt::Key_Shift ||
               event->key() == Qt::Key_Meta) {
        d->currentStrategy->handleMouseMove(d->lastPoint, event->modifiers());
    }
}

References cancelCurrentStrategy(), and KoToolBase::keyReleaseEvent().

◆ mouseMoveEvent()

void KoInteractionTool::mouseMoveEvent ( KoPointerEvent * event )

overridevirtual

Called when the mouse or stylus moved over the canvas. Implementors should call event->ignore() if they do not actually use the event.

Parameters

event state and reason of this mouse or stylus move

Implements KoToolBase.

Reimplemented in KoZoomTool.

Definition at line 55 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    d->lastPoint = event->point;
 
    if (d->currentStrategy) {
        d->currentStrategy->handleMouseMove(d->lastPoint, event->modifiers());
    } else {
        Q_FOREACH (KoInteractionStrategyFactorySP factory, d->interactionFactories) {
            // skip the rest of rendering if the factory asks for it
            if (factory->hoverEvent(event)) return;
        }
 
        event->ignore();
    }
}

References KoToolBase::factory(), and KoPointerEvent::modifiers().

◆ mousePressEvent()

void KoInteractionTool::mousePressEvent ( KoPointerEvent * event )

overridevirtual

Called when (one of) the mouse or stylus buttons is pressed. Implementors should call event->ignore() if they do not actually use the event.

Parameters

event state and reason of this mouse or stylus press

Implements KoToolBase.

Definition at line 43 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    if (d->currentStrategy) { // possible if the user presses an extra mouse button
        cancelCurrentStrategy();
        return;
    }
    d->currentStrategy = createStrategyBase(event);
    if (d->currentStrategy == 0)
        event->ignore();
}

References cancelCurrentStrategy(), and createStrategyBase().

◆ mouseReleaseEvent()

void KoInteractionTool::mouseReleaseEvent ( KoPointerEvent * event )

overridevirtual

Called when (one of) the mouse or stylus buttons is released. Implementors should call event->ignore() if they do not actually use the event.

Parameters

event state and reason of this mouse or stylus release

Implements KoToolBase.

Reimplemented in KoZoomTool.

Definition at line 72 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    if (d->currentStrategy) {
        d->currentStrategy->finishInteraction(event->modifiers());
        KUndo2Command *command = d->currentStrategy->createCommand();
        if (command)
            d->canvas->addCommand(command);
        delete d->currentStrategy;
        d->currentStrategy = 0;
        repaintDecorations();
    } else
        event->ignore();
}

References KoPointerEvent::modifiers(), and KoToolBase::repaintDecorations().

◆ operator=()

KoInteractionTool & KoInteractionTool::operator= ( const KoInteractionTool & )

private

◆ paint()

void KoInteractionTool::paint	(	QPainter &	painter,
		const KoViewConverter &	converter )

overridevirtual

Called by the canvas to paint any decorations that the tool deems needed. The painter has the top left of the canvas as its origin.

Parameters

painter	used for painting the shape
converter	to convert between internal and view coordinates.

Implements KoToolBase.

Definition at line 29 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
 
    if (d->currentStrategy) {
        d->currentStrategy->paint(painter, converter);
    } else {
        Q_FOREACH (KoInteractionStrategyFactorySP factory, d->interactionFactories) {
            // skip the rest of rendering if the factory asks for it
            if (factory->paintOnHover(painter, converter)) break;
        }
    }
}

References KoToolBase::factory().

◆ removeInteractionFactory()

void KoInteractionTool::removeInteractionFactory ( const QString & id )

protected

Definition at line 163 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
    QList<KoInteractionStrategyFactorySP>::iterator it =
            d->interactionFactories.begin();
 
    while (it != d->interactionFactories.end()) {
        if ((*it)->id() == id) {
            it = d->interactionFactories.erase(it);
        } else {
            ++it;
        }
    }
}

◆ tryUseCustomCursor()

bool KoInteractionTool::tryUseCustomCursor ( )

protected

Definition at line 191 of file KoInteractionTool.cpp.

{
    Q_D(KoInteractionTool);
 
    Q_FOREACH (auto f, d->interactionFactories) {
        if (f->tryUseCustomCursor()) {
            return true;
        }
    }
 
    return false;
}

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

libs/flake/tools/KoInteractionTool.h
libs/flake/tools/KoInteractionTool.cpp

Public Member Functions

Protected Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ KoInteractionTool() [1/3]

◆ ~KoInteractionTool()

◆ KoInteractionTool() [2/3]

◆ KoInteractionTool() [3/3]

Member Function Documentation

◆ addInteractionFactory()

◆ cancelCurrentStrategy()

◆ createStrategy()

◆ createStrategyBase()

◆ currentStrategy()

◆ hasInteractionFactory()

◆ keyPressEvent()

◆ keyReleaseEvent()

◆ mouseMoveEvent()

◆ mousePressEvent()

◆ mouseReleaseEvent()

◆ operator=()

◆ paint()

◆ removeInteractionFactory()

◆ tryUseCustomCursor()