ToolData Class Reference

#include <c4d_tooldata.h>

Inheritance diagram for ToolData:

Detailed Description

A data class for creating tool plugins.
Use RegisterToolPlugin() to register a tool plugin.

Note
To make modeling tools that support the Transform/Apply buttons use DescriptionToolData instead.

Private Member Functions

virtual CDialog * AllocDialog (BaseContainer *bc, CDialog *cd_parent, Int32 dlg_id)
 
virtual void FreeDialog (CDialog *cd)
 

Friends

Bool RegisterToolPlugin (Int32 id, const String &str, Int32 info, BaseBitmap *icon, const String &help, ToolData *dat)
 
Bool RegisterPyToolPlugin (Int32 id, const String &str, Int32 info, BaseBitmap *icon, const String &help, ToolData *dat, GeResource *res)
 

Init/Free Tool

virtual Bool InitTool (BaseDocument *doc, BaseContainer &data, BaseThread *bt)
 
virtual void FreeTool (BaseDocument *doc, BaseContainer &data)
 

Input

virtual Bool MouseInput (BaseDocument *doc, BaseContainer &data, BaseDraw *bd, EditorWindow *win, const BaseContainer &msg)
 
virtual Bool KeyboardInput (BaseDocument *doc, BaseContainer &data, BaseDraw *bd, EditorWindow *win, const BaseContainer &msg)
 

Draw

virtual TOOLDRAW Draw (BaseDocument *doc, BaseContainer &data, BaseDraw *bd, BaseDrawHelp *bh, BaseThread *bt, TOOLDRAWFLAGS flags)
 

DisplayControl

virtual Bool DisplayControl (BaseDocument *doc, BaseObject *op, BaseObject *chainstart, BaseDraw *bd, BaseDrawHelp *bh, ControlDisplayStruct &cds)
 
virtual Bool InitDisplayControl (BaseDocument *doc, BaseContainer &data, BaseDraw *bd, const AtomArray *active)
 
virtual void FreeDisplayControl (void)
 

Miscellaneous

virtual SubDialogAllocSubDialog (BaseContainer *bc)
 
virtual Bool DoCommand (ModelingCommandData &mdat)
 
virtual Bool GetCursorInfo (BaseDocument *doc, BaseContainer &data, BaseDraw *bd, Float x, Float y, BaseContainer &bc)
 
virtual const String GetResourceSymbol ()
 
virtual Int32 GetState (BaseDocument *doc)
 
virtual void InitDefaultSettings (BaseDocument *pDoc, BaseContainer &data)
 

Description

virtual Bool GetDDescription (BaseDocument *doc, BaseContainer &data, Description *description, DESCFLAGS_DESC &flags)
 
virtual Bool GetDParameter (BaseDocument *doc, BaseContainer &data, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags)
 
virtual Bool SetDParameter (BaseDocument *doc, BaseContainer &data, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)
 
virtual Bool GetDEnabling (BaseDocument *doc, BaseContainer &data, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer *itemdesc)
 
virtual Bool TranslateDescID (BaseDocument *doc, BaseContainer &data, const DescID &id, DescID &res_id, C4DAtom *res_at)
 

Message

virtual Bool Message (BaseDocument *doc, BaseContainer &data, Int32 type, void *t_data)
 

Additional Inherited Members

- Public Member Functions inherited from BaseData
 BaseData ()
 
virtual ~BaseData (void)
 
void Destructor (void)
 

Member Function Documentation

§ AllocDialog()

virtual CDialog* AllocDialog ( BaseContainer bc,
CDialog *  cd_parent,
Int32  dlg_id 
)
privatevirtual

§ FreeDialog()

virtual void FreeDialog ( CDialog *  cd)
privatevirtual

§ InitTool()

virtual Bool InitTool ( BaseDocument doc,
BaseContainer data,
BaseThread bt 
)
virtual

Called each time the tool is selected.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]btThe calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
Returns
true if successful, otherwise false.

Reimplemented in BrushToolData, SculptBrushToolData, and DescriptionToolData.

§ FreeTool()

virtual void FreeTool ( BaseDocument doc,
BaseContainer data 
)
virtual

Called each time the user chooses another tool.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.

Reimplemented in BrushToolData, SculptBrushToolData, and DescriptionToolData.

§ MouseInput()

virtual Bool MouseInput ( BaseDocument doc,
BaseContainer data,
BaseDraw bd,
EditorWindow win,
const BaseContainer msg 
)
virtual

Called when the user clicks with the mouse in any of the editors views.
Use GetToolScale to make adjustments relative to the view size.

Note
If a tool allows the user to move, rotate or scale the currently selected object, then it should call GeSyncMessage(EVMSG_ASYNCEDITORMOVE) so that managers can update their position fields during the drag.
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]winThe window for the active editor view. Cinema 4D owns the pointed editor window.
[in]msgThe mouse message container. See Input Events.
Returns
true if successful, otherwise false.

Reimplemented in BrushToolData, and SculptBrushToolData.

§ KeyboardInput()

virtual Bool KeyboardInput ( BaseDocument doc,
BaseContainer data,
BaseDraw bd,
EditorWindow win,
const BaseContainer msg 
)
virtual

Called when the user types something in any of the editors views.

Note
Make sure this function is used only when the user is somehow working with the tool plugin, so that other plugins can also use this hook when it is their turn.
Warning
Always returning true here will block all keyboard use.
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]winThe window for the active editor view. Cinema 4D owns the pointed editor window.
[in]msgThe keyboard message container. See Input Events.
Returns
true if the keyboard event was used, false if it should be passed along.

Reimplemented in SculptBrushToolData.

§ Draw()

virtual TOOLDRAW Draw ( BaseDocument doc,
BaseContainer data,
BaseDraw bd,
BaseDrawHelp bh,
BaseThread bt,
TOOLDRAWFLAGS  flags 
)
virtual

Called when the editor view is updated to display graphics for the tool in the view.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]bdThe editor's view. The caller owns the pointed view.
[in]bhThe helper for the editor's view. The caller owns the pointed base draw helper.
[in]btThe calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
[in]flagsThe tool draw flags: TOOLDRAWFLAGS
Returns
The tool draw result: TOOLDRAW

Reimplemented in SculptBrushToolData.

§ DisplayControl()

virtual Bool DisplayControl ( BaseDocument doc,
BaseObject op,
BaseObject chainstart,
BaseDraw bd,
BaseDrawHelp bh,
ControlDisplayStruct cds 
)
virtual

Called to set information about how the active object should be displayed.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]opThe active object. Cinema 4D owns the pointed object.
[in]chainstartThe start of the object chain. Cinema 4D owns the pointed object.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]bhThe helper for the editor's view. The caller owns the pointed view helper.
[in]cdsThe display control settings.
Returns
true if successful, otherwise false.

Reimplemented in SculptBrushToolData.

§ InitDisplayControl()

virtual Bool InitDisplayControl ( BaseDocument doc,
BaseContainer data,
BaseDraw bd,
const AtomArray active 
)
virtual

Called to initialize resources for the display control used in DisplayControl.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]activeThe active objects array. Cinema 4D owns the pointed array.
Returns
true if successful, otherwise false.

Reimplemented in SculptBrushToolData.

§ FreeDisplayControl()

virtual void FreeDisplayControl ( void  )
virtual

Called to free resources allocated in InitDisplayControl.

Reimplemented in SculptBrushToolData.

§ AllocSubDialog()

virtual SubDialog* AllocSubDialog ( BaseContainer bc)
virtual

Called to get the sub-dialog for the Active Tool window.
Return here an instance of the tool's sub-dialog.

Parameters
[in]bcCurrently not used.
Returns
The allocated sub-dialog. Cinema 4D owns the pointed sub-dialog.

§ DoCommand()

virtual Bool DoCommand ( ModelingCommandData mdat)
virtual

Called by SendModelingCommand to perform the command in mdat.

Parameters
[in]mdatThe data for the modeling command to perform.
Returns
true if successful, otherwise false.

§ GetCursorInfo()

virtual Bool GetCursorInfo ( BaseDocument doc,
BaseContainer data,
BaseDraw bd,
Float  x,
Float  y,
BaseContainer bc 
)
virtual

Called when the cursor is over the editor views to get the state of the mouse pointer.
Set the bubble help and cursor, for example:

Note
Make sure this function is used only when the user is somehow working with the scene hook plugin, so that other plugins can also use this hook when it is their turn.
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]xThe X coordinate of the mouse cursor relative to the top-left of the active editor view.
[in]yThe Y coordinate of the mouse cursor relative to the top-left of the active editor view.
[in]bcThe container to store the cursor information in: BFM_GETCURSORINFO_RESULT
Returns
true if successful, otherwise false.

Reimplemented in BrushToolData, and SculptBrushToolData.

§ GetResourceSymbol()

virtual const String GetResourceSymbol ( )
virtual

Called to get the description resource symbol for the tool.

Returns
The name of the description resource file to use for the plugin without .res extension, for example "Toolname".
The name has to be unique, i.e. "Tdisplay" cannot be used for two different descriptions. See Description Resource for more information.

Reimplemented in DescriptionToolData.

§ GetState()

virtual Int32 GetState ( BaseDocument doc)
virtual

Called to check if the tool should be enabled or not.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
Returns
A combination of the 2 command flags: CMD_ENABLED CMD_VALUE.

Reimplemented in SculptBrushToolData.

§ InitDefaultSettings()

virtual void InitDefaultSettings ( BaseDocument pDoc,
BaseContainer data 
)
virtual

Called to initialize the default tool settings in data.

Parameters
[in]pDocThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.

Reimplemented in BrushToolData, SculptBrushToolData, and DescriptionToolData.

§ GetDDescription()

virtual Bool GetDDescription ( BaseDocument doc,
BaseContainer data,
Description description,
DESCFLAGS_DESC flags 
)
virtual

Called to add parameters to the description for the tool.
Modify the passed description as needed, set the appropriate flags and then make sure to include a call to the parent at the end:

return SUPER::GetDescription(data, description, flags, parentdescription);
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in,out]descriptionThe node's description to add the parameters to. Cinema 4D owns the pointed description.
[in,out]flagsThe flags for the description operation: DESCFLAGS_DESC
Returns
true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in BrushToolData, SculptBrushToolData, and DescriptionToolData.

§ GetDParameter()

virtual Bool GetDParameter ( BaseDocument doc,
BaseContainer data,
const DescID id,
GeData t_data,
DESCFLAGS_GET flags 
)
virtual

Called to override the reading of description parameters.
Necessary for parameters that are not simply stored in the tool's container.
Modify the passed t_data if the right id is provided, and set the appropriate flags. Then make sure to include a call to the parent at the end:

return SUPER::GetDParameter(data, id, t_data, flags);
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]idThe ID of the parameter.
[out]t_dataThe parameter data to return. Cinema 4D owns the pointed data.
[in,out]flagsThe flags for the description operation: DESCFLAGS_DESC
Returns
true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in SculptBrushToolData.

§ SetDParameter()

virtual Bool SetDParameter ( BaseDocument doc,
BaseContainer data,
const DescID id,
const GeData t_data,
DESCFLAGS_SET flags 
)
virtual

Called to override the writing of parameters.
Read the passed t_data if the right id was provided, store the data, and set the appropriate flags. Then make sure to include a call to the parent at the end:

return SUPER::SetDParameter(data, id, t_data, flags);
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]idThe ID of the parameter.
[in]t_dataThe parameter data to set. Cinema 4D owns the pointed data.
[in,out]flagsThe flags for the description operation: DESCFLAGS_DESC
Returns
true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in BrushToolData, and SculptBrushToolData.

§ GetDEnabling()

virtual Bool GetDEnabling ( BaseDocument doc,
BaseContainer data,
const DescID id,
const GeData t_data,
DESCFLAGS_ENABLE  flags,
const BaseContainer itemdesc 
)
virtual

Called to decide which description parameters should be enabled or disabled.
Can be used both for parameters that are stored in the tool's description and for dynamic parameters.
Read the passed t_data if the right id was provided, and return true to enable the parameter or false to disable it. Then make sure to include a call to the parent at the end:

return SUPER::GetDEnabling(data, id, t_data, flags, itemdesc);
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]idThe ID of the parameter.
[in]t_dataThe parameter data. Cinema 4D owns the pointed data.
[in]flagsNot used.
[in]itemdescThe parameter's description, encoded to a container as described in Description.
Returns
true if the parameter should be enabled, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in BrushToolData, SculptBrushToolData, and DescriptionToolData.

§ TranslateDescID()

virtual Bool TranslateDescID ( BaseDocument doc,
BaseContainer data,
const DescID id,
DescID res_id,
C4DAtom res_at 
)
virtual

Called by the Attribute Manager for every object and every description ID.
Gives the opportunity to route a description ID in the description of a tool to another one.

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]idThe source description ID.
[out]res_idAssign the target description ID.
[out]res_atAssign the target object.
Returns
true if successful, otherwise false.

Reimplemented in SculptBrushToolData, and DescriptionToolData.

§ Message()

virtual Bool Message ( BaseDocument doc,
BaseContainer data,
Int32  type,
void *  t_data 
)
virtual

Called when a tool receives messages.
For example description messages such as MSG_DESCRIPTION_COMMAND are sent here.

See also
C4DAtom::Message
Note
Some notification messages are automatically passed along to branches: MSG_POINTS_CHANGED, MSG_POLYGONS_CHANGED and MSG_SEGMENTS_CHANGED. This is for convenience and historical reasons.
Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]dataThe tool settings container.
[in]typeThe message type: MSG
[in,out]t_dataThe message data. The sender owns the pointed data.
Returns
true or false depending on the message type.

Reimplemented in BrushToolData, SculptBrushToolData, and DescriptionToolData.

Friends And Related Function Documentation

§ RegisterToolPlugin

Bool RegisterToolPlugin ( Int32  id,
const String str,
Int32  info,
BaseBitmap icon,
const String help,
ToolData dat 
)
friend

Registers a tool plugin.

Parameters
[in]idA unique plugin ID. Must be obtained from http://www.plugincafe.com
[in]strThe name of the plugin.
To affect the order that plugins are displayed in menus add "#$n" as a prefix to this name, where n is a number.
Lower numbers are displayed before higher numbers. If name is "--" it will show up as a menu separator.
[in]infoThe tool plugin info flags: PLUGINFLAG_TOOL PLUGINFLAG
[in]iconThe icon for the tool. The bitmap is copied.
The icon should be of size 32x32, but will be scaled if needed.
It must also be 24 bits and should if possible include an alpha to support pattern backgrounds.
[in]helpThe tool tips and status bar help text for the tool.
When using strings it is advised to use the resources string (.str) files and the GeLoadString() function.
This keeps the plugin easy to localize for any language to support and makes full use of the language features of Cinema 4D.
[in]datThe tool data instance for the plugin. Cinema 4D takes over the ownership of the pointed tool data.
Returns
true if the tool plugin was registered, otherwise false.

§ RegisterPyToolPlugin

Bool RegisterPyToolPlugin ( Int32  id,
const String str,
Int32  info,
BaseBitmap icon,
const String help,
ToolData dat,
GeResource res 
)
friend