Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Namespace Members | Class Members | File Members | Search for 

Tool_v1 Class Reference

Specifies the interface between tools and the Kernel/OIL. More...

#include <tool.h>

Inheritance diagram for Tool_v1:

BezierTool BlankTool DragTool GridTool PenTool PushTool RotateTool TextTool Tool ZoomTool List of all members.

Public Member Functions

 Tool_v1 ()
virtual ~Tool_v1 ()
 Destroys the tool, performing any clean-up necessary.
virtual BOOL Init ()
 Called after tool's constructor to ask it whether it wants to exist or not. Each tool is asked in two passes, so that its existence can depend on another tool. If a tool does not want to exist, it should return FALSE, when it will be deleted.
virtual UINT32 GetToolInterfaceVersion ()
virtual UINT32 GetID ()
virtual void Describe (void *Info)
 Asks a tool for more information. The pointer points to a struct such as ToolInfo_v1 which the tool should fill in. All fields should be filled (NULL is OK for char* variables). The type of the pointer is not explicitly defined so the structure can evolve while keeping backward compatibility.
virtual void OnMouseMove (DocCoord, Spread *, ClickModifiers)
 This function should be overridden by any tool that wants to receive mouse move messages, when a drag is NOT in progress. For example, tools can use this function to change the mouse cursor as it moves over a "hot spot". The default implementation does nothing.
virtual void OnClick (DocCoord, ClickType, ClickModifiers, Spread *)
 This function should be overridden by any tool that wants to receive clicks on the document. When DocView receives a click event from the OIL layer it finds the current tool and calls this function.
virtual BOOL OnKeyPress (KeyPress *pKeyPress)
 This function should be overridden by any tool that wants to process key presses. The current tool is the first part of Camelot that gets the chance to process a key press, so tools can override all tool-switching and hot-key combinations if it needs to.
virtual BOOL OnIdle ()
 This function should be overridden by any tool that wants to do processing on idle events. This processing should be quick (or split into small, quick bits). Once processing is finished FALSE should be returned (although this does not guarentee then function will not be called again).
virtual BOOL GetStatusLineText (String_256 *ptext, Spread *pSpread, DocCoord DocPos, ClickModifiers ClickMods)
 Each tool should override this function to return valid status line text.
virtual BOOL RegisterToolSwitch (KeyPress *pKeyPress, BOOL FromFile=FALSE)
 This allows you to specify a key press that will be used to switch to the tool temporarily. The pKeyPress should be a valid one created by one of its public constructors.
virtual BOOL DragFinished (DragEndType HowEnded)
 Tools that start drag operations can use this function to find out how well the drag went if the operation calls this function.
virtual void RenderToolBlobs (Spread *, DocRect *)
 This function is called in the main drawing loop to get the tool to render its blobs (ie the centre of rotation for the rotation tool). Since this is the base class version of this function and will be called if the tool does not provide its own RenderToolBlobs function, then it can be assumed that the tool does not need to draw anything, so it does nothing.
virtual void SelectChange (BOOL IsSelected)
 Used to inform a tool that it is being selected or deselected. Default behaviour is to do nothing. A real tool should update the infobar when the tool is selected - this is usually all a tool will do.
virtual void GetRulerOrigin (Spread *pSpread, UserCoord *)
 Gives the current tool the chance to change the coordinates displayed on the ruler.
virtual void RenderRulerBlobs (RulerBase *pRuler, UserRect &UpdateRect, BOOL IsBackground)
 Gives the current tool the chance to render additional blobs on the ruler Is called twice - once before the standard ruler graphics are rendered (to allow additional background to be drawn) and once afterwards.
virtual BOOL GetRulerStatusLineText (String_256 *pText, UserCoord PointerPos, Spread *pSpread, RulerBase *pRuler)
virtual BOOL OnRulerClick (UserCoord PointerPos, ClickType Click, ClickModifiers Mods, Spread *pSpread, RulerBase *pRuler)
BOOL IsCurrent () const
 Centralised way of doing this. Amazing this function didn't exist before.
virtual BOOL AreToolBlobsRenderedOnSelection ()

Static Public Member Functions

static UINT32 GetOwnerModule (UINT32)
static BOOL SetOwnerModule (UINT32, UINT32)

Public Attributes

ToolListItem * Parent

Static Protected Attributes

static UINT32 OwnerModuleList [TOOLID_MAX+1]

Private Member Functions

 CC_DECLARE_MEMDUMP (Tool_v1)

Detailed Description

Specifies the interface between tools and the Kernel/OIL.

Author:
Tim_Browse (Xara Group Ltd) <camelotdev@xara.com>
Date:
19/7/93
See also:
Tool

Definition at line 310 of file tool.h.

Constructor & Destructor Documentation

Tool_v1::Tool_v1 (   )  [inline]
 

Definition at line 316 of file tool.h.

00316 { Parent = NULL; };

Tool_v1::~Tool_v1 (   )  [virtual]
 

Destroys the tool, performing any clean-up necessary.

Author:
Tim_Browse (Xara Group Ltd) <camelotdev@xara.com>
Date:
7/7/93
Parameters:
- [INPUTS]
- [OUTPUTS]
Returns:
-

Errors: -

See also:
-

Definition at line 1213 of file tool.cpp.

01214 {
01215     // Null destructor
01216 }

Member Function Documentation

virtual BOOL Tool_v1::AreToolBlobsRenderedOnSelection (   )  [inline, virtual]
 

Reimplemented in ContourTool, SelectorTool, SliceTool, and TextTool.

Definition at line 392 of file tool.h.

00392 {return FALSE;}

Tool_v1::CC_DECLARE_MEMDUMP (  Tool_v1   )  [private]
 

void Tool_v1::Describe (  void *  InfoPtr  )  [virtual]
 

Asks a tool for more information. The pointer points to a struct such as ToolInfo_v1 which the tool should fill in. All fields should be filled (NULL is OK for char* variables). The type of the pointer is not explicitly defined so the structure can evolve while keeping backward compatibility.

Author:
Andy_Pennell (Xara Group Ltd) <camelotdev@xara.com>
Date:
21/6/93
Parameters:
Pointer to area to recieve info [INPUTS]
Info area is updated [OUTPUTS]
Returns:
None

Errors: None

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, EllipseTool, GradFillTool, TranspTool, FreeHandTool, GridTool, LiveEffectsTool, MouldTool, PenTool, PushTool, RectangleTool, QuickShapeTool, RotateTool, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1237 of file tool.cpp.

01238 {
01239     ENSURE(FALSE, "Describe called for base tool class!");
01240     
01241     // Cast structure into the latest one we understand.
01242     ToolInfo_v1 *Info = (ToolInfo_v1 *) InfoPtr;
01243     
01244     Info->InfoVersion = 1;
01245     
01246     Info->InterfaceVersion = GetToolInterfaceVersion();  // You should always have this line.
01247     
01248     // These are all garbage as we should never try to create one of these...
01249     Info->Version = 1;
01250     Info->ID = TOOLID_INVALID;
01251     Info->TextID = 0;
01252     
01253     // so we never get instantiated
01254     Info->Family = Info->Name = Info->Purpose = Info->Author = NULL;
01255 }

BOOL Tool_v1::DragFinished (  DragEndType  HowEnded  )  [virtual]
 

Tools that start drag operations can use this function to find out how well the drag went if the operation calls this function.

Author:
Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com>
Date:
26/8/94
Parameters:
HowEnded - Describes how the drag ended (an if it was a drag at all really [INPUTS]
Returns:
TRUE if it is OK for the operation to finish doing the things that it was going to do, or FALSE if the tool wants the operation to stop right now.

Reimplemented in SelectorTool, and SliceTool.

Definition at line 1462 of file tool.cpp.

01463 {
01464     // Do nothing in the base class version of this function.
01465     // Just let the operation get on with what it was doing
01466     return TRUE;
01467 }

virtual UINT32 Tool_v1::GetID (  void   )  [inline, virtual]
 

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, EllipseTool, GradFillTool, TranspTool, FreeHandTool, GridTool, LiveEffectsTool, MouldTool, PenTool, PushTool, RectangleTool, QuickShapeTool, RotateTool, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 327 of file tool.h.

00327 { return 0; } ;

static UINT32 Tool_v1::GetOwnerModule (  UINT32   )  [static]
 

void Tool_v1::GetRulerOrigin (  Spread *  pSpread,
UserCoord *  pOffsets
)  [virtual]
 

Gives the current tool the chance to change the coordinates displayed on the ruler.

Author:
Phil_Martin (Xara Group Ltd) <camelotdev@xara.com>
Date:
30/Jun/2006
Parameters:
pSpread - the spread for which the ruler is displayed [INPUTS]
pOffsets - the desired origin shift in user space (is initialised to 0,0) [OUTPUTS]

Reimplemented in TextTool.

Definition at line 1543 of file tool.cpp.

01544 {
01545     // Override me if you want!
01546     // Note that overriding this function implies that you will ensure the redraw of the rulers
01547     // as you enter and leave your tool.
01548 }

BOOL Tool_v1::GetRulerStatusLineText (  String_256 *  pText,
UserCoord  PointerPos,
Spread *  pSpread,
RulerBase *  pRuler
)  [virtual]
 

Reimplemented in TextTool.

Definition at line 1589 of file tool.cpp.

01591 {
01592     // Override me if you want!
01593     return FALSE;
01594 }

BOOL Tool_v1::GetStatusLineText (  String_256 *  ptext,
Spread *  pSpread,
DocCoord  DocPos,
ClickModifiers  ClickMods
)  [virtual]
 

Each tool should override this function to return valid status line text.

Author:
Ed_Cornes (Xara Group Ltd) <camelotdev@xara.com>
Date:
14/11/94
Returns:
TRUE if returning valid text

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, GradFillTool, TranspTool, FreeHandTool, LiveEffectsTool, MouldTool, PenTool, PushTool, QuickShapeBase, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1372 of file tool.cpp.

01373 {
01374     return FALSE;   // defaults to no text
01375 }

virtual UINT32 Tool_v1::GetToolInterfaceVersion (   )  [inline, virtual]
 

Definition at line 324 of file tool.h.

00324 { return 1; } ;

BOOL Tool_v1::Init (  void   )  [virtual]
 

Called after tool's constructor to ask it whether it wants to exist or not. Each tool is asked in two passes, so that its existence can depend on another tool. If a tool does not want to exist, it should return FALSE, when it will be deleted.

Author:
Andy_Pennell (Xara Group Ltd) <camelotdev@xara.com>
Date:
21/6/93
Parameters:
- [INPUTS]
- [OUTPUTS]
Returns:
TRUE if OK, FALSE if tool doesn't want to initialise.

Errors: None

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, EllipseTool, GradFillTool, TranspTool, FreeHandTool, GridTool, LiveEffectsTool, MouldTool, PenTool, PushTool, RectangleTool, QuickShapeBase, QuickShapeTool, RotateTool, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1190 of file tool.cpp.

01191 {
01192     ENSURE(FALSE, "Init called for base tool class!");
01193     return FALSE;                   // Should never try to instantiate a tool base class
01194 }

BOOL Tool_v1::IsCurrent (   )  const
 

Centralised way of doing this. Amazing this function didn't exist before.

Author:
Andy_Pennell (Xara Group Ltd) <camelotdev@xara.com>
Date:
18/10/94
Returns:
TRUE if 'this' is the current tool, FALSE if not.

Definition at line 1480 of file tool.cpp.

01481 {
01482     if (Tool::GetCurrent() == this)
01483         return TRUE;
01484     else
01485         return FALSE;
01486 }

void Tool_v1::OnClick (  DocCoord  ,
ClickType  ,
ClickModifiers  ,
Spread * 
)  [virtual]
 

This function should be overridden by any tool that wants to receive clicks on the document. When DocView receives a click event from the OIL layer it finds the current tool and calls this function.

Author:
Phil_Martin (Xara Group Ltd) <camelotdev@xara.com>
Date:
2/7/93
Parameters:
Position of click in spread coordinates [INPUTS] Click type (single, double or drag) Modifiers (adjusted, constrained, etc...) Pointer to the spread in which the click occurred
None [OUTPUTS]
Returns:
None

Errors: None.

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, DragTool, GradFillTool, TranspTool, FreeHandTool, GridTool, LiveEffectsTool, MouldTool, PenTool, PushTool, QuickShapeBase, RotateTool, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1279 of file tool.cpp.

01281 {
01282     ENSURE(FALSE, "OnClick called for base tool class!");
01283     
01284     // DO nothing!
01285     // Click not handled by base class!
01286 }

BOOL Tool_v1::OnIdle (   )  [virtual]
 

This function should be overridden by any tool that wants to do processing on idle events. This processing should be quick (or split into small, quick bits). Once processing is finished FALSE should be returned (although this does not guarentee then function will not be called again).

Author:
Peter_Arnold (Xara Group Ltd) <camelotdev@xara.com>
Date:
14/09/94
Parameters:
- [INPUTS]
- [OUTPUTS]
Returns:
TRUE - the tool wants more idle events. FALSE - no more idle events are required.

Errors: -

Reimplemented in FreeHandTool, LiveEffectsTool, SelectorTool, and TextTool.

Definition at line 1357 of file tool.cpp.

01358 {
01359     // Return FALSE to turn off
01360     return FALSE;
01361 }

BOOL Tool_v1::OnKeyPress (  KeyPress *  pKeyPress  )  [virtual]
 

This function should be overridden by any tool that wants to process key presses. The current tool is the first part of Camelot that gets the chance to process a key press, so tools can override all tool-switching and hot-key combinations if it needs to.

Author:
Mark_Neves (Xara Group Ltd) <camelotdev@xara.com>
Date:
30/8/94
Parameters:
pKeyPress = Ptr to a platform-indy key press object [INPUTS]
- [OUTPUTS]
Returns:
TRUE - the key press was processed, so do NOT pass on FALSE - not processed, so let others have a bash

Errors: -

Reimplemented in BezierTool, BlendTool, ContourTool, GradFillTool, TranspTool, PenTool, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1332 of file tool.cpp.

01333 {
01334     // Return FALSE so the key press gets passed on to others
01335     return FALSE;
01336 }

void Tool_v1::OnMouseMove (  DocCoord  ,
Spread *  ,
ClickModifiers 
)  [virtual]
 

This function should be overridden by any tool that wants to receive mouse move messages, when a drag is NOT in progress. For example, tools can use this function to change the mouse cursor as it moves over a "hot spot". The default implementation does nothing.

Author:
Justin_Flude (Xara Group Ltd) <camelotdev@xara.com>
Date:
14 Oct 93
Parameters:
Position of the mouse, in spread coordinates [INPUTS] Pointer to the spread in which the mouse lies. Which button/keys are down.
- [OUTPUTS]
Returns:
-

Errors: -

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, GradFillTool, TranspTool, FreeHandTool, GridTool, LiveEffectsTool, MouldTool, PenTool, PushTool, QuickShapeBase, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1308 of file tool.cpp.

01309 {
01310     // Do nothing at all, if you like.  It's your tool!
01311 }

BOOL Tool_v1::OnRulerClick (  UserCoord  PointerPos,
ClickType  Click,
ClickModifiers  Mods,
Spread *  pSpread,
RulerBase *  pRuler
)  [virtual]
 

Reimplemented in TextTool.

Definition at line 1618 of file tool.cpp.

01624 {
01625     // Override me if you want!
01626     return FALSE;
01627 }

BOOL Tool_v1::RegisterToolSwitch (  KeyPress *  pKeyPress,
BOOL  FromFile = FALSE
)  [virtual]
 

This allows you to specify a key press that will be used to switch to the tool temporarily. The pKeyPress should be a valid one created by one of its public constructors.

Author:
Mark_Neves (Xara Group Ltd) <camelotdev@xara.com>
Date:
30/8/94
Parameters:
pKeyPress = Ptr to a platform-indy key press object [INPUTS] FromFile = TRUE if the tool switch was defined in a file FALSE if it's being registered directly
- [OUTPUTS]
Returns:
TRUE - the key press has been registered for temporary switching to this tool FALSE - failed. Either another tool has this combo, or the keypress is invalid
If the FromFile flag is TRUE then all registered tool switches for this tool that have been registered directly (i.e. by the tool itself calling this routine with FromFile==FALSE) are deleted.

The means that tool switches defined in file take priority over directly defined ones, so that in the future we may allow the user to choose which key presses he wants to temp tool switching. Also means that a tool can have temp switching codes with defs in a file; useful for third party tools who can't get hold of the bound in kernel resource file.

Returns:
Errors: -
See also:
KeyPress::KeyPress

Definition at line 1406 of file tool.cpp.

01407 {
01408     ENSURE(pKeyPress->IsValid(),"Tool trying to register a tool key switch with an invalid key press object");
01409     if (!pKeyPress->IsValid()) return FALSE;
01410 
01411     Tool* pThisTool = (Tool*)this;
01412 
01413     if (FromFile) Tool::RemoveDirectRegToolSwitches(pThisTool);
01414 
01415     ToolSwitch* pToolSwitch = (ToolSwitch*)ToolSwitchList.GetHead();
01416     while (pToolSwitch != NULL)
01417     {
01418         if (pToolSwitch->pTool == pThisTool)
01419         {
01420             // if this tool switch has already been assigned for this tool, return TRUE
01421             if (*pToolSwitch->pKeyPress == *pKeyPress)
01422             {
01423                 delete pKeyPress;
01424                 return TRUE;
01425             }
01426         }
01427         else
01428         {
01429             // If this tool switch belongs to another tool, return FALSE
01430             if (*pToolSwitch->pKeyPress == *pKeyPress)
01431                 return FALSE;
01432         }
01433 
01434         pToolSwitch = (ToolSwitch*)ToolSwitchList.GetNext(pToolSwitch);
01435     }
01436 
01437     // At this point we know that it is safe to assign the tool switch key press for this tool
01438 
01439     // Make a new tool switch
01440     ToolSwitch* pNewToolSwitch = new ToolSwitch(pThisTool,pKeyPress,FromFile);
01441 
01442     if (pNewToolSwitch != NULL)
01443         ToolSwitchList.AddTail(pNewToolSwitch);
01444 
01445     return (pNewToolSwitch != NULL);
01446 }

void Tool_v1::RenderRulerBlobs (  RulerBase *  pRuler,
UserRect &  UpdateRect,
BOOL  IsBackground
)  [virtual]
 

Gives the current tool the chance to render additional blobs on the ruler Is called twice - once before the standard ruler graphics are rendered (to allow additional background to be drawn) and once afterwards.

Author:
Martin Wuerthner <xara@mw-software.com>
Date:
07/07/06
Parameters:
pRuler - the ruler that is currently being redrawn [INPUTS] UpdateRect - the rectangle to be updated in user coordinates (with the tool origin applied) IsBackground - whether this is the call before drawing the main blobs or the call after rendering the main blobs

Reimplemented in TextTool.

Definition at line 1567 of file tool.cpp.

01568 {
01569     // Override me if you want!
01570     // Note that overriding this function implies that you will ensure the redraw of the rulers
01571     // as you enter and leave your tool.
01572 }

void Tool_v1::RenderToolBlobs (  Spread *  ,
DocRect * 
)  [virtual]
 

This function is called in the main drawing loop to get the tool to render its blobs (ie the centre of rotation for the rotation tool). Since this is the base class version of this function and will be called if the tool does not provide its own RenderToolBlobs function, then it can be assumed that the tool does not need to draw anything, so it does nothing.

Author:
Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com>
Date:
18/8/93
See also:
DocView::RenderOnTop

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, FreeHandTool, GridTool, MouldTool, PenTool, RotateTool, SelectorTool, SliceTool, and TextTool.

Definition at line 1504 of file tool.cpp.

01505 {
01506     // If the tool does not want to draw anything then it need not have a 
01507     // RenderToolBlobs function and this one will be called instead.
01508     // This draws nothing
01509 }

void Tool_v1::SelectChange (  BOOL  IsSelected  )  [virtual]
 

Used to inform a tool that it is being selected or deselected. Default behaviour is to do nothing. A real tool should update the infobar when the tool is selected - this is usually all a tool will do.

Author:
Tim_Browse (Xara Group Ltd) <camelotdev@xara.com>
Date:
11/11/93
Parameters:
IsSelected - Indicates whether tool is being selected (TRUE) or [INPUTS] deselected (FALSE).

Reimplemented in BezierTool, BlendTool, BlankTool, ContourTool, GradFillTool, TranspTool, FreeHandTool, GridTool, LiveEffectsTool, MouldTool, PenTool, PushTool, QuickShapeBase, RotateTool, SelectorTool, SliceTool, TextTool, and ZoomTool.

Definition at line 1525 of file tool.cpp.

01526 {
01527     // Override me!
01528 }

static BOOL Tool_v1::SetOwnerModule (  UINT32  ,
UINT32 
)  [static]
 

Member Data Documentation

UINT32 Tool_v1::OwnerModuleList[TOOLID_MAX+1] [static, protected]
 

Definition at line 395 of file tool.h.

ToolListItem* Tool_v1::Parent
 

Definition at line 381 of file tool.h.

The documentation for this class was generated from the following files:
Generated on Sat Nov 10 04:01:58 2007 for Camelot by  doxygen 1.4.4