c4d.plugins.ToolData

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

See also

Py-LiquidPainter plugin example.

Inheritance

Methods

ToolData.InitTool(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(doc, data)

Override - Called each time the user chooses another tool.

Parameters:
ToolData.InitDefaultSettings(doc, data)

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

Parameters:
ToolData.MouseInput(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(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(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(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 (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(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 (PyCObject) – Private - internal 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(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(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(doc, data, description, flags)

New in version R18.011.

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

Note

If only a description resource is used it is not needed to overload 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(doc, data, id, flags)

New in version R18.011.

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.

Note

If only a description resource is used it is not needed to overload 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(doc, data, id, t_data, flags)

New in version R18.011.

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.

Note

If only a description resource is used it is not needed to overload 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(doc, data, id, t_data, flags, itemdesc)

New in version R18.011.

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)
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(doc, data, id)

New in version R18.011.

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.
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.