Description Settings Manual

Table of Contents

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 = DescLevel(ID_BOOL, DTYPE_BOOL, 0);
const DescID* 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 || cid.IsPartOf(*singleid, nullptr))
{
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BOOL);
settings.SetString(DESC_NAME, "Boolean Parameter"_s);
// check if the new parameter description could be inserted
if (!description->SetParameter(cid, settings, ID_OBJECTPROPERTIES))
return;
}

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.
MAXON_SCOPE
{
// create a button
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BUTTON);
settings.SetString(DESC_NAME, "Button"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_BUTTON);
description->SetParameter(buttonID, settings, ID_OBJECTPROPERTIES);
}
MAXON_SCOPE
{
// create a bitmap button
BaseContainer settings = GetCustomDataTypeDefault(CUSTOMDATATYPE_BITMAPBUTTON);
settings.SetString(DESC_NAME, "Bitmap Button"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_BITMAPBUTTON);
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, ID_OBJECTPROPERTIES);
}

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
MAXON_SCOPE
{
const DescID groupID = DescLevel(ID_GROUP, DTYPE_GROUP, 0);
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_GROUP);
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, 0);
}
// add the first child parameter
MAXON_SCOPE
{
const DescID cid = DescID(DescLevel(ID_STRING_A, DTYPE_STRING, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_STRING);
settings.SetString(DESC_NAME, "Parameter A"_s);
settings.SetInt32(DESC_SCALEH, 1);
description->SetParameter(cid, settings, ID_GROUP);
}
// add the second child parameter
MAXON_SCOPE
{
const DescID cid = DescID(DescLevel(ID_STRING_B, DTYPE_STRING, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_STRING);
settings.SetString(DESC_NAME, "Parameter B"_s);
settings.SetInt32(DESC_SCALEH, 1);
description->SetParameter(cid, settings, ID_GROUP);
}
}

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
CustomDataType* const customData = parentid.GetCustomDataType(CUSTOMDATATYPE_DESCID);
const DescID* const descID = static_cast<const DescID*>(customData);
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));
}

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 = DescID(DescLevel(ID_NEWLINE, DTYPE_STATICTEXT, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_STATICTEXT);
settings.SetString(DESC_NAME, ""_s);
settings.SetInt32(DESC_SCALEH, 1);
settings.SetBool(DESC_NEWLINE, true);
description->SetParameter(cid, settings, ID_GROUP);

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 = DescID(DescLevel(ID_PARENT, DTYPE_STRING, 0));
// add the parent parameter
MAXON_SCOPE
{
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_STRING);
settings.SetString(DESC_NAME, "Parent"_s);
settings.SetData(DESC_PARENT_COLLAPSE, NOTOK);
description->SetParameter(parentID, settings, ID_OBJECTPROPERTIES);
}
// add the child parameter
MAXON_SCOPE
{
const DescID cid = DescID(DescLevel(ID_CHILD, DTYPE_STRING, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_STRING);
settings.SetString(DESC_NAME, "Child"_s);
GeData parentIdData;
parentIdData.SetCustomDataType(CUSTOMDATATYPE_DESCID, parentID);
settings.SetData(DESC_PARENT_COLLAPSE, parentIdData);
description->SetParameter(cid, settings, ID_OBJECTPROPERTIES);
}

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.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_REAL);
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
// This example creates a shader link parameter description that cannot be unfolded.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BASELISTLINK);
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
settings.SetInt32(DESC_FORBID_INLINE_FOLDING, true);
description->SetParameter(cid, settings, DescLevel(ID_OBJECTPROPERTIES));

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.
BaseContainer settings = GetCustomDataTypeDefault(DATETIME_DATA);
settings.SetString(DESC_NAME, "Date"_s);
settings.SetInt32(DESC_CUSTOMGUI, DATETIME_GUI);
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

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.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_REAL);
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

Animation

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

// This example disables animation for the new parameter description.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_REAL);
settings.SetString(DESC_NAME, "Non Animate"_s);
settings.SetInt32(DESC_ANIMATE, DESC_ANIMATE_OFF); // parameter not animateable

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.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_REAL);
settings.SetString(DESC_NAME, "Slider"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_REALSLIDER);
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

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.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_REAL);
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);

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
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_LONG);
settings.SetString(DESC_NAME, "Drop Down"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_CYCLE);
// add cycle elements
BaseContainer items;
items.SetString(0, "Item 1"_s);
items.SetString(1, "Item 2"_s);
items.SetString(2, "Item 3"_s);
settings.SetContainer(DESC_CYCLE, items);
// add cycle icons
BaseContainer 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);

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.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BASELISTLINK);
settings.SetString(DESC_NAME, "Link"_s);
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_LINKBOX);
BaseContainer ac;
ac.SetInt32(Osphere, 1); // accept "Sphere" objects
ac.SetInt32(Ocube, 1); // accept "Cube" objects.
settings.SetContainer(DESC_ACCEPT, ac);

A DTYPE_BASELISTLINK parameter can also reference and manage a shader:

// This example creates a shader link parameter description that cannot be unfolded.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BASELISTLINK);
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
settings.SetInt32(DESC_FORBID_INLINE_FOLDING, true);
description->SetParameter(cid, settings, DescLevel(ID_OBJECTPROPERTIES));

A DTYPE_SEPARATOR can be displayed with or without a line:

// This example configures a separator description.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_SEPARATOR);
settings.SetString(DESC_NAME, String());
settings.SetInt32(DESC_CUSTOMGUI, CUSTOMGUI_SEPARATOR);
settings.SetBool(DESC_SEPARATORLINE, true);

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.
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_VECTOR);
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

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 = DescID(DescLevel(ID_REAL, DTYPE_REAL, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_REAL);
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, Tbaselist2d);

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
MAXON_SCOPE
{
const DescID cid = DescID(DescLevel(ID_SETTINGS_BOOL, DTYPE_BOOL, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BOOL);
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, Tbaselist2d);
}
// add a material group
MAXON_SCOPE
{
const DescID cid = DescLevel(ID_SETTINGS_GROUP, DTYPE_GROUP, 0);
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_GROUP);
settings.SetString(DESC_NAME, "Material Properties"_s);
description->SetParameter(cid, settings, 0);
}
// add a parameter to that group
MAXON_SCOPE
{
const DescID cid = DescID(DescLevel(ID_PARAMETER, DTYPE_BOOL, 0));
BaseContainer settings = GetCustomDataTypeDefault(DTYPE_BOOL);
settings.SetString(DESC_NAME, "Some Parameter"_s);
description->SetParameter(cid, settings, ID_SETTINGS_GROUP);
}

Further Reading