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