KoToolFactory Class Reference

A factory for KoTool objects. More...

#include <KoToolFactory.h>

Inheritance diagram for KoToolFactory:

Public Member Functions
	KoToolFactory (QObject *parent, const QString &id, const QString &name)
virtual	~KoToolFactory ()
QString	activationShapeId () const
virtual bool	canCreateTool (KoCanvasBase *canvas) const
virtual KoTool *	createTool (KoCanvasBase *canvas)=0
QString	icon () const
QString	id () const
bool	inputDeviceAgnostic () const
QString	name () const
int	priority () const
void	setShortcut (const KShortcut &shortcut)
KShortcut	shortcut () const
QString	toolTip () const
QString	toolType () const
Static Public Member Functions
static QString	dynamicToolType ()
static QString	mainToolType ()
Protected Member Functions
void	setActivationShapeId (const QString &activationShapeId)
void	setIcon (const QString &iconName)
void	setInputDeviceAgnostic (bool agnostic)
void	setPriority (int newPriority)
void	setToolTip (const QString &tooltip)
void	setToolType (const QString &toolType)

Detailed Description

A factory for KoTool objects.

The baseclass for all tool plugins. Each plugin that ships a KoTool should also ship a factory. That factory will extend this class and set variable data like a toolTip and icon in the constructor of that extending class.

An example usage would be:

class MyToolFactory : public KoToolFactory {
public:
    MyToolFactory(QObject *parent, const QStringList&)
        : KoToolFactory(parent, "MyTool", i18n("My Tool")) {
        setToolTip(i18n("Create object"));
        setToolType("dynamic");
        setPriority(5);
    }
    ~MyToolFactory() {}
    KoTool* createTool(KoCanvasBase *canvas);
};
K_EXPORT_COMPONENT_FACTORY(myLibrary,
     KGenericFactory<MyToolFactory>( "MyTool" ) )

Definition at line 54 of file KoToolFactory.h.

Constructor & Destructor Documentation

KoToolFactory::KoToolFactory	(	QObject *	parent,
		const QString &	id,
		const QString &	name
	)

Create the new factory.

Parameters:

	parent	the parent QObject for memory management usage.
	id	a string that will be used internally for referencing the tool, for example for use by the KoTool::activateTemporary.
	name	the user visible name of the tool this factory creates.

Definition at line 42 of file KoToolFactory.cpp.

KoToolFactory::~KoToolFactory ( ) [virtual]

Definition at line 48 of file KoToolFactory.cpp.

Member Function Documentation

QString KoToolFactory::activationShapeId ( ) const

Return the id of the shape we can process.

This is the shape Id the tool we create is associated with. So a TextTool for a TextShape. In combination with the toolType the following situations can occur;

Type	shapeId	Result
'main'	Foo	Tool will always be visible, but only active when shape with shapeId 'Foo' is in the selection.
'main'	''	Tool will always be visible, but only active when at least one shape is selected
'main'	'flake/always'	Tool will always be visible and enabled.
'main'	'flake/edit'	Tool will be visible no matter which shape is selected (if any), but only be enabled when the current layer is editable.
'dynamic'	Foo	Tool will only be visible when shape with shapeId 'Foo' is in the selection.
'dynamic'	''	Tool will always be visible. We recommend you don't use this one.
'other'	any	similar to the 'dynamic' items, but segmented in its own section.
n/a	/always	An activation shape id ending with '/always' will make the tool always visible and enabled.

See also:: KoShapeFactory::shapeId(); setActivationShapeId()

Returns:: the id of a shape, or an empty string for all shapes.

Definition at line 78 of file KoToolFactory.cpp.

bool KoToolFactory::canCreateTool ( KoCanvasBase * canvas ) const [virtual]

Returns true if this factory will create a tool instance when called with the same canvas in createTool() The default implementation returns true.

Parameters:

canvas

the canvas that the new tool will work on. Should be passed to the constructor of the tool.

Definition at line 133 of file KoToolFactory.cpp.

virtual KoTool* KoToolFactory::createTool ( KoCanvasBase * canvas ) [pure virtual]

Instanciate a new tool.

Parameters:

canvas

the canvas that the new tool will work on. Should be passed to the constructor of the tool.

Returns:: a new KoTool instance, or zero if the tool doesn't want to show up.

See also:: canCreateTool()

Implemented in KoCreatePathToolFactory, KoCreateShapesToolFactory, KoPanToolFactory, KoPathToolFactory, and KoZoomToolFactory.

static QString KoToolFactory::dynamicToolType ( ) [inline, static]

Returns the dynamic toolType Each tool has a toolType which it uses to be grouped in the toolbox.

The predefined areas are main and dynamic. Dynamic tools are hidden until the shape they belong to is activated.

See also:: toolType(); setToolType()

Definition at line 197 of file KoToolFactory.h.

QString KoToolFactory::icon ( ) const

return the basename of the icon for this tool

Returns:: the basename of the icon for this tool

Definition at line 73 of file KoToolFactory.cpp.

QString KoToolFactory::id ( ) const

return the id for the tool this factory creates.

Returns:: the id for the tool this factory creates.

Definition at line 53 of file KoToolFactory.cpp.

bool KoToolFactory::inputDeviceAgnostic ( ) const

Returns if the tools instance this factory creates can be reused between input devices.

Returns:: true when the tool instance can be reused, false if a new instance needs to be created.

Definition at line 128 of file KoToolFactory.cpp.

static QString KoToolFactory::mainToolType ( ) [inline, static]

Returns the main toolType Each tool has a toolType which it uses to be grouped in the toolbox.

The predefined areas are main and dynamic. "main" tools are always shown.

See also:: toolType(); setToolType()

Definition at line 185 of file KoToolFactory.h.

QString KoToolFactory::name ( ) const

return the user visible (and translated) name to be seen by the user.

Returns:: the user visible (and translated) name to be seen by the user.

Definition at line 118 of file KoToolFactory.cpp.

int KoToolFactory::priority ( ) const

Returns The priority of this tool in its section in the toolbox.

Returns:: The priority of this tool.

Definition at line 58 of file KoToolFactory.cpp.

void KoToolFactory::setActivationShapeId ( const QString & activationShapeId ) [protected]

Set the id of the shape we can process.

This is the Id, as passed to the constructor of a KoShapeFactory, that the tool we create is associated with. This means that if a KoTextShape is selected, then all tools that have its id set here will be added to the dynamic part of the toolbox.

Parameters:

activationShapeId

the Id of the shape

See also:: activationShapeId()

Definition at line 88 of file KoToolFactory.cpp.

void KoToolFactory::setIcon ( const QString & iconName ) [protected]

Set an icon to be used in the toolBox.

Parameters:

iconName

the basename (without extension) of the icon

See also:: KIconLoader

Definition at line 103 of file KoToolFactory.cpp.

void KoToolFactory::setInputDeviceAgnostic ( bool agnostic ) [protected]

set if the tools instance this factory creates can be reused between input devices.

There is always at least one instance of a tool per view. KOffice will use this boolean to decide if additionally it should create one instance per input device, like mouse and tablet.

When a user has a mouse and 2 tablet pens it is useful to have one tool per device since each tool can then remember its own selection and its own cursor-position etc. Default value is true.

Parameters:

agnostic

when true the tool instance can be reused, false if a new instance needs to be created.

Definition at line 123 of file KoToolFactory.cpp.

void KoToolFactory::setPriority ( int newPriority ) [protected]

Set the priority of this tool, as it is shown in the toolBox; lower number means it will be show more to the front of the list.

Parameters:

newPriority

the priority

Definition at line 108 of file KoToolFactory.cpp.

void KoToolFactory::setShortcut ( const KShortcut & shortcut )

Set the default shortcut for activation of this tool.

Definition at line 113 of file KoToolFactory.cpp.

void KoToolFactory::setToolTip ( const QString & tooltip ) [protected]

Set the tooltip to be used for this tool.

Parameters:

tooltip

the tooltip

Definition at line 93 of file KoToolFactory.cpp.

void KoToolFactory::setToolType ( const QString & toolType ) [protected]

Set the toolType.

used to group tools in the toolbox

Parameters:

toolType

the toolType

Definition at line 98 of file KoToolFactory.cpp.

KShortcut KoToolFactory::shortcut ( ) const

Return the default keyboard shortcut for activation of this tool (if the shape this tool belongs to is active).

Returns:: the shortcut

Definition at line 83 of file KoToolFactory.cpp.

QString KoToolFactory::toolTip ( ) const

return a translated tooltip Text

Returns:: a translated tooltip Text

Definition at line 68 of file KoToolFactory.cpp.

QString KoToolFactory::toolType ( ) const

returns the type of tool, used to group tools in the toolbox

Returns:: the type of tool

Definition at line 63 of file KoToolFactory.cpp.

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

libs/flake

KoToolFactory Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

libs/flake

API Reference