libs/flake

KoTool Class Reference

Abstract base class for all tools. More...

#include <KoTool.h>

Inheritance diagram for KoTool:
Inheritance graph
[legend]

List of all members.

Public Slots

virtual void activate (bool temporary=false)
virtual void deactivate ()
virtual void resourceChanged (int key, const QVariant &res)
void setStatusText (const QString &statusText)

Signals

void activateTemporary (const QString &id)
void activateTool (const QString &id)
void cursorChanged (const QCursor &cursor)
void done ()
void selectionChanged (bool hasSelection)
void statusTextChanged (const QString &statusText)

Public Member Functions

 KoTool (KoCanvasBase *canvas)
virtual ~KoTool ()
KAction * action (const QString &name) const
QHash< QString, KAction * > actions () const
KoCanvasBase * canvas () const
virtual void copy () const
QCursor cursor () const
virtual void customMoveEvent (KoPointerEvent *event)
virtual void customPressEvent (KoPointerEvent *event)
virtual void customReleaseEvent (KoPointerEvent *event)
virtual void cut ()
virtual void deleteSelection ()
virtual void inputMethodEvent (QInputMethodEvent *event)
virtual QVariant inputMethodQuery (Qt::InputMethodQuery query, const KoViewConverter &converter) const
virtual void keyPressEvent (QKeyEvent *event)
virtual void keyReleaseEvent (QKeyEvent *event)
virtual void mouseDoubleClickEvent (KoPointerEvent *event)
virtual void mouseMoveEvent (KoPointerEvent *event)=0
virtual void mousePressEvent (KoPointerEvent *event)=0
virtual void mouseReleaseEvent (KoPointerEvent *event)=0
QMap< QString, QWidget * > optionWidgets ()
virtual void paint (QPainter &painter, const KoViewConverter &converter)=0
virtual bool paste ()
QList< QAction * > popupActionList () const
virtual void repaintDecorations ()
virtual KoToolSelection * selection ()
void setToolId (const QString &id)
virtual QStringList supportedPasteMimeTypes () const
QString toolId () const
virtual bool wantsAutoScroll ()
virtual void wheelEvent (KoPointerEvent *event)

Protected Member Functions

void addAction (const QString &name, KAction *action)
virtual QWidget * createOptionWidget ()
virtual QMap< QString, QWidget * > createOptionWidgets ()
QRectF handleGrabRect (const QPointF &position)
QRectF handlePaintRect (const QPointF &position)
void setPopupActionList (const QList< QAction * > &list)
void useCursor (const QCursor &cursor, bool force=false)

Protected Attributes

KoCanvasBase *const m_canvas

Detailed Description

Abstract base class for all tools.

Tools can create or manipulate flake shapes, canvas state or any other thing that a user may wish to do to his document or his view on a document with a pointing device.

There exists an instance of every tool for every pointer device. These instances are managed by the toolmanager..

Definition at line 52 of file KoTool.h.

Constructor & Destructor Documentation

KoTool::KoTool ( KoCanvasBase *  canvas  )  [explicit]

Constructor, normally only called by the factory (see KoToolFactory).

Parameters:
canvas the canvas interface this tool will work for.

Definition at line 43 of file KoTool.cpp.

KoTool::~KoTool (  )  [virtual]

Definition at line 56 of file KoTool.cpp.

Member Function Documentation

KAction * KoTool::action ( const QString &  name  )  const

Retrieve an action by name.

Definition at line 173 of file KoTool.cpp.

QHash< QString, KAction * > KoTool::actions (  )  const

Retrieves the entire collection of actions for the tool.

Definition at line 168 of file KoTool.cpp.

void KoTool::activate ( bool  temporary = false  )  [virtual, slot]

This method is called when this tool instance is activated.

For any main window there is only one tool active at a time, which then gets all user input. Switching between tools will call deactivate on one and activate on the new tool allowing the tool to flush items (like a selection) when it is not in use.

There is one case where two tools are activated at the same. This is the case where one tool delegates work to another temporarily. For example, while shift is being held down. The second tool will get activated with temporary=true and it should emit done() when the state that activated it is ended.

One of the important tasks of activate is to call useCursor()

Parameters:
temporary if true, this tool is only temporarily actived and should emit done when it is done.
See also:
deactivate()

Reimplemented in KoCreatePathTool, KoCreateShapesTool, KoPanTool, KoPathTool, and KoZoomTool.

Definition at line 62 of file KoTool.cpp.

void KoTool::activateTemporary ( const QString &  id  )  [signal]

Emitted when this tool wants itself to temporarily be replaced by another tool.

For instance, a paint tool could desire to be temporarily replaced by a pan tool which could be temporarily replaced by a colorpicker.

Parameters:
id the identification of the desired tool
void KoTool::activateTool ( const QString &  id  )  [signal]

Emitted when this tool wants itself to be replaced by another tool.

Parameters:
id the identification of the desired tool
See also:
toolId(), KoToolFactory::id()
void KoTool::addAction ( const QString &  name,
KAction *  action 
) [protected]

Add an action under the given name to the collection.

Inserting an action under a name that is already used for another action will replace the other action in the collection.

Parameters:
name The name by which the action be retrieved again from the collection.
action The action to add.

Definition at line 163 of file KoTool.cpp.

KoCanvasBase * KoTool::canvas (  )  const

Returns the canvas the tool is working on.

Definition at line 230 of file KoTool.cpp.

void KoTool::copy (  )  const [virtual]

copies the tools selection to the clipboard.

The default implementation is empty to aid tools that don't have any selection.

See also:
selection()

Definition at line 268 of file KoTool.cpp.

QWidget * KoTool::createOptionWidget (  )  [protected, virtual]

Reimplement this if your tool actually has an option widget.

Sets the option widget to 0 by default.

Reimplemented in KoZoomTool.

Definition at line 178 of file KoTool.cpp.

QMap< QString, QWidget * > KoTool::createOptionWidgets (  )  [protected, virtual]

Reimplemented in KoCreatePathTool, and KoPathTool.

Definition at line 183 of file KoTool.cpp.

QCursor KoTool::cursor (  )  const

return the last emitted cursor

Definition at line 205 of file KoTool.cpp.

void KoTool::cursorChanged ( const QCursor &  cursor  )  [signal]

Emitted by useCursor() when the cursor to display on the canvas is changed.

The KoToolManager should connect to this signal to handle cursors further.

void KoTool::customMoveEvent ( KoPointerEvent *  event  )  [virtual]

Called when a custom device moved over the canvas.

Implementors should call event->ignore() if they do not actually use the event.

Parameters:
event state and reason of this custom device move

Reimplemented in KoPanTool.

Definition at line 136 of file KoTool.cpp.

void KoTool::customPressEvent ( KoPointerEvent *  event  )  [virtual]

Called when (one of) a custom device buttons is pressed.

Implementors should call event->ignore() if they do not actually use the event.

Parameters:
event state and reason of this custom device press

Definition at line 126 of file KoTool.cpp.

void KoTool::customReleaseEvent ( KoPointerEvent *  event  )  [virtual]

Called when (one of) a custom device buttons is released.

Implementors should call event->ignore() if they do not actually use the event.

Parameters:
event state and reason of this custom device release

Definition at line 131 of file KoTool.cpp.

void KoTool::cut (  )  [virtual]

Cut the tools selection and copy it to the clipboard.

The default implementation calls copy() and then deleteSelection()

See also:
copy()
deleteSelection()

Definition at line 214 of file KoTool.cpp.

void KoTool::deactivate (  )  [virtual, slot]

This method is called whenever this tool is no longer the active tool.

See also:
activate()

Reimplemented in KoCreatePathTool, and KoPathTool.

Definition at line 67 of file KoTool.cpp.

void KoTool::deleteSelection (  )  [virtual]

Delete the tools selection.

The default implementation is empty to aid tools that don't have any selection.

See also:
selection()

Reimplemented in KoPathTool.

Definition at line 210 of file KoTool.cpp.

void KoTool::done (  )  [signal]

Emitted when the tool has been temporarily activated and wants to notify the world that it's done.

QRectF KoTool::handleGrabRect ( const QPointF &  position  )  [protected]

Returns a handle grab rect at the given position.

The position is expected to be in document coordinates. The grab sensitivity canvas resource is used for the dimension of the rectangle.

Returns:
the handle rectangle in document coordinates

Definition at line 240 of file KoTool.cpp.

QRectF KoTool::handlePaintRect ( const QPointF &  position  )  [protected]

Returns a handle paint rect at the given position.

The position is expected to be in document coordinates. The handle radius canvas resource is used for the dimension of the rectangle.

Returns:
the handle rectangle in document coordinates

Definition at line 249 of file KoTool.cpp.

void KoTool::inputMethodEvent ( QInputMethodEvent *  event  )  [virtual]

Text entry of complex text, like CJK, can be made more interactive if a tool implements this and the InputMethodQuery() methods.

Reimplementing this only provides the user with a more responsive text experience, since the default implementation forwards the typed text as key pressed events.

Parameters:
event the input method event.

Definition at line 117 of file KoTool.cpp.

QVariant KoTool::inputMethodQuery ( Qt::InputMethodQuery  query,
const KoViewConverter &  converter 
) const [virtual]

This method is used to query a set of properties of the tool to be able to support complex input method operations as support for surrounding text and reconversions.

Default implementation returns simple defaults, for tools that want to provide a more responsive text entry experience for CJK languages it would be good to reimplemnt.

Parameters:
query specifies which property is queried.
converter the view converter for the current canvas.

Definition at line 102 of file KoTool.cpp.

void KoTool::keyPressEvent ( QKeyEvent *  event  )  [virtual]

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 in KoCreatePathTool, KoInteractionTool, KoPanTool, KoPathTool, and KoZoomTool.

Definition at line 87 of file KoTool.cpp.

void KoTool::keyReleaseEvent ( QKeyEvent *  event  )  [virtual]

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 in KoInteractionTool, KoPathTool, and KoZoomTool.

Definition at line 92 of file KoTool.cpp.

void KoTool::mouseDoubleClickEvent ( KoPointerEvent *  event  )  [virtual]

Called when (one of) the mouse or stylus buttons is double clicked.

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 mouse or stylus press

Reimplemented in KoCreatePathTool, KoPathTool, and KoZoomTool.

Definition at line 82 of file KoTool.cpp.

virtual void KoTool::mouseMoveEvent ( KoPointerEvent *  event  )  [pure virtual]

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

Implemented in KoCreatePathTool, KoInteractionTool, KoPanTool, KoPathTool, and KoZoomTool.

virtual void KoTool::mousePressEvent ( KoPointerEvent *  event  )  [pure virtual]

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

Implemented in KoCreatePathTool, KoInteractionTool, KoPanTool, and KoPathTool.

virtual void KoTool::mouseReleaseEvent ( KoPointerEvent *  event  )  [pure virtual]

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

Implemented in KoCreatePathTool, KoCreateShapesTool, KoInteractionTool, KoPanTool, KoPathTool, and KoZoomTool.

QMap< QString, QWidget * > KoTool::optionWidgets (  ) 

Return the option widgets for this tool.

Create them if they do not exist yet. If the tool does not have an option widget, this method return an empty list. (After discussion with Thomas, who prefers the toolmanager to handle that case.)

See also:
m_optionWidgets

Definition at line 155 of file KoTool.cpp.

virtual void KoTool::paint ( QPainter &  painter,
const KoViewConverter &  converter 
) [pure virtual]

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.

Implemented in KoCreatePathTool, KoCreateShapesTool, KoInteractionTool, KoPanTool, and KoPathTool.

bool KoTool::paste (  )  [virtual]

Paste the clipboard selection.

A tool typically has one or more shapes selected and pasting should do something meaningful for this specific shape and tool combination. Inserting text in a text tool, for example. If you reimplement this function make sure to also reimplement supportedPasteMimeTypes().

Returns:
will return true if pasting succeeded. False if nothing happened.

Definition at line 263 of file KoTool.cpp.

QList< QAction * > KoTool::popupActionList (  )  const
Returns:
A list of actions to be used for a popup.

Definition at line 220 of file KoTool.cpp.

void KoTool::repaintDecorations (  )  [virtual]

request a repaint of the decorations to be made.

This triggers an update call on the canvas, but does not paint directly.

Reimplemented in KoPathTool.

Definition at line 277 of file KoTool.cpp.

void KoTool::resourceChanged ( int  key,
const QVariant &  res 
) [virtual, slot]

This method is called whenever a property in the resource provider associated with the canvas this tool belongs to changes.

An example is currently selected foreground color.

Reimplemented in KoCreatePathTool.

Definition at line 71 of file KoTool.cpp.

KoToolSelection * KoTool::selection (  )  [virtual]

Returns the internal selection option of this tool.

Each tool can have a selection which is private to that tool and the specified shape that it comes with. The default returns 0.

Reimplemented in KoPathTool.

Definition at line 272 of file KoTool.cpp.

void KoTool::selectionChanged ( bool  hasSelection  )  [signal]

A tool can have a selection that is copy-able, this signal is emitted when that status changes.

Parameters:
hasSelection is true when the tool holds selected data.
void KoTool::setPopupActionList ( const QList< QAction * > &  list  )  [protected]

Set the list of actions to be used as popup menu.

Parameters:
list the list of actions.
See also:
popupActionList

Definition at line 225 of file KoTool.cpp.

void KoTool::setStatusText ( const QString &  statusText  )  [slot]

This method just relays the given text via the tools statusTextChanged signal.

Parameters:
statusText the new status text

Definition at line 235 of file KoTool.cpp.

void KoTool::setToolId ( const QString &  id  ) 

Set the identifier code from the KoToolFactory that created this tool.

Parameters:
id the identifier code
See also:
KoToolFactory::id()

Definition at line 195 of file KoTool.cpp.

void KoTool::statusTextChanged ( const QString &  statusText  )  [signal]

Emitted when the tool wants to display a different status text.

Parameters:
statusText the new status text
QStringList KoTool::supportedPasteMimeTypes (  )  const [virtual]

Returns the mimetypes that this tool's paste() function can handle.

Returns:
QStringList containing the mimetypes that's supported by paste()

Definition at line 258 of file KoTool.cpp.

QString KoTool::toolId (  )  const

get the identifier code from the KoToolFactory that created this tool.

Returns:
the toolId.
See also:
KoToolFactory::id()

Definition at line 200 of file KoTool.cpp.

void KoTool::useCursor ( const QCursor &  cursor,
bool  force = false 
) [protected]

Classes inheriting from this one can call this method to signify which cursor the tool wants to display at this time.

Logical place to call it is after an incoming event has been handled.

Parameters:
cursor the new cursor. If this is the same as the previously set cursor this call will not do anything.
force if true the cursor will be set no matter what.

Definition at line 141 of file KoTool.cpp.

bool KoTool::wantsAutoScroll (  )  [virtual]

Return if dragging (moving with the mouse down) to the edge of a canvas should scroll the canvas (default is true).

Returns:
if this tool wants mouse events to cause scrolling of canvas.

Reimplemented in KoPanTool.

Definition at line 77 of file KoTool.cpp.

void KoTool::wheelEvent ( KoPointerEvent *  event  )  [virtual]

Called when the scrollwheel is used Implementors should call event->ignore() if they do not actually use the event.

Parameters:
event state of this wheel event

Reimplemented in KoZoomTool.

Definition at line 97 of file KoTool.cpp.

Member Data Documentation

KoCanvasBase* const KoTool::m_canvas [protected]

the canvas interface this tool will work for.

Definition at line 407 of file KoTool.h.

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