c4d.plugins.ToolData

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

See also

Py-LiquidPainter plugin example.

Definition

class c4d.plugins.ToolData

• ToolData.InitTool()
• ToolData.FreeTool()

• ToolData.InitDefaultSettings()

• ToolData.MouseInput()
• ToolData.KeyboardInput()

• ToolData.GetState()
• ToolData.GetCursorInfo()
• ToolData.Draw()

• ToolData.AllocSubDialog()

• ToolData.Message()

Inheritance

• c4d.plugins.BaseData

  • c4d.plugins.ToolData

Methods

ToolData.InitTool(self, doc, data, bt)

Override - Called each time the tool is selected.

Parameters:

• doc (BaseDocument) – The active document.
• data (BaseContainer) – The original tool settings container.
• bt (None) – Currently not used.

Return type:

bool

Returns:

True if there was no error, otherwise False.

ToolData.FreeTool(self, doc, data)

Override - Called each time the user chooses another tool.

Parameters:

• doc (BaseDocument) – The active document.
• data (BaseContainer) – The original tool settings container.

Return type:

bool

Returns:

True if there was no error, otherwise False.

ToolData.InitDefaultSettings(self, doc, data)

Called to let you initialize the default tool settings in data.

Parameters:

• op (BaseDocument) – The currently active document.
• data (BaseContainer) – The tool settings container.

ToolData.MouseInput(self, doc, data, bd, win, msg)

Override - Called when the user clicks with the mouse in any of the editors views.

Parameters:

• doc (BaseDocument) – The currently active document.
• data (BaseContainer) – The tool settings container.
• bd (BaseDraw) – The BaseDraw object for the active editor view.
• win (EditorWindow) – The EditorWindow object for the active editor view.
• msg (BaseContainer) – The original message container.

Return type:

bool

Returns:

False if a problem occured during this function.

ToolData.KeyboardInput(self, doc, data, bd, win, msg)

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

Note

Make sure that you only use this function when the user is somehow working with your plugin, so that other plugins can also use this hook when it’s their turn.

Parameters:

• doc (BaseDocument) – The currently active document.
• data (BaseContainer) – The tool settings container.
• bd (BaseDraw) – The BaseDraw object for the active editor view.
• win (EditorWindow) – The EditorWindow object for the active editor view.
• msg (BaseContainer.) – The original message container.

Return type:

bool

Returns:

False if a problem occured during this function.

ToolData.GetState(self, doc)

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

Parameters: doc (BaseDocument) – The document the tool is being used in. Return type: int Returns: The return flags:

CMD_ENABLED	Enabled.
CMD_VALUE	Checked.

ToolData.GetCursorInfo(self, doc, data, bd, x, y, bc)

Called when the cursor is over editor window to get the state of the mouse pointer. You can set the bubble help and cursor using for example:

bc.SetString(c4d.RESULT_BUBBLEHELP, "My Tools Help");
bc.SetLong(c4d.RESULT_CURSOR, c4d.MOUSE_POINT_HAND);

Parameters:

• doc (BaseDocument) – The currently active document.
• data (BaseContainer.) – The tool settings container.
• bd (BaseDraw) – The BaseDraw object for the active editor view.
• x (float) – The x coordinate of the mouse cursor relative to the top-left of the currently active editor view.
• y (float) – The y coordinate of the mouse cursor relative to the top-left of the currently active editor view.
• bc (BaseContainer) –

  The container to store the result in. Use the following container IDs:

  RESULT_BUBBLEHELP	str	Bubbletext help.
  RESULT_CURSOR	int	Cursortype.

  MOUSE_HIDE	Hide cursor.
  MOUSE_SHOW	Show cursor.
  MOUSE_NORMAL	Normal cursor.
  MOUSE_BUSY	Busy cursor.
  MOUSE_CROSS	Cross cursor.
  MOUSE_QUESTION	Question cursor
  MOUSE_ZOOM_IN	Zoom in cursor.
  MOUSE_ZOOM_OUT	Zoom out cursor.
  MOUSE_FORBIDDEN	Forbidden cursor.
  MOUSE_DELETE	Delete cursor.
  MOUSE_COPY	Copy cursor.
  MOUSE_INSERTCOPY	Insert copy cursor.
  MOUSE_INSERTCOPYDOWN	Insert copy down cursor.
  MOUSE_MOVE	Move cursor.
  MOUSE_INSERTMOVE	Insert move cursor.
  MOUSE_INSERTMOVEDOWN	Insert move cursor.
  MOUSE_ARROW_H	Horizontal cursor.
  MOUSE_ARROW_V	Vertical cursor.
  MOUSE_ARROW_HV	Horizontal and vertical arrow cursor.
  MOUSE_POINT_HAND	Point hand cursor.
  MOUSE_MOVE_HAND	Move hand cursor.
  MOUSE_IBEAM	I-beam cursor.
  MOUSE_SELECT_LIVE	Live selection cursor.
  MOUSE_SELECT_FREE	Free selection cursor.
  MOUSE_SELECT_RECT	Rectangle selection cursor.
  MOUSE_SELECT_POLY	Polygon selection cursor.
  MOUSE_SPLINETOOLS	Spline tools cursor.
  MOUSE_EXTRUDE	Extrude cursor.
  MOUSE_NORMALMOVE	Normal move cursor.
  MOUSE_ADDPOINTS	Add points cursor.
  MOUSE_ADDPOLYGONS	Add polygons cursor.
  MOUSE_BRIDGE	Bridge cursor.
  MOUSE_MIRROR	Mirror cursor.
  MOUSE_PAINTMOVE	Paint move cursor.
  MOUSE_PAINTSELECTRECT	Paint select rectangle cursor.
  MOUSE_PAINTSELECTCIRCLE	Paint select circle cursor.
  MOUSE_PAINTSELECTPOLY	Paint select polygon cursor.
  MOUSE_PAINTSELECTFREE	Paint select free cursor.
  MOUSE_PAINTMAGICWAND	Paint magic wand cursor.
  MOUSE_PAINTCOLORRANGE	Paint color range cursor.
  MOUSE_PAINTFILL	Paint fill cursor.
  MOUSE_PAINTPICK	Paint pick cursor.
  MOUSE_PAINTBRUSH	Paint brush cursor.
  MOUSE_PAINTCLONE	Paint clone cursor.
  MOUSE_PAINTTEXT	Paint text cursor.
  MOUSE_PAINTCROP	Paint crop cursor.
  MOUSE_PAINTLINE	Paint line cursor.
  MOUSE_PAINTPOLYSHAPE	Paint polygon shape cursor.

Return type:

bool

Returns:

False if a problem occured during this function.

ToolData.Draw(self, doc, data, bd, bh, bt, flags)

Called when the editor view is updated so you can display graphics for your tool in the view.

Parameters:

• doc (BaseDocument) – The active document.
• data (BaseContainer) – The tool settings container.
• bd (BaseDraw) – The BaseDraw object for the active editor view.
• bh (PyCObject) – Private - internal helper
• flags (int) –

  The flags are:

  TOOLDRAWFLAGS_0	No flags.
  TOOLDRAWFLAGS_INVERSE_Z	This flag is used for inverse Z-buffer use, with this mode the drawing engine of CINEMA 4D will only draw elements if they are further away from the camera than other objects. This is mostly used for helplines (such as the semitransparent axis inside of objects). This mode only works when all objects are drawn so it should be the passed last.
  TOOLDRAWFLAGS_HIGHLIGHT	Highlight mode.

• bt (None) – Currently not used

Return type:

int

Returns:

The values for this are:

TOOLDRAW_0	None
TOOLDRAW_HANDLES	The active objects handles will be drawn.
TOOLDRAW_AXIS	The active objects axes will be drawn.
TOOLDRAW_HIGHLIGHTS	The highlights will be drawn.

ToolData.AllocSubDialog(self, bc)

Called to get a GUI for the Active Tool window. Return an instance of your tool’s dialog.

Parameters: bc (BaseContainer) – Currently not used. Return type: SubDialog Returns: The allocated sub dialog.

ToolData.Message(self, doc, data, type, t_data)

Lets you get messages for the tool. For example description messages such as MSG_DESCRIPTION_COMMAND are sent here.

Parameters:

• doc (BaseDocument) – The current document.
• data (BaseContainer) – The current tool data.
• type (int) –

  The message ID:

  MSG_POINTS_CHANGED	The points have changed. The corresponding data is VariableChanged.
  MSG_POLYGONS_CHANGED	The polygons have changed. The corresponding data is VariableChanged.
  MSG_UPDATE	Must be sent if the bounding box has to be recalculated. (Otherwise you can use MSG_CHANGE.)
  MSG_SMALLUPDATE	Part of the object has changed that needs no cache rebuilding. Note: This message should be used very carefully, it is there for (small) performance enhancements, for example if a polygon selection is changed then the caches needn’t be rebuilt, so MSG_SMALLUPDATE can be sent.
  MSG_CHANGE	Must be sent if any object data (except for the matrix) has been changed.
  MSG_BASECONTAINER	Message with a container, for example from a C.O.F.F.E.E. plugin. The corresponding data is BaseContainer.
  MSG_SEGMENTS_CHANGED	The segments have changed. The corresponding data is VariableChanged.
  MSG_FILTER	A message filter that lets you block C4DAtom.MultiMessage() calls. The corresponding data is MessageFilter. Return True to let the message pass and False to block it!
  MSG_TRANSFERGOALS	Internal message!
  MSG_DESCRIPTION_INITUNDO	Allows elements to create undo actions for the following parameter changes in the attributes manager. This is already automatically handled for keys, tags, objects etc. The corresponding data is DescriptionInitUndo.
  MSG_DESCRIPTION_CHECKUPDATE	Allows elements to determine the type of refresh after a parameter has been changed in the Active manager. This is already automatically handled for keys, tags, objects etc. The corresponding data is DescriptionCheckUpdate. Note: Currently this message is completely handled by all baseclasses. Most plugins won’t need to modify the message data. It’s more interesting to start some update action - e.g. deleting data that will be rebuilt with the next access.
  MSG_DESCRIPTION_COMMAND	Sent by for example BUTTON (description element). See example below.
  MSG_DESCRIPTION_POPUP	Allows popup menu handling in the Attribute Manager. The corresponding data is DescriptionPopup.
  MSG_DESCRIPTION_POSTSETPARAMETER	After a SetParameter() call to an atom element this message is sent to the object. The corresponding data is DescriptionPostSetValue.
  MSG_DESCRIPTION_VALIDATE	Allows you to update dependencies or to check for invalid values after a parameter has been changed (For example: the light’s inner radius always must be smaller than the light’s outer radius - so this routine checks for it and corrects it). The corresponding data is DescriptionValidate.
  MSG_EDIT	Allows elements to do some action if the user edits the element (doubleclick e.g. in object manager).
  MSG_MENUPREPARE	Allows tags, objects, shaders etc. to do some setup work when called from the menu. The corresponding data is the current BaseDocument.
  MSG_RETRIEVEPRIVATEDATA	A generic private message to retrieve data from an object. Specific for every type of object so no public documentation available. The corresponding data is RetrievePrivateData.
  MSG_DESCRIPTION_REMOVE_ENTRY	Tells the node to remove a description entry. The corresponding data is DescriptionCommand.
  MSG_DESCRIPTION_EDIT_ENTRY	Tells the node to edit a description entry. The corresponding data is DescriptionCommand.
  MSG_DESCRIPTION_CHECKDRAGANDDROP	Asks the node if a drag and drop onto for example a LINK (description element) field should be accepted. The corresponding data is DescriptionCheckDragAndDrop.
  MSG_DESCRIPTION_GETBITMAP	Queries the object for updated bitmaps for BitmapButtonCustomGui elements in the description. (E.g. the lens flare preview.) The corresponding data is DescriptionGetBitmap.
  MSG_DESCRIPTION_GETOBJECTS	Private.
  MSG_DESCRIPTION_USERINTERACTION_END	End of user interaction.
  MSG_DESCRIPTION_GETINLINEOBJECT	Sent by the Attribute Manager to the object. The object can check for a description ID and return the linked objects in the atom array. The corresponding data is DescriptionInlineObjectMsg.
  MSG_MOVE_FINISHED	Sent after a handle or the object has been moved.
  MSG_MOVE_START	Sent before a handle or the object has been moved.
  MSG_EDITABLE_END	Private.
  MSG_GETCUSTOMICON	Every atom can return a custom icon with this message. The corresponding data is GetCustomIconData.
  MSG_MATERIALDRAGANDDROP	Received by a material upon dropping an instance of the material onto an object. The material can choose to create a tag of its own, or trigger other actions, instead of letting CINEMA 4D create a normal material assignment. The corresponding data is MaterialDragAndDrop. For example Sketch and Toon creates its own type of tag and returns it in result. CINEMA 4D creates the undo for it and activates it. Inserting the tag is done by the material.
  MSG_DRAGANDDROP	Received when something is dropped on it. The corresponding data is DragAndDrop.
  MSG_INITIALCHANNEL	See HandleInitialChannel().
  MSG_DOCUMENTINFO	Sent as broadcast message to the document when it its loaded, saved etc. The corresponding data is DocumentInfoData. (See the type member for more information about when the message is sent.)
  MSG_GETSELECTION	Private.
  MSG_MULTI_RENDERNOTIFICATION	A document and all of its elements receive this message before a render starts. The corresponding data is RenderNotificationData.
  MSG_MULTI_MARKMATERIALS	When data is None this is sent to plugin nodes to let them mark the materials that they use. Otherwise the message is sent to let you translate you material links, for example when a material is replaced, and then the corresponding structure is MarkMaterials. (An example for both cases is included on the MarkMaterials page.)
  MSG_MULTI_DOCUMENTCLONED	The document has been cloned.
  MSG_MULTI_DOCUMENTIMPORTED	After a C4D document has been loaded this message is sent to the document (and all children structures). The corresponding data is DocumentImported.
  MSG_MULTI_SETNEWMARKERS	Private.
  MSG_MULTI_CLEARSUGGESTEDFOLDER	Objects have to remove absolute paths (only if they support MSG_GETALLASSETS). Both are important for SaveProject to work and to collect all items.
  MSG_TRANSLATE_POINTS	Sent by the modeling core to let tags etc. update after point changes. The corresponding data is TranslationMaps.
  MSG_TRANSLATE_POLYGONS	Sent by the modeling core to let tags etc. update after polygon changes. The corresponding data is TranslationMaps.
  MSG_TRANSLATE_NGONS	Sent by the modeling core to let tags etc. update after N-gon changes. The corresponding data is TranslationMaps.
  MSG_TRANSLATE_SEGMENTS	Sent by the modeling core to let tags etc. update after segment changes. The corresponding data is TranslationMaps.
  MSG_PRETRANSLATE_POINTS	Sent before MSG_TRANSLATE_POINTS, before the changes are actually carried out. The corresponding data is TranslationMaps.
  MSG_PRETRANSLATE_POLYGONS	Sent before MSG_TRANSLATE_POLYGONS, before the changes are actually carried out. The corresponding data is TranslationMaps.
  MSG_PRETRANSLATE_NGONS	Sent before MSG_TRANSLATE_NGONS, before the changes are actually carried out. The corresponding data is TranslationMaps.
  MSG_PRETRANSLATE_SEGMENTS	Sent before MSG_TRANSLATE_SEGMENTS, before the changes are actually carried out. The corresponding data is TranslationMaps.
  MSG_UPDATE_NGONS	Should be sent if points are changed and any N-gons need updating. CINEMA 4D will then update the N-gons, if the user has this option enabled.
  MSG_DOCUMENT_MODE_CHANGED	Sent to the active tool plugin during BaseDocument.SetMode().
  MSG_TOOL_RESTART	Private. (Handles the tool description apply behaviour after mouse clicks.)
  MSG_DEFORMMODECHANGED	Private.
  MSG_ANIMATE	Sent to objects after they have been animated.
  MSG_CALCMEMUSAGE	Private.
  MSG_SCALEDOCUMENT	Tells the document that another document with different scale has been merged. The corresponding data is MessageScaleDocument.
  MSG_GET_INHERITANCECONTAINER	Private.
  MSG_SOFTTAG_UPDATE	Private.

• t_data (any) – Depends on type.

Return type:

bool

Returns:

Depends on the message type.