内容表

• Basics
• Naming Convention
• Name Flag
• Include Flag
• Show and Hide Flags
• Groups
• Layout Groups
• Elements
• Element Flags
• GraphView Flags
• Element Types
• 自定义数据类型
• Custom GUI

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]
};
						

注意

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 在 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
{
  descriptionname "Description Name";
  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:

Prefix	Meaning
D	Data type.
F	Scene loader/saver.
GV	Graph View.
KE	Key.
M	Material.
O	Object.
SE	Sequence.
T	Tag.
TE	Track.
VP	Video post.
X	Shader.

Name Flag

The name of a description is specified using the flag:

Flag	Explanation
NAME stringid	Description 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:

Flag	Explanation
INCLUDE parentdesc	Parent 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.

警告

The parent description must have been registered with Cinema 4D before the plugin description for the lookup to work.

注意

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:

Flag	Explanation
SHOW elementid	Show the element.
HIDE elementid	Hide 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.

Flag	Explanation
DEFAULT 1 | 0	Specifies if the group is initially open ( 1 ) or closed ( 0 ).
COLUMNS n	Used to create multi-column groups. (See Tcompositing.res .)
MATEDCOLUMNS n	Number of columns in the 材质 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.

注意

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 命令：

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.

Flag	Explanation
COLUMNS n	The number of columns.

注意

使用 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:

Flag	Explanation
PARENTID parid	Group the element visually with parid .
HIDDEN	Hide the element.
ANIM ON | OFF | MIX	Set the animation mode of the parameter:
ON	Parameter is animatable.
OFF	Parameter is not animatable.
MIX	Parameter 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.
OPEN	Show 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:

Flag	Explanation
INPORT	This is an in port.
OUTPORT	This is an out port.
STATICPORT	This is a static port.
NEEDCONNECTION	Needs a connection.
MULTIPLE	Allow multiple instances per node.
PORTONLY	Only as port.
CREATEPORT [n]	Create this many ports.
MINPORTS n	Minimum number of ports.
MAXPORTS n	Maximum number of ports.
NOTMOVABLE	Not movable.
EDITPORT	Editable.

Element Types

Here are links to the valid description resource element types:

• BOOL
• BASETIME
• BUTTON
• COLOR
• DATETIME
• DYNAMIC
• FILENAME
• FONT
• GRADIENT
• HYPERLINK
• IN_EXCLUDE
• LINK
• LONG
• MATRIX
• PRIORITY
• REAL
• SEPARATOR
• SHADERLINK
• SPLINE
• STATICTEXT
• STRING
• TEXTURE
• VECTOR

自定义数据类型

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):

ID	描述
REALSLIDER	Edit field with slider for REAL .
REALSLIDERONLY	Slider only for REAL .
LONGSLIDER	Edit field with slider for LONG .
MULTISTRING	Multiple line edit field for STRING
SUBDESCRIPTION	Forced expanded view of sub channels, for all element types.