Description Manual

About

A Description object stores information on how C4DAtom parameters are to be displayed in the GUI (Attribute Manager). It contains information on:

  • the parameter type and valid parameter values.
  • optional information on the (custom) GUI that is used to display the parameter in the Attribute Manager.

The information is stored using description setting IDs, see Description Settings Manual.

Note
A Description is displayed in a GeDialog using the DescriptionCustomGui custom GUI element.
User data parameters are stored in a DynamicDescription object, see DynamicDescription Manual.

Access

To add dynamic parameters to a NodeData based plugin one can implement NodeData::GetDDescription(). This function receives a given Description object that should be filled with the description of the visible parameters.

See NodeData::GetDDescription() Manual.

// This example defines the element's parameter description by loading the registered description of the plugin type.
virtual Bool GetDDescription(GeListNode* node, Description* description, DESCFLAGS_DESC& flags)
{
const Bool invalidNode = node == nullptr;
const Bool invalidDescription = description == nullptr;
if (invalidNode || invalidDescription)
return false;
// load the description of this type
if (description->LoadDescription(node->GetType()) == false)
return false;
return SUPER::GetDDescription(node, description, flags);
}

Correspondingly it is possible to get the parameter description from a C4DAtom:

See C4DAtom Parameter Properties.

// This example prints the names of all parameters in the current parameter description.
if (description == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// get the Description of the given object
if (!object->GetDescription(description, DESCFLAGS_DESC::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
void* handle = description->BrowseInit();
const BaseContainer* bc = nullptr;
DescID id, gid;
// loop through all elements of the description
while (description->GetNext(handle, &bc, id, gid))
{
ApplicationOutput("Parameter Name: " + bc->GetString(DESC_NAME));
}
description->BrowseFree(handle);

Allocation/Deallocation

A Description object can be created with the usual tools:

This is needed to access the parameter description of a given object:

// This example accesses the Description of the given object.
// check if an object is selected
BaseObject* const activeObject = doc->GetActiveObject();
if (activeObject == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// check if the Description object could be allocated
if (description == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// read the Description from the active object
if (activeObject->GetDescription(description, DESCFLAGS_DESC::NONE))
{
ApplicationOutput("Got Description");
}

Load Description

The description of an plugin's static parameters is defined in the plugin's *.res file. This *.res file is typically registered using the "Register" function of the plugin (see General Plugin Information Manual). Such a registered description can then be loaded:

A custom data type can also define its own description. This sub-description (or sub-channels) can be loaded with:

// This example reads and prints the sub-description
// of the "Scale" spline parameter of the given "Sweep" generator.
// load parameter sub-description
if (elements == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
elements->Append(sweepObj);
if (desc == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// get plugin structure for the given resource plugin
RESOURCEDATATYPEPLUGIN* resDataType = FindResourceDataTypePlugin(completeID[-1].dtype);
if (resDataType == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// load sub-description
const Bool gotSubDescription = desc->GetSubDescriptionWithData(
completeID, elements, resDataType, BaseContainer(), nullptr);
if (!gotSubDescription)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// print names of sub-description parameters
void* handle = desc->BrowseInit();
const BaseContainer* bc = nullptr;
DescID loopID, gid;
// loop through sub-description parameters
while (desc->GetNext(handle, &bc, loopID, gid))
desc->BrowseFree(handle);

Parameter Descriptions

Edit

In certain situations NodeData::GetDDescription() is not called to get the description of all parameters but of only one specific parameter.

Existing parameter descriptions are stored in BaseContainers that can be accessed with:

Note
The parameter IDs are described in Description Settings Manual.
// This example changes the name of a description element.
const DescID* const singleid = description->GetSingleDescID();
// parameter ID
DescID cid = DescLevel(EXAMPLE_GENERATOR_BUTTON, DTYPE_BUTTON, 0);
// check if this parameter ID is requested
if (singleid == nullptr || cid.IsPartOf(*singleid, nullptr))
{
BaseContainer* settings = nullptr;
settings = description->GetParameterI(cid, nullptr);
if (settings)
settings->SetString(DESC_SHORT_NAME, "New Button Name"_s);
}

Also a new parameter description can be added:

// This example adds a new parameter description.
const DescID* const singleid = description->GetSingleDescID();
// add a parameter description
DescID cid = DescLevel(1003, DTYPE_REAL, 0);
// check if this parameter ID is requested (NOTE: this check is important for speed)
if (singleid == nullptr || cid.IsPartOf(*singleid, nullptr))
{
// define the new parameter description
settings.SetString(DESC_NAME, "A new parameter"_s);
// set the new parameter
if (!description->SetParameter(cid, settings, ID_OBJECTPROPERTIES))
return;
}

Iterate

There are two ways to iterate over all elements stored in a Description object. The first way is to loop over all stored parameters in a list:

// This example shows how to load an existing description into a temporary
// description and to copy the data into the actual description.
// load the Description of the material preview element
if (tempDesc && tempDesc->LoadDescription("Mpreview"))
{
void* handle = tempDesc->BrowseInit();
const BaseContainer* settings = nullptr;
DescID id, gid;
// loop through the elements of the description
while (tempDesc->GetNext(handle, &settings, id, gid))
{
description->SetParameter(id, *settings, gid);
}
tempDesc->BrowseFree(handle);
}

The other way to iterate over all elements is to navigate down the tree hierarchy defined by parameter groups:

// This example loops through the top level parameter descriptions.
BaseObject* const object = doc->GetActiveObject();
if (object == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
if (description == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// read the Description from the active object
if (!object->GetDescription(description, DESCFLAGS_DESC::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// loop through description
// get the first element
if (ar == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
DescEntry* entry = description->GetFirst(ar);
while (entry != nullptr)
{
// get element
const BaseContainer* bc = nullptr;
DescID descid;
description->GetDescEntry(entry, &bc, descid);
// print description name
if (bc != nullptr)
// handle sub-entries (elements of parameter groups etc.)
// HandleSubEntries() is a custom function
DescEntry* const subEntries = description->GetDown(entry);
HandleSubEntries(subEntries);
entry = description->GetNext(entry);
}

Miscellaneous

This convenience function allows to fill the BaseContainer for a pop-up menu based on the content of the Description:

// This example creates a pop up menu based on the given Description.
BaseContainer descriptionPopUp;
if (!description->CreatePopupMenu(descriptionPopUp))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
ShowPopupMenu(nullptr, MOUSEPOS, MOUSEPOS, descriptionPopUp);

This function allows to complete a given DescID:

// This example completes the given DescID.
const DescID incompleteID = DescID(DescLevel(1110, 0, 0));
DescID completeID;
if (arr == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// check if the ID exists and complete it
if (description->CheckDescID(incompleteID, arr, &completeID))
{
// check if the completed ID describes a float parameter
if (completeID[-1].dtype == DTYPE_REAL)
ApplicationOutput("This is a float parameter");
}

Further Reading

Description::CheckDescID
Bool CheckDescID(const DescID &searchid, const AtomArray &ops, DescID *completeid)
GetCustomDataTypeDefault
BaseContainer GetCustomDataTypeDefault(Int32 type)
ShowPopupMenu
Int32 ShowPopupMenu(CDialog *cd, Int32 screenx, Int32 screeny, const BaseContainer &bc, Int32 flags=POPUP_RIGHT|POPUP_EXECUTECOMMANDS, Int32 *res_mainid=nullptr)
MOUSEPOS
#define MOUSEPOS
Mouse position constant for ShowPopupMenu().
Definition: c4d_gui.h:3209
Description::CreatePopupMenu
Bool CreatePopupMenu(BaseContainer &menu)
BaseObject
Definition: c4d_baseobject.h:224
DescID
Definition: lib_description.h:327
C4DAtom::GetDescription
Bool GetDescription(Description *description, DESCFLAGS_DESC flags)
BaseContainer::SetString
void SetString(Int32 id, const maxon::String &s)
Definition: c4d_basecontainer.h:569
Description::LoadDescription
Bool LoadDescription(const BCResourceObj *bc, Bool copy)
Description
Definition: lib_description.h:527
DESCFLAGS_DESC
DESCFLAGS_DESC
Definition: ge_prepass.h:3101
Description::GetFirst
DescEntry * GetFirst(const AtomArray &op)
DescID::IsPartOf
Bool IsPartOf(const DescID &cmp, Int32 *pos) const
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
ID_OBJECTPROPERTIES
@ ID_OBJECTPROPERTIES
Definition: obase.h:53
Description::SetParameter
Bool SetParameter(const DescID &id, const BaseContainer &param, const DescID &groupid)
DESCFLAGS_DESC::NONE
@ NONE
None.
GeListNode
Represents a C4DAtom that resides in a 4D list.
Definition: c4d_baselist.h:1797
DTYPE_BUTTON
@ DTYPE_BUTTON
Button.
Definition: lib_description.h:61
Description::GetNext
Bool GetNext(void *handle, const BaseContainer **bc, DescID &id, DescID &groupid)
DESC_SHORT_NAME
@ DESC_SHORT_NAME
String Short name, for attributes dialog.
Definition: lib_description.h:92
DescLevel
Represents a level within a DescID.
Definition: lib_description.h:286
Description::GetDown
DescEntry * GetDown(DescEntry *de)
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
CUSTOMDATATYPE_SPLINE
#define CUSTOMDATATYPE_SPLINE
Spline data type ID.
Definition: customgui_splinecontrol.h:23
Description::GetParameterI
BaseContainer * GetParameterI(const DescID &id, AtomArray *ar)
Description::GetSingleDescID
const DescID * GetSingleDescID()
@markPrivate
DESCFLAGS_DESC::LOADED
@ LOADED
Set if elements have been added to the description, either by loading or manual addition.
Description::BrowseInit
void * BrowseInit()
AtomArray::Append
Bool Append(C4DAtom *obj)
Definition: c4d_baselist.h:1671
AutoAlloc
Definition: ge_autoptr.h:36
BaseContainer::GetString
String GetString(Int32 id, const maxon::String &preset=maxon::String()) const
Definition: c4d_basecontainer.h:387
DESC_NAME
@ DESC_NAME
String Name for standalone use.
Definition: lib_description.h:91
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55
BaseDocument::GetActiveObject
BaseObject * GetActiveObject(void)
Description::GetSubDescriptionWithData
Bool GetSubDescriptionWithData(const DescID &did, const AtomArray &op, RESOURCEDATATYPEPLUGIN *resdatatypeplugin, const BaseContainer &bc, DescID *singledescid)
Description::BrowseFree
void BrowseFree(void *&handle)
DTYPE_REAL
@ DTYPE_REAL
Float
Definition: lib_description.h:68
C4DAtom::GetType
Int32 GetType() const
Definition: c4d_baselist.h:1378
Description::GetDescEntry
void GetDescEntry(DescEntry *de, const BaseContainer **bc, DescID &descid)
SWEEPOBJECT_SPLINESCALE
@ SWEEPOBJECT_SPLINESCALE
Definition: osweep.h:20
FindResourceDataTypePlugin
RESOURCEDATATYPEPLUGIN * FindResourceDataTypePlugin(Int32 type)
BaseContainer
Definition: c4d_basecontainer.h:46