c4d.plugins.ToolData

class c4d.plugins.ToolData

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

See also

Py-LiquidPainter plugin example.

Methods Signatures

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

Override - Called each time the tool is selected.

ToolData.FreeTool(self, doc, data)

Override - Called each time the user chooses another tool.

ToolData.InitDefaultSettings(self, doc, data)

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

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

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

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

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

ToolData.GetState(self, doc)

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

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

Called when the cursor is over editor window to get the state of the mouse pointer.

ToolData.Draw(self, doc, data, bd, ...)

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

ToolData.AllocSubDialog(self, bc)

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

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

Called when the tool receives messages.

ToolData.GetDDescription(self, doc, data, ...)

Called to add parameters to the description for the tool. Modify the passed description as needed and return the appropriate flags.

ToolData.GetDParameter(self, doc, data, id, flags)
Called to override the reading of description parameters. Necessary for parameters that are not simply stored in the tool’s container e.g. class members.

ToolData.SetDParameter(self, doc, data, id, ...)

Called to override the writing of parameters. Read the passed t_data if the right id is provided, store the data and return the appropriate flags.

ToolData.GetDEnabling(self, doc, data, id, ...)
Called to let decide which parameters should be enabled or disabled (ghosted).

ToolData.TranslateDescID(self, doc, data, id)
Called by the Attribute Manager for every tool and every description ID.

Inheritance

Parent Class:

Methods Documentation

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

Override - Called each time the tool is selected.

Parameters
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
ToolData.InitDefaultSettings(self, doc, data)

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

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

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

Parameters
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 is their turn.

Parameters
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 (c4d.documents.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.

See also

Py-LiquidPainter change the cursor and the bubble help string.

Parameters

  • doc (c4d.documents.BaseDocument) – The currently active document.

  • data (c4d.BaseContainer) – The tool settings container.

  • bd (c4d.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 (c4d.BaseContainer) –

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

    RESULT_BUBBLEHELP_TITLE

    str

    Bubble help text title. Printed in bold for the bubble help, not visible in the status bar.

    RESULT_BUBBLEHELP

    str

    Bubble text help.

    RESULT_CURSOR

    int

    Mouse cursor: MOUSE.

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 (c4d.documents.BaseDocument) – The active document.

  • data (c4d.BaseContainer) – The tool settings container.

  • bd (c4d.BaseDraw) – The BaseDraw object for the active editor view.

  • bh (c4d.plugins.BaseDrawHelp) – The helper for the editor’s view. The caller owns the pointed base draw helper.

  • flags (int) –

    The flags are:

    TOOLDRAWFLAGS_NONE

    None.

    TOOLDRAWFLAGS_INVERSE_Z
    Inverse Z-buffer mode. If set, 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 help lines (such as the semi-transparent axis inside of objects). .. note:: This mode only works when all objects are drawn so it should be passed last.

    TOOLDRAWFLAGS_HIGHLIGHT

    Highlight mode.

  • bt (c4d.threading.BaseThread) – The calling thread.

Return type

int

Returns

The values for this are:

TOOLDRAW_NONE

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 (c4d.BaseContainer) – Currently not used.

Return type

c4d.gui.SubDialog

Returns

The allocated sub dialog.

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

Called when the tool receives messages.

See also

MSG for the information on the messages type, data and input/output.

Parameters
Return type

bool

Returns

Depends on the message type.

ToolData.GetDDescription(self, doc, data, description, flags)

Called to add parameters to the description for the tool. Modify the passed description as needed and return the appropriate flags.

New in version R18.011.

Note

If only a description resource is used it is not needed to overload GetDDescription().

See also

NodeData.GetDDescription()

Parameters

  • doc (c4d.documents.BaseDocument) – The active document.

  • data (c4d.BaseContainer) – The tool settings container.

  • description (c4d.Description) – The description to add the parameters to.

  • flags (int) –

    The flags for the description operation:

    DESCFLAGS_DESC_NONE

    None.

    DESCFLAGS_DESC_RESOLVEMULTIPLEDATA

    Private and unused.

    DESCFLAGS_DESC_LOADED

    Set if elements have been added to the description, either by loading or manual addition.

    DESCFLAGS_DESC_RECURSIONLOCK

    Private.

    DESCFLAGS_DESC_DONTLOADDEFAULT

    If set, the object description will also contain the tag’s descriptions (as sub-containers).

    DESCFLAGS_DESC_MAPTAGS

    If specified, the object description will also contain the tag’s descriptions (as sub-containers).

    DESCFLAGS_DESC_NEEDDEFAULTVALUE

    Set if “Reset to Default” was called by the user.

Return type

bool or tuple(bool, int)

Returns

One of these options:

bool: True if successful, otherwise False. Useful in error state to only return False.
tuple(bool, int): The status (True if successful, otherwise False) and description flags (DESCFLAGS_DESC).

ToolData.GetDParameter(self, doc, data, id, flags)
Called to override the reading of description parameters. Necessary for parameters that are not simply stored in the tool’s container e.g. class members.
Return the parameter data and the appropriate flags if the right id is provided.

New in version R18.011.

Note

If only a description resource is used it is not needed to overload GetDParameter().

See also

NodeData.GetDParameter()

Parameters

  • doc (c4d.documents.BaseDocument) – The active document.

  • data (c4d.BaseContainer) – The tool settings container.

  • id (c4d.DescID) – The ID of the parameter.

  • flags (int) –

    The flags for the description operation:

    DESCFLAGS_GET_NONE

    None.

    DESCFLAGS_GET_PARAM_GET

    Parameter retrieved.

    DESCFLAGS_GET_NO_GEDATADEFAULTVALUE

    If set, the C++ GeData default type will not be initialized for C4DAtom.GetParameter().

    DESCFLAGS_GET_NO_GLOBALDATA

    Private.

Return type

bool or tuple(bool, any, int)

Returns

One of these options:

bool: True if successful, otherwise False. Useful in error state to only return False.
tuple(bool, any, int): The status (True if successful, otherwise False), parameter data and description flags (DESCFLAGS_DESC).

ToolData.SetDParameter(self, doc, data, id, t_data, flags)

Called to override the writing of parameters. Read the passed t_data if the right id is provided, store the data and return the appropriate flags.

New in version R18.011.

Note

If only a description resource is used it is not needed to overload SetDParameter().

See also

NodeData.SetDParameter()

Parameters

  • doc (c4d.documents.BaseDocument) – The active document.

  • data (c4d.BaseContainer) – The tool settings container.

  • id (c4d.DescID) – The ID of the parameter.

  • t_data (any) – The parameter data to set.

  • flags (int) –

    The flags for the description operation:

    DESCFLAGS_SET_NONE

    None.

    DESCFLAGS_SET_PARAM_SET

    Parameter set.

    DESCFLAGS_SET_USERINTERACTION

    Set when the GUI is calling SetParameter(). This is the only time when SetParameter() is allowed to use user interaction elements (e.g. open dialogs, display messages etc.).

    DESCFLAGS_SET_DONTCHECKMINMAX

    No check is internally done if the parameter passed is within the [min/max] range of the description, to save some time.

    DESCFLAGS_SET_DONTAFFECTINHERITANCE

    No parameter inheritance, for render settings and post effects only.

    DESCFLAGS_SET_FORCESET

    Forces the set value without GetParameter()/Compare. Use only for calls where for sure the value was changed!

    DESCFLAGS_SET_DONTFREESPLINECACHE

    Private. .. versionadded:: R16.038

    DESCFLAGS_SET_INDRAG

    Gadget (e.g. Slider) in dragging mode (not finished). Only used when DESCFLAGS_SET_USERINTERACTION is set. .. versionadded:: R17.053

Return type

bool or tuple(bool, int)

Returns

One of these options:

bool: True if successful, otherwise False. Useful in error state to only return False.
tuple(bool, int): The status (True if successful, otherwise False) and description flags (DESCFLAGS_DESC).

ToolData.GetDEnabling(self, doc, data, id, t_data, flags, itemdesc)
Called to let decide which parameters should be enabled or disabled (ghosted).
This can be used both for parameters that are stored in the tool’s container and for custom parameters.

Just read the passed t_data if the right id was provided, and return True to enable the parameter or False to disable it depending on the value.

And if the passed id element is not processed, include a call to the base class method as last return.
return ToolData.GetDEnabling(self, doc, data, id, t_data, flags, itemdesc)

New in version R18.011.

See also

NodeData.GetDEnabling()

Parameters
Return type

bool

Returns

True if the parameter should be enabled, otherwise False.

Note

It is recommended to include a call to the base class method as last return.

ToolData.TranslateDescID(self, doc, data, id)
Called by the Attribute Manager for every tool and every description ID.
Gives the opportunity to route a description ID in the description of a tool to another one.

New in version R18.011.

See also

NodeData.TranslateDescID()

Parameters
Return type

bool or tuple(bool, DescID, C4DAtom)

Returns

One of these options:

bool: True if successful, otherwise False. Useful in error state to only return False.
tuple(bool, DescID, C4DAtom): The status (True if successful, otherwise False), target description ID and tool.