Description Class Reference

#include <lib_description.h>

Detailed Description

The description class contains information for all description ID of an object.
For example it stores a BaseContainer for ID_BASEOBJECT_REL_POSITION that describes that this value is a Vector, has minimum and maximum values XYZ etc.
To access the actual values of these description parameters you will have to ask the object itself, for example with C4DAtom::GetParameter().
Example to get the name of a description, for example "Landscape Object":

String GetTypeName(C4DAtom *op)
{
if (op)
{
if (!desc)
return String();
return String();
const BaseContainer *bc = desc->GetParameterI(DESCID_ROOT, nullptr);
if (bc)
return bc->GetString(DESC_NAME);
}
return String();
}

Public Member Functions

Bool LoadDescription (const BCResourceObj *bc, Bool copy)
 
Bool LoadDescription (Int32 id)
 
Bool LoadDescription (const String &id)
 
Bool SortGroups ()
 
const BCResourceObj * GetDescription ()
 
const BaseContainerGetParameter (const DescID &id, BaseContainer &temp, AtomArray *ar) const
 
BaseContainerGetParameterI (const DescID &id, AtomArray *ar)
 
Bool SetParameter (const DescID &id, const BaseContainer &param, const DescID &groupid)
 
void * BrowseInit ()
 
Bool GetNext (void *handle, const BaseContainer **bc, DescID &id, DescID &groupid)
 
void BrowseFree (void *&handle)
 
DescEntry * GetFirst (const AtomArray &op)
 
DescEntry * GetNext (DescEntry *de)
 
DescEntry * GetDown (DescEntry *de)
 
void GetDescEntry (DescEntry *de, const BaseContainer **bc, DescID &descid)
 
SubDialogCreateDialogI ()
 
void FreeDialog (SubDialog *dlg)
 
Bool CreatePopupMenu (BaseContainer &menu)
 
Bool GetPopupId (Int32 id, const DescID &descid)
 
Bool CheckDescID (const DescID &searchid, const AtomArray &ops, DescID *completeid)
 
Bool GetSubDescriptionWithData (const DescID &did, const AtomArray &op, RESOURCEDATATYPEPLUGIN *resdatatypeplugin, const BaseContainer &bc, DescID *singledescid)
 
const DescIDGetSingleDescID ()
 
void SetSingleDescriptionMode (const DescID &descid)
 

Private Member Functions

 Description ()
 
 ~Description ()
 

Alloc/Free

static DescriptionAlloc ()
 
static void Free (Description *&description)
 

Constructor & Destructor Documentation

§ Description()

Description ( )
private

§ ~Description()

~Description ( )
private

Member Function Documentation

§ Alloc()

static Description* Alloc ( )
static

Allocates a description. Destroy the allocated description with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Returns
The allocated description, or nullptr if the allocation failed.

§ Free()

static void Free ( Description *&  description)
static

Destructs descriptions allocated with Alloc(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in,out]descriptionThe description to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

§ LoadDescription() [1/3]

Bool LoadDescription ( const BCResourceObj *  bc,
Bool  copy 
)

Loads a description from a BCResourceObj, such as the one returned from GetDescription().

Warning
Existing entries are lost.
Parameters
[in]bcThe BCResourceObj to load the description from.
[in]copytrue if the description should be copied, otherwise the objects will share the same internal data so that changes to one affects the other.
Returns
true if the description was loaded, otherwise false.

§ LoadDescription() [2/3]

Bool LoadDescription ( Int32  id)

Loads a description by ID. The ID must have been registered with RegisterDescription().

Warning
Existing entries are lost.
Parameters
[in]idThe description ID, for example Obase.
Returns
true if the description was loaded, otherwise false.

§ LoadDescription() [3/3]

Bool LoadDescription ( const String id)

Loads a description by name. The description name must have been registered with RegisterDescription().

Warning
Existing entries are lost.
Parameters
[in]idThe description name, for example "Obase".
Returns
true if the description was loaded, otherwise false.

§ SortGroups()

Bool SortGroups ( )

Private.

§ GetDescription()

const BCResourceObj* GetDescription ( )

Retrieves the internal pointer of the description.

Returns
The internal description pointer.

§ GetParameter()

const BaseContainer* GetParameter ( const DescID id,
BaseContainer temp,
AtomArray ar 
) const

Retrieves the information container for a description parameter.

Parameters
[in]idThe description ID.
[out]tempWhen the parameter is of a dynamic type that does not already exist as predefined container, i.e. not returnable as pointer, the result is the address of temp, where temp allows to store the data.
In this case nullptr is returned.
[out]arMost of the time this can be just AtomArray(). However dynamic descriptions (like sub-descriptions of a gradient or dynamic XPresso node) need an array of elements the parameter is assigned to.
Returns
The information container, or nullptr if temp was used. The description owns the pointed container.

§ GetParameterI()

BaseContainer* GetParameterI ( const DescID id,
AtomArray ar 
)

Retrieves a pointer to the information container for a description parameter.

Parameters
[in]idThe description ID.
[out]arMost of the time this can be just AtomArray(). However dynamic descriptions (like sub-descriptions of a gradient or dynamic XPresso node) need an array of elements the parameter is assigned to.
Returns
The information container. The description owns the pointed container.

§ SetParameter()

Bool SetParameter ( const DescID id,
const BaseContainer param,
const DescID groupid 
)

Inserts a description parameter into the collection.

Parameters
[in]idThe description ID.
[in]paramThe settings for the new parameter.
[in]groupidThe ID of the parameter's group, or DESCID_ROOT.
Returns
true if the parameter was inserted, otherwise false.

§ BrowseInit()

void* BrowseInit ( )

Starts browsing the parameters linearly.

Warning
After browsing is done done BrowseFree() must be called.
Returns
The browse handle.

§ GetNext() [1/2]

Bool GetNext ( void *  handle,
const BaseContainer **  bc,
DescID id,
DescID groupid 
)

Retrieves the next parameter in a browse sequence initialized with BrowseInit().

Parameters
[in]handleThe browse handle returned by BrowseInit().
[out]bcAssigned the settings for the retrieved parameter. The caller owns the pointed base container.
[out]idAssigned the ID of the retrieved parameter.
[out]groupidAssigned the group ID of the retrieved parameter.
Returns
true if a new parameter was retrieved, otherwise the sequence is finished.

§ BrowseFree()

void BrowseFree ( void *&  handle)

Frees browse handles from BrowseInit().

Parameters
[in,out]handleThe handle to free. Assigned nullptr.

§ GetFirst()

DescEntry* GetFirst ( const AtomArray op)

Gets a handle to the first description entry. Use GetDescEntry() to access the information and GetNext() or GetDown() to browse the hierarchy.

Parameters
[in]opMost of the time this can be just AtomArray(). However dynamic descriptions (like sub-descriptions of a gradient or dynamic XPresso node) need an array of elements the parameter is assigned to.
Returns
The description entry handle.

§ GetNext() [2/2]

DescEntry* GetNext ( DescEntry *  de)

Gets the next description entry handle.

Parameters
[in]deThe current description entry handle.
Returns
The next description entry handle.

§ GetDown()

DescEntry* GetDown ( DescEntry *  de)

Gets the child description entry handle.

Parameters
[in]deThe current description entry handle.
Returns
The child description entry handle.

§ GetDescEntry()

void GetDescEntry ( DescEntry *  de,
const BaseContainer **  bc,
DescID descid 
)

Retrieves the data for a description entry handle.

Parameters
[in]deThe current description entry handle.
[out]bcAssigned the settings for the retrieved parameter. The caller owns the pointed base container.
[out]descidAssigned the ID of the retrieved parameter.

§ CreateDialogI()

SubDialog* CreateDialogI ( )

Private.

§ FreeDialog()

void FreeDialog ( SubDialog dlg)

Private.

§ CreatePopupMenu()

Bool CreatePopupMenu ( BaseContainer menu)

Builds a popup menu for choosing a parameter in the description.

Parameters
[out]menuAssigned the menu container.
Returns
true if the menu was built, otherwise false.

§ GetPopupId()

Bool GetPopupId ( Int32  id,
const DescID descid 
)

Private.

§ CheckDescID()

Bool CheckDescID ( const DescID searchid,
const AtomArray ops,
DescID completeid 
)

Checks if a description ID searchid exists for the given objects ops (usually only one single object is passed as otherwise the smallest common nominator is returned).
If completeid != nullptr and the return value is true the complete ID will be assigned to completeid.

Note
Complete ID means that all parts of the DescLevel are filled with appropriate data.
For example if the DescID passed is:
DescID(DescLevel(ID_BASEOBJECT_POSITION, 0, 0), DescLevel(VECTOR_X, 0, 0))
CheckDescID() will return:
Parameters
[in]searchidThe partial ID.
[in]opsMost of the time this can be just AtomArray(). However dynamic descriptions (like sub-descriptions of a gradient or dynamic XPresso node) need an array of elements the parameter is assigned to.
[out]completeidAssigned the complete ID.
Returns
true if a description ID searchid exists, otherwise false.

§ GetSubDescriptionWithData()

Bool GetSubDescriptionWithData ( const DescID did,
const AtomArray op,
RESOURCEDATATYPEPLUGIN *  resdatatypeplugin,
const BaseContainer bc,
DescID singledescid 
)

Retrieves dynamic sub-description data (e.g. the gradient data type).

Parameters
[in]didThe description ID.
[in]opThe current objects.
[in]resdatatypepluginThe resource data type plug, retrieved with FindResourceDataTypePlugin().
[out]bcThe existing container for the data type.
[in]singledescidShould be nullptr.
Returns
true if successful, otherwise false.

§ GetSingleDescID()

const DescID* GetSingleDescID ( )

Private.

§ SetSingleDescriptionMode()

void SetSingleDescriptionMode ( const DescID descid)

Private.