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(const GeListNode* node, Description* description, DESCFLAGS_DESC& flags) const
{
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);
}
PyCompilerFlags * flags
Definition: ast.h:14
Definition: lib_description.h:622
Bool LoadDescription(const BCResourceObj *bc, Bool copy)
Represents a C4DAtom that resides in a 4D list.
Definition: c4d_baselist.h:1976
maxon::Bool Bool
Definition: ge_sys_math.h:51
DESCFLAGS_DESC
Definition: ge_prepass.h:3332
@ LOADED
Set if elements have been added to the description, either by loading or manual addition.
Definition: node.h:10

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);
Definition: ge_autoptr.h:37
Definition: c4d_basecontainer.h:48
String GetString(Int32 id, const maxon::String &preset=maxon::String()) const
Definition: c4d_basecontainer.h:432
Definition: lib_description.h:355
@ DESC_NAME
String Name for standalone use.
Definition: lib_description.h:91
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
Definition: object.h:105

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");
}
Definition: c4d_baseobject.h:248
Bool GetDescription(Description *description, DESCFLAGS_DESC flags) const
const char * doc
Definition: pyerrors.h:226

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 Common Plugin Concepts). 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);
RESOURCEDATATYPEPLUGIN * FindResourceDataTypePlugin(Int32 type)
#define CUSTOMDATATYPE_SPLINE
Spline data type ID.
Definition: customgui_splinecontrol.h:30
#define ConstDescID(...)
Definition: lib_description.h:594
@ SWEEPOBJECT_SPLINESCALE
Definition: osweep.h:20
Represents a level within a DescID.
Definition: lib_description.h:298
PyStructSequence_Desc * desc
Definition: structseq.h:26

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 = ConstDescID(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);
}
void SetString(Int32 id, const maxon::String &s)
Definition: c4d_basecontainer.h:651
Bool IsPartOf(const DescID &cmp, Int32 *pos) const
@ DESC_SHORT_NAME
String Short name, for attributes dialog.
Definition: lib_description.h:92
@ DTYPE_BUTTON
Button.
Definition: lib_description.h:61

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
// 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, ConstDescID(DescLevel(ID_OBJECTPROPERTIES))))
return;
}
BaseContainer GetCustomDataTypeDefault(Int32 type)
@ DTYPE_REAL
Float
Definition: lib_description.h:68
@ ID_OBJECTPROPERTIES
Definition: obase.h:56

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);
#define MOUSEPOS
Mouse position constant for ShowPopupMenu().
Definition: c4d_gui.h:3329
Int32 ShowPopupMenu(CDialog *cd, Int32 screenx, Int32 screeny, const BaseContainer &bc, Int32 flags=POPUP_RIGHT|POPUP_EXECUTECOMMANDS|POPUP_ALLOW_FILTERING, Int32 *res_mainid=nullptr)

This function allows to complete a given DescID:

// This example completes the given DescID.
const DescID incompleteID = ConstDescID(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