Description Settings Manual

About

A parameter description includes the type of a parameter and some additional information. Such a parameter description is stored in a BaseContainer. The different settings are accessed using the IDs described on this page. These settings define how the parameter behaves and how it is displayed in the Attribute Manager.

Such parameter descriptions are handled in the following situations:

Parameters Types

While certain settings apply to all parameter types, others are specific to certain parameter types. With this utility function one can create a BaseContainer with the correct default settings:

These are the default Cinema 4D parameter and data types. For plugin data types the plugin ID must be used.

Note
Do not confuse these types with DA_TYPES (see GeData Manual).
// This example adds a new Boolean parameter
// to the given Description in NodeData::GetDDescription().
const DescID cid = ConstDescID(DescLevel(ID_BOOL, DTYPE_BOOL, 0));
const DescID* const singleid = description->GetSingleDescID();
// If a SingleDescID is set, check if the cid is part of it.
// This is a check if only the description of the given SingleDescID
// should be set or not.
if (singleid == nullptr || cid.IsPartOf(*singleid, nullptr))
{
settings.SetString(DESC_NAME, "Boolean Parameter"_s);
// check if the new parameter description could be inserted
if (!description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES))))
return;
}
BaseContainer GetCustomDataTypeDefault(Int32 type)
Definition: c4d_basecontainer.h:48
void SetString(Int32 id, const maxon::String &s)
Definition: c4d_basecontainer.h:651
Definition: lib_description.h:355
Bool IsPartOf(const DescID &cmp, Int32 *pos) const
@ DESC_NAME
String Name for standalone use.
Definition: lib_description.h:91
@ DTYPE_BOOL
GV Bool. ID_GV_DATA_TYPE_BOOL.
Definition: lib_description.h:75
#define ConstDescID(...)
Definition: lib_description.h:594
@ ID_OBJECTPROPERTIES
Definition: obase.h:56
Represents a level within a DescID.
Definition: lib_description.h:298

Other parameter types are

Other data types are defined as custom data types like CUSTOMDATATYPE_BITMAPBUTTON etc.

// This example adds both a button and a BitmapButton to the given Description.
{
// create a button
settings.SetString(DESC_NAME, "Button"_s);
description->SetParameter(buttonID, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));
}
{
// create a bitmap button
settings.SetString(DESC_NAME, "Bitmap Button"_s);
settings.SetInt32(BITMAPBUTTON_BUTTON, true); // button acts like a button
settings.SetInt32(BITMAPBUTTON_ICONID1, IDM_DELETE); // use the "Delete" icon
settings.SetInt32(DESC_ALIGNLEFT, 1); // don't scale
description->SetParameter(bitmamButtionID, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));
}
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:587
#define CUSTOMDATATYPE_BITMAPBUTTON
Bitmap button custom data ID.
Definition: customgui_bitmapbutton.h:28
#define CUSTOMGUI_BITMAPBUTTON
Bitmap button custom GUI ID.
Definition: customgui_bitmapbutton.h:25
#define BITMAPBUTTON_BUTTON
Definition: customgui_bitmapbutton.h:35
#define BITMAPBUTTON_ICONID1
Int32 Registered icon bitmap ID. On state for toggle buttons.
Definition: customgui_bitmapbutton.h:47
#define CUSTOMGUI_BUTTON
Button.
Definition: lib_description.h:223
#define MAXON_SCOPE
Definition: apibase.h:2886
@ DESC_ALIGNLEFT
Bool Align element left.
Definition: lib_description.h:137
@ DESC_CUSTOMGUI
Int32 The ID of the GUI for this element. Either a custom ID or one of: CUSTOMGUI
Definition: lib_description.h:125
@ DTYPE_BUTTON
Button.
Definition: lib_description.h:61
#define IDM_DELETE
Delete.
Definition: ge_prepass.h:3872

Groups

Parameters are organized in parameter groups. These groups are used to define the structure and the layout of the parameters.

// This example creates a new parameter group with two sub-parameters.
// define the group
{
const DescID groupID = ConstDescID(DescLevel(ID_GROUP, DTYPE_GROUP, 0));
settings.SetString(DESC_NAME, "New Group"_s);
settings.SetInt32(DESC_COLUMNS, 2); // group has two columns
settings.SetInt32(DESC_DEFAULT, 1); // group is unfolded by default
settings.SetInt32(DESC_SCALEH, 1); // group is scaled horizontally
description->SetParameter(groupID, settings, ConstDescID(DescLevel(0)));
}
// add the first child parameter
{
const DescID cid = ConstDescID(DescLevel(ID_STRING_A, DTYPE_STRING, 0));
settings.SetString(DESC_NAME, "Parameter A"_s);
settings.SetInt32(DESC_SCALEH, 1);
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_GROUP)));
}
// add the second child parameter
{
const DescID cid = ConstDescID(DescLevel(ID_STRING_B, DTYPE_STRING, 0));
settings.SetString(DESC_NAME, "Parameter B"_s);
settings.SetInt32(DESC_SCALEH, 1);
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_GROUP)));
}
}
@ DESC_DEFAULT
Int32/Float/Vector Default numeric value.
Definition: lib_description.h:120
@ DESC_SCALEH
Bool Scale element horizontally.
Definition: lib_description.h:135
@ DESC_COLUMNS
Int32 Number of columns for layout groups (DTYPE_GROUP).
Definition: lib_description.h:127
@ DTYPE_STRING
String.
Definition: lib_description.h:72
@ DTYPE_GROUP
Group.
Definition: lib_description.h:56

A parameter is typically part of a group:

The group IDs of specific elements are defined in the corresponding header files like ID_OBJECTPROPERTIES in Obase.h.

// This example reads the DESC_PARENTGROUP parameter of a given description BaseContainer.
const GeData parentid = bc->GetData(DESC_PARENTGROUP);
// check if the GeData stores a DescID
if (parentid.GetType() == CUSTOMDATATYPE_DESCID)
{
// get DescID
const DescID* const descID = parentid.GetCustomDataType<DescID>();
if (descID == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// print ID
const Int32 id = descID->operator[](-1).id;
ApplicationOutput("Parent Group ID: " + String::IntToString(id));
}
Definition: c4d_gedata.h:83
const DATATYPE * GetCustomDataType() const
Definition: c4d_gedata.h:542
Int32 GetType() const
Definition: c4d_gedata.h:436
const maxon::Data & GetData() const
Definition: c4d_gedata.h:535
static String IntToString(Int32 v)
Definition: c4d_string.h:497
maxon::Int32 Int32
Definition: ge_sys_math.h:56
@ DESC_PARENTGROUP
Int32/Parent ID.
Definition: lib_description.h:117
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
#define CUSTOMDATATYPE_DESCID
DescID custom data type ID.
Definition: lib_description.h:272

A row of a group can be filled with dummy elements so that the next elements start in a new row:

  • DESC_NEWLINE: The element in question is used as a "line break". Typically used with a static text element.
// This example adds a static text element to the given group.
// Using DESC_NEWLINE this element will fill the remainder of the row
// so that the next added elements are placed in the next row.
const DescID cid = ConstDescID(DescLevel(ID_NEWLINE, DTYPE_STATICTEXT, 0));
settings.SetString(DESC_NAME, ""_s);
settings.SetInt32(DESC_SCALEH, 1);
settings.SetBool(DESC_NEWLINE, true);
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_GROUP)));
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:580
@ DESC_NEWLINE
Bool Line break.
Definition: lib_description.h:139
@ DTYPE_STATICTEXT
Static text.
Definition: lib_description.h:64

Parent Parameters

A parameter can be a parent parameter of another parameter. The child parameter is hidden until the user clicks on a little arrow.

// This example adds two parameter descriptions.
// The first parameter acts as a parent for the second parameter.
const DescID parentID = ConstDescID(DescLevel(ID_PARENT, DTYPE_STRING, 0));
// add the parent parameter
{
settings.SetString(DESC_NAME, "Parent"_s);
description->SetParameter(parentID, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));
}
// add the child parameter
{
const DescID cid = ConstDescID(DescLevel(ID_CHILD, DTYPE_STRING, 0));
settings.SetString(DESC_NAME, "Child"_s);
GeData parentIdData;
parentIdData.SetCustomDataType<DescID>(parentID);
settings.SetData(DESC_PARENT_COLLAPSE, parentIdData);
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));
}
Bool SetData(Int32 id, const GeData &n)
Definition: c4d_basecontainer.h:274
void SetCustomDataType(const DATATYPE &v)
Definition: c4d_gedata.h:747
#define NOTOK
Definition: ge_sys_math.h:263
@ DESC_PARENT_COLLAPSE
Int32 Parent collapse ID.
Definition: lib_description.h:143

Layout

The parameter description includes settings that define how a group or parameter should be scaled in the Attribute Manager.

Visibility

The parameter description also includes information on how the parameter is displayed:

Note
To enable or disable a parameter in the Attribute Manager one must implement NodeData::GetDEnabling(), see NodeData::GetDEnabling() Manual.
// This example creates and configures the BaseContainer for a float parameter description.
settings.SetString(DESC_NAME, "Float Value"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_REALSLIDER); // use this custom GUI
settings.SetInt32(DESC_NOGUISWITCH, true); // do not allow to change the custom GUI
#define CUSTOMGUI_REALSLIDER
Float edit field with slider.
Definition: lib_description.h:208
@ DESC_NOGUISWITCH
Bool Disables GUI switching for this description element.
Definition: lib_description.h:166
@ DTYPE_REAL
Float
Definition: lib_description.h:68
// This example creates a shader link parameter description that cannot be unfolded.
settings.SetString(DESC_NAME, "Shader"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_TEXBOX); // use the tex box gui to handle shaders
settings.SetBool(DESC_SHADERLINKFLAG, true); // is a shader link
// don't unfold the GUI in the Attribute Manager
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));
#define CUSTOMGUI_TEXBOX
Shader link custom GUI ID.
Definition: customgui_texbox.h:18
@ DESC_FORBID_INLINE_FOLDING
Bool Instructs the Attribute Manager to not allow expanding inline objects for entry.
Definition: lib_description.h:144
@ DESC_SHADERLINKFLAG
Bool Specifies that this element is a shader link. (Only if datatype==DTYPE_BASELISTLINK....
Definition: lib_description.h:165
@ DTYPE_BASELISTLINK
BaseLink.
Definition: lib_description.h:74

The settings of a custom GUI also have to be stored in the BaseContainer.

// This example configures a DateTime description so that the used
// custom GUI only displays the calendar.
settings.SetString(DESC_NAME, "Date"_s);
settings.SetBool(DATETIME_TIME_CONTROL, false); // don't display clock
settings.SetBool(DATETIME_DATE_CONTROL, true); // display calendar
settings.SetBool(DATETIME_NOW_BUTTON, true); // display "Today" button
#define DATETIME_DATA
DateTime custom data ID.
Definition: customgui_datetime.h:23
#define DATETIME_GUI
DateTime custom GUI ID.
Definition: customgui_datetime.h:20
#define DATETIME_DATE_CONTROL
Bool true, if it is a calendar.
Definition: customgui_datetime.h:29
#define DATETIME_TIME_CONTROL
Bool true, if it is a clock.
Definition: customgui_datetime.h:28
#define DATETIME_NOW_BUTTON
Bool true, to add "Now" button.
Definition: customgui_datetime.h:30

Name

The name of a parameter is displayed in the Attribute Manager or other contexts:

  • DESC_NAME: The parameter name for standalone use.
  • DESC_SHORT_NAME: The short name, displayed in the Attribute Manager.
  • DESC_IDENT: The resource identifier, e.g. "ID_BASEOBJECT_REL_POSITION". This value is typically read-only.
  • DESC_IDENT_ORIGIN: The resource identifier, e.g. "ID_BASEOBJECT_REL_POSITION". This value is typically read-only.
// This example configures the names for a float parameter description.
settings.SetString(DESC_NAME, "Parameter Name"_s); // displayed in the Xpresso "Object" node
settings.SetString(DESC_SHORT_NAME, "Short Name"_s); // displayed in the Attribute Manager
@ DESC_SHORT_NAME
String Short name, for attributes dialog.
Definition: lib_description.h:92

Animation

One can enable or disable if a parameter should be animateable:

// This example disables animation for the new parameter description.
settings.SetString(DESC_NAME, "Non Animate"_s);
settings.SetInt32(DESC_ANIMATE, DESC_ANIMATE_OFF); // parameter not animateable
@ DESC_ANIMATE
Int32 Animation mode:
Definition: lib_description.h:104
@ DESC_ANIMATE_OFF
Parameter is not animatable.
Definition: lib_description.h:105

Values

For specific parameter types certain values can be set:

For DTYPE_REAL, DTYPE_LONG and DTYPE_VECTOR parameters:

// This example uses a slider to display a float parameter.
// The range of the parameter and of the slider are configured.
settings.SetString(DESC_NAME, "Slider"_s);
settings.SetFloat(DESC_MIN, -1.0); // min value: -100%
settings.SetFloat(DESC_MAX, 2.0); // max value: 200%
settings.SetFloat(DESC_MINSLIDER, 0.0); // min slider: 0%
settings.SetFloat(DESC_MAXSLIDER, 1.0); // max slider: 100%
settings.SetFloat(DESC_STEP, 0.02); // step size 2%
settings.SetInt32(DESC_UNIT, DESC_UNIT_PERCENT); // display percent
void SetFloat(Int32 id, Float r)
Definition: c4d_basecontainer.h:615
@ DESC_MAXSLIDER
Int32/Float/Vector Maximum value for slider.
Definition: lib_description.h:133
@ DESC_MINSLIDER
Int32/Float/Vector Minimum value for slider.
Definition: lib_description.h:132
@ DESC_STEP
Int32/Float/Vector The step for the edit field arrows.
Definition: lib_description.h:103
@ DESC_MIN
Int32/Float/Vector Minimum value.
Definition: lib_description.h:99
@ DESC_UNIT
Int32 Unit for DTYPE_VECTOR:
Definition: lib_description.h:110
@ DESC_UNIT_PERCENT
FORMAT_PERCENT
Definition: lib_description.h:113
@ DESC_MAX
Int32/Float/Vector Maximum value.
Definition: lib_description.h:100

DTYPE_REAL and DTYPE_VECTOR can display values with a given unit:

Note
These are the same formats as used with GeDialog::SetFloat().
// This example configures a float parameter to display "meters" as a unit.
// This parameter won't be scaled when the object is scaled.
settings.SetString(DESC_NAME, "Meters"_s);
settings.SetInt32(DESC_UNIT, DESC_UNIT_METER); // display "meters"
// don't scale this parameter when the host BaseObject is scaled
settings.SetBool(DESC_FORBID_SCALING, true);
@ DESC_UNIT_METER
FORMAT_METER
Definition: lib_description.h:115
@ DESC_FORBID_SCALING
Bool Prevents auto-scaling of the parameter with the scale tool (for DESC_UNIT_METER).
Definition: lib_description.h:145

The values selectable in a drop down parameter (based on DTYPE_LONG) are stored in sub-containers:

// This example creates a drop down field with three items.
// a drop down is a long parameter with a custom GUI
settings.SetString(DESC_NAME, "Drop Down"_s);
// add cycle elements
items.SetString(0, "Item 1"_s);
items.SetString(1, "Item 2"_s);
items.SetString(2, "Item 3"_s);
// add cycle icons
icons.SetInt32(0, 5159); // use "Cube" icon
icons.SetInt32(1, IDM_CUT); // use "Cut" icon
icons.SetInt32(2, IDM_DELETE); // use "Delete" icon
settings.SetContainer(DESC_CYCLEICONS, icons);
void SetContainer(Int32 id, const BaseContainer &s)
Definition: c4d_basecontainer.h:679
#define CUSTOMGUI_CYCLE
Selection list field.
Definition: lib_description.h:215
@ DESC_CYCLEICONS
BaseContainer Icon IDs for cycle.
Definition: lib_description.h:141
@ DESC_CYCLE
BaseContainer Contains members of cycle as string. (E.g. GetString(10041) == "-X"....
Definition: lib_description.h:118
@ DTYPE_LONG
Int32
Definition: lib_description.h:67
#define IDM_CUT
Cut.
Definition: ge_prepass.h:3869
PyWideStringList Py_ssize_t wchar_t ** items
Definition: initconfig.h:448

Both DTYPE_BASELISTLINK and CUSTOMDATATYPE_INEXCLUDE_LIST parameter types can reference Cinema 4D elements.

Note
The check is done with C4DAtom::IsInstanceOf(), so also category types like Obase etc. can be used.
// This example configures a link parameter description
// that only accepts "Cube" and "Sphere" objects.
settings.SetString(DESC_NAME, "Link"_s);
ac.SetInt32(Osphere, 1); // accept "Sphere" objects
ac.SetInt32(Ocube, 1); // accept "Cube" objects.
settings.SetContainer(DESC_ACCEPT, ac);
@ DESC_ACCEPT
BaseContainer Contains the accepted IDs as strings. For C4DAtom::IsInstanceOf() checks....
Definition: lib_description.h:121
#define Ocube
Cube.
Definition: ge_prepass.h:1119
#define Osphere
Sphere.
Definition: ge_prepass.h:1120

A DTYPE_BASELISTLINK parameter can also reference and manage a shader:

// This example creates a shader link parameter description that cannot be unfolded.
settings.SetString(DESC_NAME, "Shader"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_TEXBOX); // use the tex box gui to handle shaders
settings.SetBool(DESC_SHADERLINKFLAG, true); // is a shader link
// don't unfold the GUI in the Attribute Manager
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));

A DTYPE_SEPARATOR can be displayed with or without a line:

// This example configures a separator description.
settings.SetString(DESC_NAME, String());
settings.SetBool(DESC_SEPARATORLINE, true);
Definition: c4d_string.h:41
#define CUSTOMGUI_SEPARATOR
Separator.
Definition: lib_description.h:225
@ DESC_SEPARATORLINE
Bool true if separators should have a visible line.
Definition: lib_description.h:122
@ DTYPE_SEPARATOR
Separator.
Definition: lib_description.h:63

If a DTYPE_VECTOR is used to display a rotation (DESC_UNIT_DEGREE) it can display this as XYZ or HPB:

  • DESC_ANGULAR_XYZ: Set to true for XYZ as angular representation, or false for HPB.
// This example configures a vector parameter description.
settings.SetString(DESC_NAME, "Vector"_s);
settings.SetInt32(DESC_UNIT, DESC_UNIT_DEGREE); // use degree units for rotation vector
settings.SetBool(DESC_ANGULAR_XYZ, true); // sub-parameters won't be shown as HPB but as XYZ
@ DESC_UNIT_DEGREE
FORMAT_DEGREE
Definition: lib_description.h:114
@ DESC_ANGULAR_XYZ
Bool true for XYZ as angular representation, or false for HPB.
Definition: lib_description.h:146
@ DTYPE_VECTOR
Vector
Definition: lib_description.h:70

Material Editor

Materials can include parameter groups that are presented as "channels" in the Material Editor window. The left column of the Material Editor can include references to these channels or simple parameters:

// This example adds a parameter to the left column of the Material Editor.
// The name of the parameter will be hidden.
const DescID cid = ConstDescID(DescLevel(ID_REAL, DTYPE_REAL, 0));
settings.SetString(DESC_NAME, "Float Value"_s);
// don't display the name in the Material Editor left column
settings.SetBool(DESC_MATEDNOTEXT, true);
description->SetParameter(cid, settings, ConstDescID(DescLevel(Tbaselist2d)));
@ DESC_MATEDNOTEXT
Bool No text in Material Editor window.
Definition: lib_description.h:163
#define Tbaselist2d
2D list.
Definition: ge_prepass.h:996

A DTYPE_BOOL can be used to enable or disable a channel group.

// This example adds a new material parameter group.
// This group can be selected with a Boolean parameter in the left column.
// add the Boolean parameter to select the group
{
const DescID cid = ConstDescID(DescLevel(ID_SETTINGS_BOOL, DTYPE_BOOL, 0));
settings.SetString(DESC_NAME, "Settings"_s);
settings.SetInt32(DESC_PARENTMSG, ID_SETTINGS_GROUP); // the group to select
settings.SetBool(BOOL_PAGEMODE, true); // page mode; no checkbox is displayed
settings.SetBool(DESC_HIDE, true); // hide in Attribute Manager
description->SetParameter(cid, settings, ConstDescID(DescLevel(Tbaselist2d)));
}
// add a material group
{
const DescID cid = ConstDescID(DescLevel(ID_SETTINGS_GROUP, DTYPE_GROUP, 0));
settings.SetString(DESC_NAME, "Material Properties"_s);
description->SetParameter(cid, settings, ConstDescID(DescLevel(0)));
}
// add a parameter to that group
{
const DescID cid = ConstDescID(DescLevel(ID_PARAMETER, DTYPE_BOOL, 0));
settings.SetString(DESC_NAME, "Some Parameter"_s);
description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_SETTINGS_GROUP)));
}
@ DESC_HIDE
Bool Indicates whether the property is hidden or not.
Definition: lib_description.h:119
@ DESC_PARENTMSG
DescID Used in the Material Editor on the boolean tabs to specify which section to open.
Definition: lib_description.h:162
#define BOOL_PAGEMODE
Page mode for boolean elements. If set it means that this boolean will have no checkbox....
Definition: lib_description.h:31

Further Reading