Description Settings Manual

Table of Contents

• About
• Parameters Types
• Groups
• Parent Parameters
• Layout
• Visibility
• Name
• Animation
• Values
• Material Editor
• Further Reading

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:

• receiving a Description from C4DAtom::GetDescription(), see Parameter Properties.
• creating or editing user data, see DynamicDescription Manual.
• creating or editing dynamic parameters in NodeData::GetDDescription(), see NodeData::GetDDescription() Manual and Description Manual.

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:

• GetCustomDataTypeDefault(): Returns a BaseContainer with the default settings of the given parameter type.

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

• ::DTYPE_LONG: A Int32 parameter.
• ::DTYPE_REAL: A Float parameter.
• ::DTYPE_COLOR: A Color parameter.
• ::DTYPE_COLORA: A RGBA Color value.
• ::DTYPE_BOOL: A Bool parameter.
• ::DTYPE_TIME: A BaseTime parameter.
• ::DTYPE_VECTOR: A Vector parameter.
• ::DTYPE_VECTOR4D: A 4D vector.
• ::DTYPE_MATRIX: A Matrix parameter.
• ::DTYPE_STRING: A String parameter.
• ::DTYPE_FILENAME: A Filename parameter.
• ::DTYPE_TEXTURE: A texture name (Filename). Do not confuse this with a shader link which is a ::DTYPE_BASELISTLINK with a custom GUI.
• ::DTYPE_BASELISTLINK: A BaseLink parameter. May also be a shader link displaying and managing a shader.

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))
      {
        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, ConstDescID(DescLevel(ID_OBJECTPROPERTIES))))
          return;
      }

Other parameter types are

• ::DTYPE_BUTTON: A button parameter.
• ::DTYPE_SEPARATOR: A separator parameter.
• ::DTYPE_STATICTEXT: A static text parameter.
• ::DTYPE_POPUP: A popup parameter.
• ::DTYPE_SUBCONTAINER: A sub-container. Typically for user data.
• ::DTYPE_GROUP: A parameter group. See Groups

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, ConstDescID(DescLevel(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, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));
        }

Groups

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

• ::DTYPE_GROUP: The type of a parameter group.
• ::DESC_COLUMNS: Number of columns for layout groups.
• ::DESC_LAYOUTGROUP: Set to true for layout groups. The content of such layout groups must be organized in sub-groups, see Layout Groups.
• ::DESC_GROUPSCALEV: Allow the group height to be scaled.
• ::DESC_TITLEBAR: Main group title bar option. If the title bar should be hidden ::DESC_NAME must not be set, only ::DESC_SHORT_NAME.
• ::DESC_DEFAULT: If set to 1 the group is unfolded by default. If set to -1 it will always be unfolded when re-created.

      // This example creates a new parameter group with two sub-parameters.
 
      // define the group
      MAXON_SCOPE
      {
        const DescID groupID = ConstDescID(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, ConstDescID(DescLevel(0)));
      }
 
      // add the first child parameter
      MAXON_SCOPE
      {
        const DescID  cid = ConstDescID(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, ConstDescID(DescLevel(ID_GROUP)));
      }
 
      // add the second child parameter
      MAXON_SCOPE
      {
        const DescID  cid = ConstDescID(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, ConstDescID(DescLevel(ID_GROUP)));
      }
    }

A parameter is typically part of a group:

• ::DESC_PARENTGROUP: The ID of the parent 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));
      }

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

• ::DESC_PARENT_COLLAPSE: The ID of the parent parameter.

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

Layout

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

• ::DESC_SCALEH: The element is scaled horizontally.
• ::DESC_FITH: The element fits horizontally.
• ::DESC_ALIGNLEFT: The element is aligned left.

Visibility

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

• ::DESC_HIDE: Indicates whether the element is hidden or not. Especially used to hide a parameter from a loaded parameter description.
• ::DESC_CUSTOMGUI: The ID of the custom GUI element.
• ::DESC_GUIOPEN: Set to true if the maximized GUI is shown by default.
• ::DESC_FORBID_INLINE_FOLDING: Instructs the Attribute Manager to not allow expanding inline objects.
• ::DESC_NOGUISWITCH: Disables GUI switching for this element.
• ::DESC_DISABLELAYOUTSWITCH: Hides the Layout Switch arrow.
• ::DESC_HIDE_WHEN_INLINE: Hide this attribute in inline descriptions.
• ::DESC_REPLACE_HIDE: Element replaced by a complex UI.
• ::DESC_REPLACECOMPLEXUI: BaseContainer filled with descids of props to replace.

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, ConstDescID(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:

• ::DESC_ANIMATE: The animation mode:
  • ::DESC_ANIMATE_OFF: Parameter is not animatable.
  • ::DESC_ANIMATE_ON: Parameter is animatable.
  • ::DESC_ANIMATE_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.

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

• ::DESC_MIN: Minimum value.
• ::DESC_MAX: Maximum value.
• ::DESC_MINEX: Defines if ::DESC_MIN is exclusive, otherwise it is inclusive.
• ::DESC_MAXEX: Defines if ::DESC_MAX is exclusive, otherwise it is inclusive.
• ::DESC_STEP: The step for the edit field arrows.
• ::DESC_DEFAULT: Default numeric value.
• ::DESC_MINSLIDER: Minimum value for slider.
• ::DESC_MAXSLIDER: Maximum value for slider.

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

• ::DESC_UNIT: Unit type.
  • ::DESC_UNIT_FLOAT: Float.
  • ::DESC_UNIT_INT: Integer.
  • ::DESC_UNIT_PERCENT: Percentage.
  • ::DESC_UNIT_DEGREE: Degree.
  • ::DESC_UNIT_METER: Meters. The "Scale" tool will auto-scale these parameters when the host BaseObject is scaled.
  • ::DESC_UNIT_TIME: Time.
• ::DESC_FORBID_SCALING: Prevents auto-scaling "meter" parameters.

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:

• ::DESC_CYCLE: Setting for a BaseContainer with the members of the cycle as string.
• ::DESC_CYCLEICONS: Setting for a BaseContainer with the icon IDs for cycle.

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

• ::DESC_ACCEPT: Setting for a BaseContainer with accepted element IDs.
• ::DESC_REFUSE: Setting for a BaseContainer with refused element IDs.

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:

• ::DESC_SHADERLINKFLAG: Specifies that this element is a shader link.

      // 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, ConstDescID(DescLevel(ID_OBJECTPROPERTIES)));

A ::DTYPE_SEPARATOR can be displayed with or without a line:

• ::DESC_SEPARATORLINE: Set to true if the separator should have a visible 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:

• ::DESC_MATEDNOTEXT: Defines if the parameter name is displayed in the Material Editor window.
• ::DESC_COLUMNSMATED: Number of columns in left Material Editor window.
• ::DESC_MATERIALEDITOR_LEFTSIDE: True if the property should appear on the left side of the material editor.

      // 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));
      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, ConstDescID(DescLevel(Tbaselist2d)));

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

• ::DESC_PARENTMSG: ID of the associated group.
• BOOL_PAGEMODE: Defines if a checkbox is displayed or not.

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

Further Reading

• Description Manual
• DynamicDescription Manual
• DescID Manual
• C4DAtom Manual
• NodeData::GetDDescription() Manual
• NodeData::GetDEnabling() Manual