About

A DynamicDescription object stores the description of user data parameters that can be added to an element by the user. It allows to access existing parameters and also to add new parameters.

Warning: Standard parameters can be dynamically created and edited by implementing NodeData::GetDDescription(). See NodeData::GetDDescription() Manual.

Note: User data parameters are accessed using a special DescID, see DescID Manual.; For description parameter IDs see Description Settings Manual.

  // This example adds a group and a child string user data parameter to the active object.
 
  BaseObject* const op = doc->GetActiveObject();
  if (op == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  DynamicDescription* const ddesc = op->GetDynamicDescription();
  if (ddesc == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  DescID groupID;
 
  MAXON_SCOPE
  {
    // make group
    BaseContainer bc = GetCustomDataTypeDefault(DTYPE_GROUP);
 
    bc.SetString(DESC_NAME, "Group"_s);
    bc.SetInt32(DESC_COLUMNS, 1);
    bc.SetInt32(DESC_DEFAULT, 1);
    bc.SetInt32(DESC_SCALEH, 1);
 
    groupID = ddesc->Alloc(bc);
  }
 
  MAXON_SCOPE
  {
    // make string parameter
    BaseContainer bc = GetCustomDataTypeDefault(DTYPE_STRING);
    bc.SetString(DESC_NAME, "Text 1"_s);
    bc.SetInt32(DESC_SCALEH, 1);
 
    // set group as parent
    bc.SetData(DESC_PARENTGROUP, GeData { CUSTOMDATATYPE_DESCID, groupID });
 
    ddesc->Alloc(bc);
  }

Access

The DynamicDescription object can be obtained from every C4DAtom:

C4DAtom::GetDynamicDescription(): Returns the user data parameter description of the entity.

The description of a specific user data parameter can be directly accessed:

DynamicDescription::Find(): Returns the description of the user data parameter with the given ID.

  // This example prints the name of the user data parameter with the ID 1.
 
  DynamicDescription* const ddesc = object->GetDynamicDescription();
  if (ddesc == nullptr)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  const DescLevel userData = DescLevel(ID_USERDATA, DTYPE_SUBCONTAINER, 0);
  const DescID    ID { userData, DescLevel(1) };
  const BaseContainer* const bc = ddesc->Find(ID);
 
  if (bc != nullptr)
    ApplicationOutput("Name: " + bc->GetString(DESC_NAME));

It is also possible to iterate through all user data parameter descriptions:

DynamicDescription::BrowseInit(): Returns the handle used to browse the parameter descriptions.
DynamicDescription::BrowseGetNext(): Retrieves the next parameter description.
DynamicDescription::BrowseFree(): Frees the given browse handles.

  // This example prints the name of all user data parameters of the given object.
 
  // get user data
  DynamicDescription* const ddesc = object->GetDynamicDescription();
  if (ddesc == nullptr)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // browse user data
  void* handle = ddesc->BrowseInit();
  if (handle == nullptr)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  DescID ID;
  const BaseContainer* bc = nullptr;
 
  // loop through all user data parameter descriptions
  while (ddesc->BrowseGetNext(handle, &ID, &bc))
  {
    // print name
    if (bc != nullptr)
      ApplicationOutput("Name: " + bc->GetString(DESC_NAME));
  }
 
  ddesc->BrowseFree(handle);

Edit User Data

User data parameter descriptions can be added or removed:

DynamicDescription::Alloc(): Allocates a new user data parameter and returns its ID.
DynamicDescription::Set(): Inserts a new user data parameter with the given ID.
DynamicDescription::Remove(): Removes the user data parameter with the given ID.
DynamicDescription::FillDefaultContainer(): Fills the given BaseContainer with the default settings of the given data type.

  // This example creates a new user data parameter
 
  // get user data
  DynamicDescription* const ddesc = object->GetDynamicDescription();
  if (ddesc == nullptr)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // configure type as vector
  BaseContainer bc(DTYPE_VECTOR);
  ddesc->FillDefaultContainer(bc, DTYPE_VECTOR, "Position");
 
  // create new userdata parameter
  ddesc->Alloc(bc);

Note: An empty DescID as the DESC_PARENTGROUP of a user data group will create a new tab in the Attribute Manager.

Interaction

User data parameters can include buttons. When such a button is pressed a message is sent to NodeData::Message(), see NodeData::Message() Manual.

      // This example catches the event triggered when a user data button was pressed.
      // The event is caught in the host NodeData::Message() function.
 
      case MSG_DESCRIPTION_COMMAND:
      {
        DescriptionCommand* const dc = static_cast<DescriptionCommand*>(data);
        if (dc == nullptr)
          return false;
 
        // check if the DescID has two levels (expected for user data)
        if (dc->_descId.GetDepth() == 2)
        {
          // check if it is a user data button
          if (dc->_descId[0].id == ID_USERDATA)
          {
            const maxon::String stringID = maxon::String::IntToString(dc->_descId[1].id);
            MessageDialog("User Data Button clicked: "_s + stringID);
          }
        }
 
        break;
      }

Miscellaneous

Further functions of the DynamicDescription class are:

DynamicDescription::CopyTo(): Copies the dynamic description to the given object.
DynamicDescription::GetDirty(): Returns a dirty count of the parameter descriptions (not the parameter values).

  // This example prints the dirty count of the user data description.
 
  const UInt32 dirty = ddesc->GetDirty();
  ApplicationOutput("Dirty State: " + String::UIntToString(dirty));

User Data Editor

The user data manager can be opened with these functions:

EditDescription(): Shows the edit dialog for a dynamic description.
AddDescription(): Shows the add dialog for a dynamic description.
PasteDescription(): Shows the paste dialog for a dynamic description.

  // This example opens the dialog to add user data descriptions to the given object.
 
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  AddDescription(object);

Table of Contents