#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)
  {
    AutoAlloc<Description> desc;
    if (!desc)
      return String();
    if (!op->GetDescription(desc, DESCFLAGS_DESC::NONE))
      return String();
    const BaseContainer *bc = desc->GetParameterI(ConstDescID(DescLevel(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 BaseContainer *	GetParameter (const DescID &id, BaseContainer &temp, AtomArray *ar) const

BaseContainer *	GetParameterI (const DescID &id, AtomArray *ar)

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

void *	BrowseInit () const

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

void	BrowseFree (void *&handle) const

DescEntry *	GetFirst (const AtomArray &op)

DescEntry *	GetNext (DescEntry *de)

DescEntry *	GetDown (DescEntry *de)

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

SubDialog *	CreateDialogI ()

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 DescID *	GetSingleDescID ()

void	SetSingleDescriptionMode (const DescID &descid)

Private Member Functions
	Description ()

	~Description ()

Alloc/Free
static Description *	Alloc ()

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] description The 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]	bc	The `BCResourceObj` to load the description from.
[in]	copy	true 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] id The 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] id The 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]	id	The description ID.
[out]	temp	When 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]	ar	Most 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]	id	The description ID.
[out]	ar	Most 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]	id	The description ID.
[in]	param	The settings for the new parameter.
[in]	groupid	The ID of the parameter's group, or DESCID_ROOT.

Returns: true if the parameter was inserted, otherwise false.

◆ BrowseInit()

void* BrowseInit ( ) const

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
	)		const

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

Parameters

[in]	handle	The browse handle returned by BrowseInit().
[out]	bc	Assigned the settings for the retrieved parameter. The caller owns the pointed base container.
[out]	id	Assigned the ID of the retrieved parameter.
[out]	groupid	Assigned 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 ) const

Frees browse handles from BrowseInit().

Parameters

[in,out] handle The 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] op Most 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] de The current description entry handle.

Returns: The next description entry handle.

◆ GetDown()

DescEntry* GetDown ( DescEntry * de )

Gets the child description entry handle.

Parameters

[in] de The 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]	de	The current description entry handle.
[out]	bc	Assigned the settings for the retrieved parameter. The caller owns the pointed base container.
[out]	descid	Assigned 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] menu Assigned 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:
ConstDescID(DescLevel(ID_BASEOBJECT_POSITION, 0, 0), DescLevel(VECTOR_X, 0, 0))

VECTOR_X
@ VECTOR_X
X component.
Definition: lib_description.h:279

CheckDescID() will return:
ConstDescID(DescLevel(ID_BASEOBJECT_POSITION, DTYPE_VECTOR, ID_BASEOBJECT_GROUP1), DescLevel(VECTOR_X, DTYPE_REAL, ...))

DTYPE_VECTOR
@ DTYPE_VECTOR
Vector
Definition: lib_description.h:70

DTYPE_REAL
@ DTYPE_REAL
Float
Definition: lib_description.h:68

ID_BASEOBJECT_GROUP1
@ ID_BASEOBJECT_GROUP1
Definition: obase.h:54

Parameters

[in]	searchid	The partial ID.
[in]	ops	Most 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]	completeid	Assigned 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]	did	The description ID.
[in]	op	The current objects.
[in]	resdatatypeplugin	The resource data type plug, retrieved with FindResourceDataTypePlugin().
[out]	bc	The existing container for the data type.
[in]	singledescid	Should be nullptr.

Returns: true if successful, otherwise false.

◆ GetSingleDescID()

const DescID* GetSingleDescID ( )

Private.

◆ SetSingleDescriptionMode()

void SetSingleDescriptionMode ( const DescID & descid )

Private.

Detailed Description

Public Member Functions

Private Member Functions

Alloc/Free

Constructor & Destructor Documentation

◆ Description()

◆ ~Description()

Member Function Documentation

◆ Alloc()

◆ Free()

◆ LoadDescription() [1/3]

◆ LoadDescription() [2/3]

◆ LoadDescription() [3/3]

◆ SortGroups()

◆ GetDescription()

◆ GetParameter()

◆ GetParameterI()

◆ SetParameter()

◆ BrowseInit()

◆ GetNext() [1/2]

◆ BrowseFree()

◆ GetFirst()

◆ GetNext() [2/2]

◆ GetDown()

◆ GetDescEntry()

◆ CreateDialogI()

◆ FreeDialog()

◆ CreatePopupMenu()

◆ GetPopupId()

◆ CheckDescID()

◆ GetSubDescriptionWithData()

◆ GetSingleDescID()

◆ SetSingleDescriptionMode()