# gcp::Tool Class Reference

`#include <tool.h>`

List of all members.

## Public Member Functions

| Tool (gcp::Application *App, std::string Id)
virtual | ~Tool ()
bool | OnClicked (View *pView, gcu::Object *pObject, double x, double y, unsigned int state)
void | OnDrag (double x, double y, unsigned int state)
void | OnRelease (double x, double y, unsigned int state)
bool | OnRightButtonClicked (View *pView, gcu::Object *pObject, double x, double y, GtkUIManager *UIManager)
bool | Activate (bool bState)
std::string & | GetName ()
virtual bool | OnRightButtonClicked (GtkUIManager *UIManager)
virtual void | Activate ()
virtual bool | Deactivate ()
void | OnKeyPressed (unsigned int code)
void | OnKeyReleased (unsigned int code)
virtual bool | OnEvent (GdkEvent *event)
virtual bool | NotifyViewChange ()
virtual bool | DeleteSelection ()
virtual bool | CopySelection (GtkClipboard *clipboard)
virtual bool | CutSelection (GtkClipboard *clipboard)
virtual bool | PasteSelection (GtkClipboard *clipboard)
virtual void | AddSelection (WidgetData *data)
virtual bool | OnReceive (GtkClipboard *clipboard, GtkSelectionData *data, int type)
virtual bool | OnUndo ()
virtual bool | OnRedo ()
virtual void | PushNode (xmlNodePtr node)
virtual GtkWidget * | GetPropertyPage ()
virtual char const * | GetHelpTag ()

## Protected Member Functions

virtual bool | OnClicked ()
virtual void | OnDrag ()
virtual void | OnRelease ()
virtual void | OnChangeState ()

## Protected Attributes

double | m_x0
double | m_y0
double | m_x1
double | m_y1
double | m_x
double | m_y
gcu::Object * | m_pObject
gcu::Object * | m_pObjectGroup
View * | m_pView
WidgetData * | m_pData
GtkWidget * | m_pWidget
GnomeCanvasGroup * | m_pGroup
GnomeCanvasItem * | m_pItem
GnomeCanvasItem * | m_pBackground
double | m_dZoomFactor
bool | m_bChanged
unsigned int | m_nState
gcp::Application * | m_pApp
std::set< std::string > | ModifiedObjects
bool | m_bAllowed

## Detailed Description

Base clas for GChemPaint tools.

Definition at line 43 of file tool.h.

## Constructor & Destructor Documentation

gcp::Tool::Tool | ( | gcp::Application * | App,
|  | std::string | Id |
| ) |  |  |

Parameters:

  | App | the GChemPaint application.
  | Id | the name of the tool.

Constructs a new tool.

virtual gcp::Tool::~Tool | ( |  | ) | `[virtual]`

The destructor.

## Member Function Documentation

bool gcp::Tool::OnClicked | ( | View * | pView,
|  | gcu::Object * | pObject,
|  | double | x,
|  | double | y,
|  | unsigned int | state |
| ) |  |  |

Parameters:

  | pView | the view instance owning the event.
  | pObject | the Object on which the click occured.
  | x | the horizontal position of the mouse when the click occured.
  | y | the vertical position of the mouse when the click occured.
  | state | a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See GdkModifierType in GDK documentation.

This method is called by the framework when the tool is active and a click occurs. It initialize some members and then calls the virtual OnClicked() method. It might be called to simulate a click in some instances (e.g. from a contextual menu handler).

Returns:
  true if the mouse drag and button release evens are significative for this tool in the current context, false otherwise. If true, a mouse move will fire the OnDrag method, and a button release will result in an OnRelease call. If false, nothing happens for these events.

void gcp::Tool::OnDrag | ( | double | x,
|  | double | y,
|  | unsigned int | state |
| ) |  |  |

Parameters:

  | x | the horizontal position of the mouse when the event occured.
  | y | the vertical position of the mouse when the event occured.
  | state | a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See GdkModifierType in GDK documentation.

This method is called by the framework when the tool is active, the first mouse button is pressed and the mouse is moved.

void gcp::Tool::OnRelease | ( | double | x,
|  | double | y,
|  | unsigned int | state |
| ) |  |  |

Parameters:

  | x | the horizontal position of the mouse when the event occured.
  | y | the vertical position of the mouse when the event occured.
  | state | a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See GdkModifierType in GDK documentation.

This method is called by the framework when the tool is active and the first mouse button is released.

bool gcp::Tool::OnRightButtonClicked | ( | View * | pView,
|  | gcu::Object * | pObject,
|  | double | x,
|  | double | y,
|  | GtkUIManager * | UIManager |
| ) |  |  |

Parameters:

  | pView | the view where the event occured.
  | pObject | the object on which the event occured.
  | x | the horizontal position of the mouse when the event occured.
  | y | the vertical position of the mouse when the event occured.
  | UIManager | the GtkUIManager in use.

This method is called by the framework when the tool is active and the right mouse button is pressed. It is used to add tool specific menu items to the contextual menu. It calls OnRightButtonClicked(GtkUIManager*).

Returns:
  true if at least one menu item was added, false otherwise.

bool gcp::Tool::Activate | ( | bool | bState | ) |

Parameters:

  | bState | whether to activate or deactivate the tool.

When bState is true, the tool is activated, otherwise it is deactivated. Activate() or Deactivate() is called for this instance.

Returns:
  true on success, and false otherwise. Activation always succeeds.

std::string& gcp::Tool::GetName | ( | void |  | ) | `[inline]`

Returns:
  the tool name.

Definition at line 119 of file tool.h.

virtual bool gcp::Tool::OnRightButtonClicked | ( | GtkUIManager * | UIManager | ) | `[virtual]`

Parameters:

  | UIManager | the GtkUIManager in use.

Adds menu items to the contextual menu. Default implementation do not add any menu item and returns false. Derived classes for which menu items exist must override this method.

Returns:
  true if at least one menu item was added, false otherwise.

virtual void gcp::Tool::Activate | ( |  | ) | `[virtual]`

Virtual method called when the tool is activated. This method should be overriden for all tools which need some initialization when activated. Default does nothing.

virtual bool gcp::Tool::Deactivate | ( |  | ) | `[virtual]`

Virtual method called when the tool is deactivated. This method should be overriden for all tools which need some cleaning when deactivated. Default does nothing.

Returns:
  true on success, false otherwise.

void gcp::Tool::OnKeyPressed | ( | unsigned int | code | ) | `[inline]`

Parameters:

  | code | the state of the mofifier keys as given inthe state field or some GdkEvent derived structures.

Called by the framework when a modifier key has been pressed, updates m_nState, and calls Tool::OnChangeState ().

Definition at line 149 of file tool.h.

References m_nState, and OnChangeState().

void gcp::Tool::OnKeyReleased | ( | unsigned int | code | ) | `[inline]`

Parameters:

  | code | the state of the mofifier keys as given inthe state field or some GdkEvent derived structures.

Called by the framework when a modifier key has been released, updates m_nState, and calls Tool::OnChangeState ().

Definition at line 157 of file tool.h.

References m_nState, and OnChangeState().

virtual bool gcp::Tool::OnEvent | ( | GdkEvent * | event | ) | `[virtual]`

Called by the framework for the active tool when an event occurs. Default just returns false.

Returns:
  true to stop any further propagation of the event, false otherwise.

virtual bool gcp::Tool::NotifyViewChange | ( |  | ) | `[virtual]`

Virtual method called by the framework whenthe active view, and hence the active document has changed, so that the tool can finish its current operation in the previously active document and update its options box according to the new active document settings.

Returns:
  true to accept the document change, false if something went wrong and the active document should not change, as in the case of the fragment tool when the symbols entered can't be interpreted.

virtual bool gcp::Tool::DeleteSelection | ( |  | ) | `[virtual]`

Called by the framework to delete the selection. Tools for which it is meaningful must have an overriden version of this method.

virtual bool gcp::Tool::CopySelection | ( | GtkClipboard * | clipboard | ) | `[virtual]`

Called by the framework to delete the selection. Tools for which it is meaningful must have an overriden version of this method.

virtual bool gcp::Tool::CutSelection | ( | GtkClipboard * | clipboard | ) | `[virtual]`

Called by the framework to copy the selection. Tools for which it is meaningful must have an oveeriden version of this method.

virtual bool gcp::Tool::PasteSelection | ( | GtkClipboard * | clipboard | ) | `[virtual]`

Called by the framework to cut the selection. Tools for which it is meaningful must have an overriden version of this method.

virtual void gcp::Tool::AddSelection | ( | WidgetData * | data | ) | `[virtual]`

Called by the framework to paste data. Tools for which it is meaningful must have an overriden version of this method.

virtual bool gcp::Tool::OnReceive | ( | GtkClipboard * | clipboard,
|  | GtkSelectionData * | data,
|  | int | type |
| ) |  |  | `[virtual]`

Called by the framework when clipboard data are available. Tools for which this is meaningful must have an overriden version of this method.

virtual bool gcp::Tool::OnUndo | ( |  | ) | `[virtual]`

Called by the framework when the user requests to undo the last change. Tools such as text editing tools for which this is meaningful must have an overriden version of this method.

virtual bool gcp::Tool::OnRedo | ( |  | ) | `[virtual]`

Called by the framework when the user requests to redo the last undone change. Tools such as text editing tools for which this is meaningful must have an overriden version of this method.

virtual void gcp::Tool::PushNode | ( | xmlNodePtr | node | ) | `[virtual]`

Parameters:

  | node | an xml node to push on the tools private undo stack.

Used to store a node after a change while editing a text object by text tools.

virtual GtkWidget* gcp::Tool::GetPropertyPage | ( |  | ) | `[virtual]`

Gets the property page for the tool. Called the first time the tool becomes active.

Returns:
  the new tool property page.

virtual char const* gcp::Tool::GetHelpTag | ( |  | ) | `[inline, virtual]`

Gets the tag used to display the appropriate help topic when the user presses the help button in the tools box. The framework will prefix the result with the application name. The text tool in GChemPaint returns "text" which becomes "gchempaint-text".

Returns:
  the help tag for the tool.

Definition at line 236 of file tool.h.

virtual bool gcp::Tool::OnClicked | ( |  | ) | `[protected, virtual]`

Called from OnClicked(View*,gcu::Object*,double,doubl,unsigned int) when a click occured. This method must be overriden in derived classes, and return true if the drag and release events are meaningful for the tool in the current context. Default implementation does nothing and returns false.

Returns:
  true if drag and release events are needed, false otherwise.

virtual void gcp::Tool::OnDrag | ( |  | ) | `[protected, virtual]`

Called from OnDrag(double,double,unsigned int) when a drag event occured occured. This method must be overriden in derived classes if drag events are meaningful for the tool. Default implementation does nothing.

virtual void gcp::Tool::OnRelease | ( |  | ) | `[protected, virtual]`

Called from OnRelease(double,double,unsigned int) when a button release event occured. This method must be overriden in derived classes if button release events are meaningful for the tool. Default implementation does nothing.

virtual void gcp::Tool::OnChangeState | ( |  | ) | `[protected, virtual]`

Called when a modifier key has been pressed or released, and fires a drag event so that the tool can update things if necessary.

Referenced by OnKeyPressed(), and OnKeyReleased().

## Member Data Documentation

double gcp::Tool::m_x0 `[protected]`

x coordinate for the last mouse click (unless the tool modified it).

Definition at line 273 of file tool.h.

double gcp::Tool::m_y0 `[protected]`

y coordinate for the last mouse click (unless the tool modified it).

Definition at line 277 of file tool.h.

double gcp::Tool::m_x1 `[protected]`

x coordinate for the last mouse click (unless the tool modified it). It might be used by tools necessitating to pairs of coordinates.

Definition at line 282 of file tool.h.

double gcp::Tool::m_y1 `[protected]`

y coordinate for the last mouse click (unless the tool modified it). It might be used by tools necessitating to pairs of coordinates.

Definition at line 287 of file tool.h.

double gcp::Tool::m_x `[protected]`

The current x position of the mouse cursor.

Definition at line 291 of file tool.h.

double gcp::Tool::m_y `[protected]`

The current y position of the mouse cursor.

Definition at line 295 of file tool.h.

gcu::Object* gcp::Tool::m_pObject `[protected]`

The object on which the last click occured or NULL.

Definition at line 299 of file tool.h.

gcu::Object* gcp::Tool::m_pObjectGroup `[protected]`

The group to which m_pObject belongs if any.

Definition at line 303 of file tool.h.

View* gcp::Tool::m_pView `[protected]`

The active gcp::View.

Definition at line 307 of file tool.h.

WidgetData* gcp::Tool::m_pData `[protected]`

The widget data for the current active canvas.

Definition at line 311 of file tool.h.

GtkWidget* gcp::Tool::m_pWidget `[protected]`

The active canvas widget.

Definition at line 315 of file tool.h.

GnomeCanvasGroup* gcp::Tool::m_pGroup `[protected]`

The root group in the active canvas.

Definition at line 319 of file tool.h.

GnomeCanvasItem* gcp::Tool::m_pItem `[protected]`

The item on which the last click occured if any.

Definition at line 323 of file tool.h.

GnomeCanvasItem* gcp::Tool::m_pBackground `[protected]`

The canvas background.

Definition at line 327 of file tool.h.

double gcp::Tool::m_dZoomFactor `[protected]`

The zoom factor when the click occured.

Definition at line 331 of file tool.h.

bool gcp::Tool::m_bChanged `[protected]`

Flag that might be used by tools to store whether they changed something since the last click (and before releasing the button).

Definition at line 336 of file tool.h.

unsigned int gcp::Tool::m_nState `[protected]`

The state of modifier keys as a GdkModifierType values combination.

Definition at line 340 of file tool.h.

Referenced by OnKeyPressed(), and OnKeyReleased().

gcp::Application* gcp::Tool::m_pApp `[protected]`

The application owning the tool.

Definition at line 344 of file tool.h.

std::set<std::string> gcp::Tool::ModifiedObjects `[protected]`

A set of modified objects tools might use to track what they did modify.

Definition at line 348 of file tool.h.

bool gcp::Tool::m_bAllowed `[protected]`

if true, the intended operation is allowed. Default value is true, each tool must set this flag to false if necessary.

Definition at line 353 of file tool.h.

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

- tool.h