KoToolManager Class Reference

#include <KoToolManager.h>

Inheritance diagram for KoToolManager:

Public Slots
void	switchBackRequested ()
void	switchInputDeviceRequested (const KoInputDevice &id)
void	switchToolRequested (const QString &id)
void	themeChanged ()

Signals
void	aboutToChangeTool (KoCanvasController *canvas)
void	addedTool (KoToolAction *toolAction, KoCanvasController *canvas)
void	changedCanvas (const KoCanvasBase *canvas)
void	changedStatusText (const QString &statusText)
void	changedTool (KoCanvasController *canvas)
void	createOpacityResource (bool isOpacityPresetMode, KoToolBase *tool)
void	currentLayerChanged (const KoCanvasController *canvas, const KoShapeLayer *layer)
void	inputDeviceChanged (const KoInputDevice &device)
void	textModeChanged (bool text)
void	toolCodesSelected (const QList< QString > &types)
void	toolOptionWidgetsChanged (KoCanvasController *controller, const QList< QPointer< QWidget > > &widgets)

Public Member Functions
KoCanvasController *	activeCanvasController () const
QString	activeToolId () const
	Returns the toolId of the currently active tool.
void	addController (KoCanvasController *controller)
void	attachCanvas (KoCanvasController *controller)
Q_SLOT void	attemptCanvasControllerRemoval (QObject *controller)
void	connectActiveTool ()
CanvasData *	createCanvasData (KoCanvasController *controller, const KoInputDevice &device)
KoToolBase *	createTool (KoCanvasController *controller, KoToolAction *toolAction)
KoInputDevice	currentInputDevice () const
void	currentLayerChanged (const KoShapeLayer *layer)
void	detachCanvas (KoCanvasController *controller)
void	disconnectActiveTool ()
bool	eventFilter (QObject *object, QEvent *event)
void	initializeCurrentToolForCanvas ()
void	initializeToolActions ()
	KoToolManager ()
void	movedFocus (QWidget *from, QWidget *to)
void	postSwitchTool ()
QString	preferredToolForSelection (const QList< KoShape * > &shapes)
KoToolManager::Private *	priv ()
	Private (KoToolManager *qq)
void	registerToolProxy (KoToolProxy *proxy, KoCanvasBase *canvas)
void	removeCanvasController (KoCanvasController *controller)
void	requestToolActivation (KoCanvasController *controller)
	Request tool activation for the given canvas controller.
void	selectionChanged (const QList< KoShape * > &shapes)
void	setAbstractResource (KoAbstractCanvasResourceInterfaceSP abstractResource, KoToolBase *tool)
void	setConverter (KoDerivedResourceConverterSP converter, KoToolBase *tool)
void	setup ()
void	switchBackRequested ()
void	switchCanvasData (CanvasData *cd)
void	switchInputDevice (const KoInputDevice &device)
void	switchTool (const QString &id)
void	switchToolTemporaryRequested (const QString &id)
QList< KoToolAction * >	toolActionList () const
KoToolBase *	toolById (KoCanvasBase *canvas, const QString &id) const
void	updateCursor (const QCursor &cursor)
void	updateToolForProxy ()
	~KoToolManager () override
	~Private ()

Static Public Member Functions
static KoToolManager *	instance ()
	Return the toolmanager singleton.

Public Attributes
CanvasData *	canvasData
QHash< KoCanvasController *, QList< CanvasData * > >	canvasses
KoInputDevice	inputDevice
bool	layerExplicitlyDisabled
QHash< KoCanvasBase *, KoToolProxy * >	proxies
KoToolManager *	q
QList< KoToolAction * >	toolActionList

Private Member Functions
	KoToolManager (const KoToolManager &)
KoToolManager	operator= (const KoToolManager &)
Private Member Functions inherited from Private
	Private (KisCanvas2 *c)

Private Attributes
Private *const	d
Private Attributes inherited from Private
KisCanvas2 *	canvas
int	displayedFrame
int	intendedFrame

Detailed Description

This class manages the activation and deactivation of tools for each input device.

Managing the active tool and switching tool based on various variables.

The state of the toolbox will be the same for all views in the process so practically you can say we have one toolbox per application instance (process). Implementation does not allow one widget to be in more then one view, so we just make sure the toolbox is hidden in not-in-focus views.

The ToolManager is a singleton and will manage all views in all applications that are loaded in this process. This means you will have to register and unregister your view. When creating your new view you should use a KoCanvasController() and register that with the ToolManager like this:

MyGuiWidget::MyGuiWidget() {
    m_canvasController = new KoCanvasController(this);
    m_canvasController->setCanvas(m_canvas);
    KoToolManager::instance()->addControllers(m_canvasController));
}
MyGuiWidget::~MyGuiWidget() {
    KoToolManager::instance()->removeCanvasController(m_canvasController);
}

For a new view that extends KoView all you need to do is implement KoView::createToolBox()

KoToolManager also keeps track of the current tool based on a complex set of conditions and heuristics:

• there is one active tool per KoCanvasController (and there is one KoCanvasController per view, because this is a class with scrollbars and a zoomlevel and so on)
• for every pointing device (determined by the unique id of tablet, or 0 for mice – you may have more than one mouse attached, but Qt cannot distinguish between them, there is an associated tool.
• depending on things like tablet leave/enter proximity, incoming mouse or tablet events and a little timer (that gets stopped when we know what is what), the active pointing device is determined, and the active tool is set accordingly.

Nota bene: if you use KoToolManager and register your canvases with it you no longer have to manually implement methods to route mouse, tablet, key or wheel events to the active tool. In fact, it's no longer interesting to you which tool is active; you can safely route the paint event through KoToolProxy::paint().

(The reason the input events are handled completely by the toolmanager and the paint events not is that, generally speaking, it's okay if the tools get the input events first, but you want to paint your shapes or other canvas stuff first and only then paint the tool stuff.)

Definition at line 127 of file KoToolManager.h.

Constructor & Destructor Documentation

KoToolManager() [1/2]

KoToolManager::KoToolManager

(

)

Definition at line 191 of file KoToolManager.cpp.

    : QObject(),
      d(new Private(this))
{
    connect(QApplication::instance(), SIGNAL(focusChanged(QWidget*,QWidget*)),
            this, SLOT(movedFocus(QWidget*,QWidget*)));
}

References connect(), and movedFocus().

~KoToolManager()

KoToolManager::~KoToolManager ( )

override

Definition at line 199 of file KoToolManager.cpp.

{
    delete d;
}

References d.

KoToolManager() [2/2]

KoToolManager::KoToolManager ( const KoToolManager & )

private

~Private()

KoToolManager::~Private

(

)

Member Function Documentation

aboutToChangeTool

void KoToolManager::aboutToChangeTool ( KoCanvasController * canvas )

signal

Emitted when a new tool is going to override the current tool

Parameters

canvas

the currently active canvas.

activeCanvasController()

KoCanvasController * KoToolManager::activeCanvasController

(

)

const

Returns

the active canvas controller

Definition at line 282 of file KoToolManager.cpp.

{
    if (! d->canvasData) return 0;
    return d->canvasData->canvas;
}

References Private::canvas, and d.

activeToolId()

QString KoToolManager::activeToolId

(

)

const

Returns the toolId of the currently active tool.

Definition at line 344 of file KoToolManager.cpp.

{
    if (!d->canvasData) return QString();
    return d->canvasData->activeToolId;
}

References d.

addController()

void KoToolManager::addController

(

KoCanvasController *

controller

)

Register a new canvas controller

Parameters

controller

the view controller that this toolmanager will manage the tools for

Definition at line 226 of file KoToolManager.cpp.

{
    Q_ASSERT(controller);
    if (d->canvasses.contains(controller))
        return;
    d->setup();
    d->attachCanvas(controller);
    connect(controller->proxyObject, SIGNAL(destroyed(QObject*)), this, SLOT(attemptCanvasControllerRemoval(QObject*)));
    connect(controller->proxyObject, SIGNAL(canvasRemoved(KoCanvasController*)), this, SLOT(detachCanvas(KoCanvasController*)));
    connect(controller->proxyObject, SIGNAL(canvasSet(KoCanvasController*)), this, SLOT(attachCanvas(KoCanvasController*)));
}

References attachCanvas(), attemptCanvasControllerRemoval(), connect(), d, detachCanvas(), and KoCanvasController::proxyObject.

addedTool

void KoToolManager::addedTool ( KoToolAction * toolAction, KoCanvasController * canvas )

signal

emitted whenever a new tool is dynamically added for the given canvas

attachCanvas()

void KoToolManager::attachCanvas

(

KoCanvasController *

controller

)

attemptCanvasControllerRemoval()

void KoToolManager::attemptCanvasControllerRemoval

(

QObject *

controller

)

Attempt to remove a controller. This is automatically called when a controller's proxy object is deleted, and it ensures that the controller is, in fact, removed, even if the creator forgot to do so.

Parameters

controller

the proxy object of the controller to be removed

Definition at line 246 of file KoToolManager.cpp.

{
    KoCanvasControllerProxyObject* controllerActual = qobject_cast<KoCanvasControllerProxyObject*>(controller);
    if (controllerActual) {
        removeCanvasController(controllerActual->canvasController());
    }
}

References KoCanvasControllerProxyObject::canvasController(), and removeCanvasController().

changedCanvas

void KoToolManager::changedCanvas ( const KoCanvasBase * canvas )

signal

Emitted whenever the active canvas changed.

Parameters

canvas

the new activated canvas (might be 0)

changedStatusText

void KoToolManager::changedStatusText ( const QString & statusText )

signal

Emitted whenever the active tool changes the status text.

Parameters

statusText

the new status text

changedTool

void KoToolManager::changedTool ( KoCanvasController * canvas )

signal

Emitted when a new tool was selected or became active.

Parameters

canvas

the currently active canvas.

connectActiveTool()

void KoToolManager::connectActiveTool

(

)

createCanvasData()

CanvasData * KoToolManager::createCanvasData	(	KoCanvasController *	controller,
		const KoInputDevice &	device )

createOpacityResource

void KoToolManager::createOpacityResource ( bool isOpacityPresetMode, KoToolBase * tool )

signal

Emitted to create and store the opacity resource in tool. The opacity is a derived or abstract resource depending on isOpacityPresetMode.

createTool()

KoToolBase * KoToolManager::createTool	(	KoCanvasController *	controller,
		KoToolAction *	toolAction )

currentInputDevice()

KoInputDevice KoToolManager::currentInputDevice

(

)

const

Returns

the currently active pointing device

Definition at line 216 of file KoToolManager.cpp.

{
    return d->inputDevice;
}

References d.

currentLayerChanged [1/2]

void KoToolManager::currentLayerChanged ( const KoCanvasController * canvas, const KoShapeLayer * layer )

signal

Emitted after the current layer changed either its properties or to a new layer.

Parameters

canvas	the currently active canvas.
layer	the layer that is selected.

currentLayerChanged() [2/2]

void KoToolManager::currentLayerChanged

(

const KoShapeLayer *

layer

)

detachCanvas()

void KoToolManager::detachCanvas

(

KoCanvasController *

controller

)

disconnectActiveTool()

void KoToolManager::disconnectActiveTool

(

)

eventFilter()

bool KoToolManager::eventFilter	(	QObject *	object,
		QEvent *	event )

initializeCurrentToolForCanvas()

void KoToolManager::initializeCurrentToolForCanvas

(

)

Definition at line 318 of file KoToolManager.cpp.

{
    KIS_ASSERT_RECOVER_RETURN(d->canvasData);
 
    // make a full reconnect cycle for the currently active tool
    d->disconnectActiveTool();
    d->connectActiveTool();
    d->postSwitchTool();
}

References d, and KIS_ASSERT_RECOVER_RETURN.

initializeToolActions()

void KoToolManager::initializeToolActions

(

)

Initialize actions for switching to tools. The actions will have the text / shortcut as stated by the toolFactory. If the application calls this in their KoView extending class they will have all the benefits from allowing this in the menus and to allow the use to configure the shortcuts used.

Definition at line 221 of file KoToolManager.cpp.

{
    d->setup();
}

References d.

inputDeviceChanged

void KoToolManager::inputDeviceChanged ( const KoInputDevice & device )

signal

Every time a new input device gets used by a tool, this event is emitted.

Parameters

device

the new input device that the user picked up.

instance()

KoToolManager * KoToolManager::instance ( )

static

Return the toolmanager singleton.

Definition at line 339 of file KoToolManager.cpp.

{
    return s_instance;
}

movedFocus()

void KoToolManager::movedFocus	(	QWidget *	from,
		QWidget *	to )

operator=()

KoToolManager KoToolManager::operator= ( const KoToolManager & )

private

postSwitchTool()

void KoToolManager::postSwitchTool

(

)

preferredToolForSelection()

QString KoToolManager::preferredToolForSelection

(

const QList< KoShape * > &

shapes

)

For the list of shapes find out which tool is the highest priority tool that can handle it.

Returns

the toolId for the shapes.

Parameters

shapes

a list of shapes, a selection for example, that is used to look for the tool.

Definition at line 288 of file KoToolManager.cpp.

{
    QSet<QString> shapeTypes;
    Q_FOREACH (KoShape *shape, shapes) {
        shapeTypes << shape->shapeId();
    }
    //KritaUtils::makeContainerUnique(types);
 
    QString toolType = KoInteractionTool_ID;
    int prio = INT_MAX;
    Q_FOREACH (KoToolAction *helper, d->toolActionList) {
        if (helper->priority() >= prio)
            continue;
 
        bool toolWillWork = false;
        foreach (const QString &type, shapeTypes) {
            if (helper->toolFactory()->activationShapeId().split(',').contains(type)) {
                toolWillWork = true;
                break;
            }
        }
 
        if (toolWillWork) {
            toolType = helper->id();
            prio = helper->priority();
        }
    }
    return toolType;
}

References KoToolFactoryBase::activationShapeId(), d, KoToolAction::id(), KoInteractionTool_ID, KoToolAction::priority(), KoShape::shapeId(), and KoToolAction::toolFactory.

priv()

KoToolManager::Private * KoToolManager::priv

(

)

Definition at line 361 of file KoToolManager.cpp.

{
    return d;
}

References d.

Private()

KoToolManager::Private

(

KoToolManager *

qq

)

registerToolProxy()

void KoToolManager::registerToolProxy	(	KoToolProxy *	proxy,
		KoCanvasBase *	canvas )

Whenever a new tool proxy class is instantiated, it will use this method to register itself so the toolManager can update it to the latest active tool.

Parameters

proxy	the proxy to register.
canvas	which canvas the proxy is associated with; whenever a new tool is selected for that canvas, the proxy gets an update.

removeCanvasController()

void KoToolManager::removeCanvasController

(

KoCanvasController *

controller

)

Remove a set of controllers When the controller is no longer used it should be removed so all tools can be deleted and stop eating memory.

Parameters

controller

the controller that is removed

Definition at line 238 of file KoToolManager.cpp.

{
    Q_ASSERT(controller);
    disconnect(controller->proxyObject, SIGNAL(canvasRemoved(KoCanvasController*)), this, SLOT(detachCanvas(KoCanvasController*)));
    disconnect(controller->proxyObject, SIGNAL(canvasSet(KoCanvasController*)), this, SLOT(attachCanvas(KoCanvasController*)));
    d->detachCanvas(controller);
}

References attachCanvas(), d, detachCanvas(), and KoCanvasController::proxyObject.

requestToolActivation()

void KoToolManager::requestToolActivation

(

KoCanvasController *

controller

)

Request tool activation for the given canvas controller.

Definition at line 209 of file KoToolManager.cpp.

{
    if (d->canvasses.contains(controller)) {
        d->switchTool(d->canvasses.value(controller).first()->activeToolId);
    }
}

References d.

selectionChanged()

void KoToolManager::selectionChanged

(

const QList< KoShape * > &

shapes

)

setAbstractResource()

void KoToolManager::setAbstractResource	(	KoAbstractCanvasResourceInterfaceSP	abstractResource,
		KoToolBase *	tool )

Definition at line 355 of file KoToolManager.cpp.

{
    tool->setAbstractResource(abstractResource);
}

References KoToolBase::setAbstractResource().

setConverter()

void KoToolManager::setConverter	(	KoDerivedResourceConverterSP	converter,
		KoToolBase *	tool )

Definition at line 350 of file KoToolManager.cpp.

{
    tool->setConverter(converter);
}

References KoToolBase::setConverter().

setup()

void KoToolManager::setup

(

)

switchBackRequested [1/2]

void KoToolManager::switchBackRequested ( )

slot

Switches to the last tool used just before the current one, if any.

Definition at line 265 of file KoToolManager.cpp.

{
    if (!d->canvasData) return;
    if (d->canvasData->mostRecentTools.isEmpty()) return;
    d->switchTool(d->canvasData->mostRecentTools.first()->toolId());
}

References d.

switchBackRequested() [2/2]

void KoToolManager::switchBackRequested

(

)

switchCanvasData()

void KoToolManager::switchCanvasData

(

CanvasData *

cd

)

switchInputDevice()

void KoToolManager::switchInputDevice

(

const KoInputDevice &

device

)

Request a switch from to the param input device. This will cause the tool for that device to be selected.

switchInputDeviceRequested

void KoToolManager::switchInputDeviceRequested ( const KoInputDevice & id )

slot

Request change input device

Parameters

id	the id of the input device

Definition at line 259 of file KoToolManager.cpp.

{
    if (!d->canvasData) return;
    d->switchInputDevice(id);
}

References d.

switchTool()

void KoToolManager::switchTool

(

const QString &

id

)

switchToolRequested

void KoToolManager::switchToolRequested ( const QString & id )

slot

Request switching tool

Parameters

id	the id of the tool

Definition at line 254 of file KoToolManager.cpp.

{
    d->switchTool(id);
}

References d.

switchToolTemporaryRequested()

void KoToolManager::switchToolTemporaryRequested

(

const QString &

id

)

textModeChanged

void KoToolManager::textModeChanged ( bool text )

signal

Emitted when the tool's text mode has changed.

Parameters

inTextMode

whether it is now in text mode.

themeChanged

void KoToolManager::themeChanged ( )

slot

Notify theme changes

Definition at line 328 of file KoToolManager.cpp.

{
    Q_FOREACH (const QList<CanvasData*> &canvasDataList, d->canvasses) {
        Q_FOREACH (CanvasData *canvasData, canvasDataList) {
            Q_FOREACH (KoToolBase *tool, canvasData->allTools) {
                tool->updateOptionsWidgetIcons();
            }
        }
    }
}

References CanvasData::allTools, canvasData, d, and KoToolBase::updateOptionsWidgetIcons().

toolActionList()

QList< KoToolAction * > KoToolManager::toolActionList

(

)

const

Returns the list of toolActions for the current tools.

Returns

lists of toolActions for the current tools.

toolById()

KoToolBase * KoToolManager::toolById	(	KoCanvasBase *	canvas,
		const QString &	id ) const

Returns the tool for the given tool id. The tool may be 0

Parameters

canvas	the canvas that is a child of a previously registered controller who's tool you want.
id	the tool identifier

See also

addController()

Definition at line 272 of file KoToolManager.cpp.

{
    Q_ASSERT(canvas);
    Q_FOREACH (KoCanvasController *controller, d->canvasses.keys()) {
        if (controller->canvas() == canvas)
            return d->canvasData->allTools.value(id);
    }
    return 0;
}

References KoCanvasController::canvas(), Private::canvas, and d.

toolCodesSelected

void KoToolManager::toolCodesSelected ( const QList< QString > & types )

signal

Emitted after the selection changed to state which unique shape-types are now in the selection.

Parameters

types

a list of string that are the shape types of the selected objects.

toolOptionWidgetsChanged

void KoToolManager::toolOptionWidgetsChanged ( KoCanvasController * controller, const QList< QPointer< QWidget > > & widgets )

signal

Emit the new tool option widgets to be used with this canvas.

updateCursor()

void KoToolManager::updateCursor

(

const QCursor &

cursor

)

updateToolForProxy()

void KoToolManager::updateToolForProxy

(

)

Member Data Documentation

canvasData

CanvasData* KoToolManager::canvasData

Definition at line 81 of file KoToolManager_p.h.

canvasses

QHash<KoCanvasController*, QList<CanvasData*> > KoToolManager::canvasses

Definition at line 78 of file KoToolManager_p.h.

d

Private* const KoToolManager::d

private

Definition at line 313 of file KoToolManager.h.

inputDevice

KoInputDevice KoToolManager::inputDevice

Definition at line 83 of file KoToolManager_p.h.

layerExplicitlyDisabled

bool KoToolManager::layerExplicitlyDisabled

Definition at line 85 of file KoToolManager_p.h.

proxies

QHash<KoCanvasBase*, KoToolProxy*> KoToolManager::proxies

Definition at line 79 of file KoToolManager_p.h.

q

KoToolManager* KoToolManager::q

Definition at line 74 of file KoToolManager_p.h.

toolActionList

QList< KoToolAction * > KoToolManager::toolActionList

Definition at line 76 of file KoToolManager_p.h.

---

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

• libs/flake/KoToolManager.h
• libs/flake/KoToolManager_p.h
• libs/flake/KoToolManager.cpp