Description Resource

Basics

A description resource contains information about the parameters of a node object. Cinema 4D uses this information to let the user edit and animate these parameters.
See Parameter Descriptions for more information.

Each description resource file must be named descriptionname.res and be placed within the description folder of the res folder in the plugin directory.
The file should be structured like this:

CONTAINER descriptionname // Like the filename without ".res"
{
  [NAME]
  [INCLUDE]
  [SHOW/HIDE]

  [Elements and groups]
}

There must also be a corresponding descriptionname.h file in the same directory, that contains an enum with all the IDs used in the description.
It is parsed by Cinema 4D, and can also be included into the C++ code. This is how the file should be structured:

#ifndef DESCRIPTIONNAME_H__
#define DESCRIPTIONNAME_H__

enum
{
  [IDs definition]
};
Note
Generally it is safe to use IDs above 1000 in a local context like this one.

The strings for the description are taken from descriptionname.str in the strings_xx folder for the current language.
Special for description string files is that a shorter name (only displayed in the Attributes Manager) can be optionally specified:

STRINGTABLE descriptionname
{
  NAME descriptionname;

  ELEMENT_1 "Long Name";
  ELEMENT_2 "Long Name" "Short Name";
}

Naming Convention

The descriptions in Cinema 4D are all named with an uppercase prefix and a lower case suffix, for example Tdisplay or Olight.
These are the prefixes used:

PrefixMeaning
DData type.
FScene loader/saver.
GVGraph View.
KEKey.
MMaterial.
OObject.
SESequence.
TTag.
TETrack.
VPVideo post.
XShader.

Name Flag

The name of a description is specified using the flag:

FlagExplanation
NAME stringidDescription name.

stringid should be an identifier from the string resource file that belongs to the description i.e. descriptionname.str.
It is not possible to specify a string directly. This ensures that all text within the description can be localized.

By convention the stringid parameter is always equal to descriptionname. Thus no extra ID need to be inserted into the header file for the name string:

STRINGTABLE descriptionname
{
  NAME descriptionname;

  ...
}

Include Flag

The description of parent nodes can be included with this flag:

FlagExplanation
INCLUDE parentdescParent description.

parentdesc should be the identifier for the parent description. All elements of the parent description are inserted before the elements of the plugin description, in the various groups.

Warning
The parent description must have been registered with Cinema 4D before the plugin description for the lookup to work.
Note
It is recommended to always include at least the base description for the node type plugin, for exampe Tbase for tags.

Show and Hide Flags

If an element in the parent description has been given the HIDDEN flag, or to hide one of its visible elements, the following flags can be used:

FlagExplanation
SHOW elementidShow the element.
HIDE elementidHide the element.

elementid is the identifier for the element to hide or show. When an element is hidden it is not displayed in Cinema 4D. It can still be accessed and animated by plugin code.

Groups

All elements, except for those in sub-descriptions, should be placed in a group. Groups are created like this:

GROUP [groupid]
{
  [DEFAULT 1 | 0;]
  [Elements]
}

groupid is a constant from the descriptionname.h file. It is used for the name of the group in the string table, and as an identifier for the group.
If no group ID is specified the group is just used for structuring.

FlagExplanation
DEFAULT 1 | 0Specifies if the group is initially open (1) or closed (0).
COLUMNS nUsed to create multi-column groups. (See Tcompositing.res.)
MATEDCOLUMNS nNumber of columns in the Material Editor. (See Mmaterial.res.)

Groups can be nested within each other.
They can be also reused for included descriptions, so if there are elements in the parent description within a certain group they will be placed together with elements within that group of the plugin description.

Note
Always check if a parent group can be reused before creating a top-level group in the description.
For each node type there is a corresponding ID_NODETYPEPROPERTIES to use, for example ID_TAGPROPERTIES.

Layout Groups

Normally all elements in a description are placed in a linear layout from top to bottom. With LAYOUTGROUP it is possible to place the elements in columns.
This can be used for example to line up BOOL checkbox elements with their corresponding option. (See Tcompositing.res.)

The LAYOUTGROUP command is used inside a GROUP of its own and always followed by the COLUMNS command:

GROUP
{
  LAYOUTGROUP; COLUMNS n;

  GROUP
  {
    [First column's elements]
  }

  ...

  GROUP
  {
    [nth column's elements]
  }
}

The elements of each column are placed in a standard GROUP inside the layout group.

FlagExplanation
COLUMNS nThe number of columns.
Note
Use LAYOUTGROUP sparingly to avoid making descriptions too wide.

Elements

The elements are the most important part of a description. Each element corresponds to an entry in a node's container. The elements are formatted like this:

ELEMENTTYPE elementid { [Flags] }

or

ELEMENTTYPE elementid
{
  [Flags]
}

elementid must be a constant from the descriptionname.h file. For some element types it is not needed, for instance SEPARATOR.

Element Flags

The element flags vary between the different element types, but these are common:

FlagExplanation
PARENTID paridGroup the element visually with parid.
HIDDENHide the element.
ANIM ON | OFF | MIXSet the animation mode of the parameter:
ONParameter is animatable.
OFFParameter is not animatable.
MIXParameter is animatable, but needs to know the left and right data element.
An example is the Target expression that interpolates the Name parameter. If MIX is specified, the expression can at any time call BaseList2D::GetAnimatedParameter() to get the left, right and mix values.
OPENShow the extended GUI by default.

The flags are separated with semi-colons, for example.

REAL CAMERAOBJECT_TARGETDISTANCE { UNIT METER; MINEX; MIN 0.0; }

GraphView Flags

There are also flags for GraphView:

FlagExplanation
INPORTThis is an in port.
OUTPORTThis is an out port.
STATICPORTThis is a static port.
NEEDCONNECTIONNeeds a connection.
MULTIPLEAllow multiple instances per node.
PORTONLYOnly as port.
CREATEPORT [n]Create this many ports.
MINPORTS nMinimum number of ports.
MAXPORTS nMaximum number of ports.
NOTMOVABLENot movable.
EDITPORTEditable.

Element Types

Here are links to the valid description resource element types:

Custom Data Types

Custom data types, created with CustomDataTypeClass, can be included as elements in descriptions. Their identifier is given by CustomDataTypeClass::GetResourceSym().

Custom GUI

All elements have a default GUI, but it is also possible to specify alternative GUI representations for a data type.
These can be created with the CustomGuiData class. The custom GUI is specified with the CUSTOMGUI flag for each element:

ELEMENTTYPE elementid { [Flags;] CUSTOMGUI id; }

The id is a string name for the representation. For plugin GUIs this is CustomDataTypeClass::GetResourceSym().

Here are some built-in custom GUIs (not listing the defaults):

IDDescription
REALSLIDEREdit field with slider for REAL.
REALSLIDERONLYSlider only for REAL.
LONGSLIDEREdit field with slider for LONG.
MULTISTRINGMultiple line edit field for STRING
SUBDESCRIPTIONForced expanded view of sub channels, for all element types.