GeListNode Manual

About

The class GeListNode is based on C4DAtom and is a base class for many entities of the classic Cinema 4D API. It mostly provides the functionality to organize elements in linked lists and trees.

GeListNode objects are an instance of Tgelistnode.

Access

NodeData::Get() is rarely needed, as a pointer to a GeListNode is typically handed over to virtual functions of NodeData and derived classes:

// This example shows a primitive implementation of Message().
virtual Bool Message(GeListNode* node, Int32 type, void* data)
{
switch (type)
{
case (MSG_UPDATE):
{
break;
}
// more cases

GeListNode is also used in the context of object hierarchies with GeListHead elements.

Allocation/Deallocation

It is possible to create a GeListNode instance of a RegisterNodePlugin() registered node with

Note
These functions are typically not used with third party plugins. They are only useful to handle custom NodeData plugins.
// This example allocates a node of the type ID_PYTHONSCRIPT.
// This node can be used to execute a Python script.
String python;
python += "print(\"this is python\")";
if (op == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
op->Message(MSG_SCRIPT_EXECUTE, nullptr);
blDelete(op);

Lists and Trees

Navigation in Lists and Trees

GeListNode based elements can be organized in lists and trees. A GeListNode based entity can reference the accompanying elements in that hierarchy. If no element is referenced, nullptr is returned.

Note
Derived classes often provide overwritten versions of these functions for convenience.

The typical Cinema 4D workflow would be:

// This example iterates over a linked list.
// In this case it is the list of all tags of the given BaseObject.
// loop through all tags
for (BaseTag* tag = object->GetFirstTag(); tag; tag = tag->GetNext())
{
ApplicationOutput("Tag: " + tag->GetName());
}

and

// This function walks recursively over the tree of nodes.
static void WalkTreeRec(GeListNode* node)
{
while (node != nullptr)
{
// check if the current node is a BaseList2D object
{
const BaseList2D* const baseList2d = static_cast<BaseList2D*>(node);
ApplicationOutput("Name: " + baseList2d->GetName());
}
// check child objects
WalkTreeRec(node->GetDown());
// check next objects in the list
node = node->GetNext();
}
}
Note
Avoid unnecessary recursion to prevent a stack overflow.

Edit Lists and Trees

A given GeListNode can be inserted into a list or tree or it can be removed from that list or tree:

Note
If a GeListNode is supposed to be deleted it must be removed from its list before.
At any given time a GeListNode can only be inserted into one single list or tree. Before inserting a node into a new list, make sure to remove it from the old one.
// This example switches the position of the given object
// and its parent object in the object tree.
BaseObject* const parentObject = selectedObject->GetUp();
if (parentObject == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// the parent object may or may not have a parent itself
BaseObject* const parentParent = parentObject->GetUp();
// remove both objects from the tree
selectedObject->Remove();
parentObject->Remove();
// insert the selected object
doc->InsertObject(selectedObject, parentParent, nullptr);
// insert the parent object as a child
parentObject->InsertUnder(selectedObject);

Heads and Branches

A GeListHead element is used as the root of a list or tree:

See GeListHead Manual.

A given GeListNode can host multiple internal lists and trees by storing multiple GeListHead objects, called branches. For example the list of tags is a branch of BaseObject. These branches can be accessed with this function:

Valid flags are:

The used BranchInfo struct has the following members:

The branch flags are:

// This example loops through all branches of a given BaseDocument.
// If possible the name of the first branch child object is printed.
BranchInfo info[20]; // 20 is just an arbitrary number, that should be enough to catch all branches
const Int32 branchCount = doc->GetBranchInfo(info, 20, GETBRANCHINFO::NONE);
for (Int32 i = 0; i < branchCount; ++i)
{
const String branchName = info[i].name;
ApplicationOutput(" - Name: " + branchName);
GeListHead* const branchHead = info[i].head;
if (branchHead != nullptr)
{
GeListNode* const child = branchHead->GetFirst();
// check if the child is a BaseList2D object
if (child && child->IsInstanceOf(Tbaselist2d))
{
BaseList2D* const child2D = static_cast<BaseList2D*>(child);
ApplicationOutput(" - First Child Element: " + child2D->GetName());
}
}
}

NodeData

The base class for most classic plugins is NodeData. NodeData based plugin classes build the "core" of any plugin based entity of the classic Cinema 4D API. This "core" class can be obtained with:

See also Basic Classes and Plugin Classes.

// This example checks if the given object has the type of a custom plugin class.
// If so, GetNodeData<T>() can be used to get the pointer to the plugin class.
// check if the selected object is an "ExampleGenerator"
if (selectedObject->GetType() == g_exampleGeneratorID)
{
ExampleGenerator* const exampleGenerator = selectedObject->GetNodeData<ExampleGenerator>();
if (exampleGenerator)
{
exampleGenerator->MemberFunction();
}
}
Warning
It is only possible to cast the retrieved object into a specific class in the module where this class is defined.
Some components of Cinema 4D are not implemented as a plugin so there is no NodeData instance to access.

Document

GeListNode based objects can also be part of a BaseDocument:

Warning
Always check the returned document pointer for nullptr, as the element might not be part of any document.
// This example from a NodeData::Message() function uses
// the BaseDocument of the given GeListNode.
// get the document that hosts the given node
const BaseDocument* doc = node->GetDocument();
if (doc)
{
GeData geData;
// read the BaseLink parameter from the node
if (node->GetParameter(EXAMPLE_GENERATOR_LINK, geData, DESCFLAGS_GET::NONE))
{
// resolve the link using the received document
C4DAtom* const atom = geData.GetLinkAtom(doc, Tbaselist2d);
if (atom)
{
BaseList2D* const baseList2D = static_cast<BaseList2D*>(atom);
ApplicationOutput(baseList2D->GetName());
}
}
}

Infos

Additional information can be accessed:

// This example casts the given BaseObject into SplineObject
// if it is a spline or if it is a spline generator.
SplineObject* spline = nullptr;
// check if the object is a "Spline" object
if (object->IsInstanceOf(Ospline))
spline = ToSpline(object);
// check if the object is a spline generator
else if (object->GetInfo() & OBJECT_ISSPLINE)
spline = object->GetRealSpline();
if (spline != nullptr)
ApplicationOutput("Spline Object: " + spline->GetName());

NBits

Various settings of an element can be configured by changing a corresponding bit. A list of available bits is defined in NBIT.

The change operations are:

// This example toggles the NBIT_EHIDE of the active object.
BaseObject* const object = doc->GetActiveObject();
if (object == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
object->ChangeNBit(NBIT::EHIDE, NBITCONTROL::TOGGLE);

Further Reading

BaseObject::GetUp
BaseObject * GetUp(void)
Definition: c4d_baseobject.h:268
BranchInfo::name
String name
The human readable name of the branch. (Currently not used.)
Definition: c4d_baselist.h:1185
BranchInfo
Definition: c4d_baselist.h:1182
GeListNode::GetBranchInfo
Int32 GetBranchInfo(BranchInfo *info, Int32 max, GETBRANCHINFO flags)
Definition: c4d_baselist.h:1960
BaseList2D
Definition: c4d_baselist.h:2174
GeData::GetLinkAtom
C4DAtomGoal * GetLinkAtom(const BaseDocument *doc, Int32 instanceof=0) const
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
NBITCONTROL::TOGGLE
@ TOGGLE
Toggle bit.
GeListNode::GetInfo
Int32 GetInfo()
@markPrivate
BaseObject
Definition: c4d_baseobject.h:224
GETBRANCHINFO::NONE
@ NONE
None.
Ospline
#define Ospline
Spline - SplineObject.
Definition: ge_prepass.h:981
NBIT::EHIDE
@ EHIDE
Hide in viewport.
BranchInfo::head
GeListHead * head
Either a GeListNode or a GeListHead for the branch, depending on flags.
Definition: c4d_baselist.h:1184
BaseContainer::SetString
void SetString(Int32 id, const maxon::String &s)
Definition: c4d_basecontainer.h:569
ToSpline
#define ToSpline(op)
Casts a BaseObject* to a SplineObject*.
Definition: c4d_baseobject.h:2198
GeListHead::GetFirst
GeListNode * GetFirst()
Definition: c4d_baselist.h:2067
AllocListNode
GeListNode * AllocListNode(Int32 id)
BaseTag
Definition: c4d_basetag.h:46
blDelete
#define blDelete(v)
Destructs objects derived from BaseList2D. It is basically the same as BaseList2D::Free().
Definition: c4d_baselist.h:2859
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
ID_PYTHONSCRIPT
#define ID_PYTHONSCRIPT
Definition: ge_prepass.h:4837
GeListNode
Represents a C4DAtom that resides in a 4D list.
Definition: c4d_baselist.h:1797
MSG_UPDATE
#define MSG_UPDATE
Must be sent if the bounding box has to be recalculated. (Otherwise use MSG_CHANGE....
Definition: c4d_baselist.h:340
String
Definition: c4d_string.h:38
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:495
GeListNode::GetDown
GeListNode * GetDown()
Definition: c4d_baselist.h:1824
BaseList2D::GetDataInstanceRef
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2329
MSG_SCRIPT_EXECUTE
#define MSG_SCRIPT_EXECUTE
Execute the script. (No arguments.)
Definition: ge_prepass.h:4887
BaseObject::GetRealSpline
SplineObject * GetRealSpline(void)
Tbaselist2d
#define Tbaselist2d
2D list.
Definition: ge_prepass.h:943
GeData
Definition: c4d_gedata.h:82
C4DAtom
Definition: c4d_baselist.h:1361
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
GeListNode::GetDocument
BaseDocument * GetDocument()
Definition: c4d_baselist.h:1945
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
C4DAtom::Message
Bool Message(Int32 type, void *data=nullptr)
Definition: c4d_baselist.h:1424
GeListNode::Remove
void Remove()
Definition: c4d_baselist.h:1884
GeListNode::GetNext
GeListNode * GetNext()
Definition: c4d_baselist.h:1812
DESCFLAGS_GET::NONE
@ NONE
None.
SplineObject
Represents a spline object.
Definition: c4d_baseobject.h:2030
PYTHONSCRIPT_TEXT
#define PYTHONSCRIPT_TEXT
String Script.
Definition: ge_prepass.h:4898
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55
BaseTag::GetNext
BaseTag * GetNext(void)
Definition: c4d_basetag.h:78
BaseDocument::GetActiveObject
BaseObject * GetActiveObject(void)
C4DAtom::IsInstanceOf
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1403
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2348
OBJECT_ISSPLINE
#define OBJECT_ISSPLINE
Spline object.
Definition: ge_prepass.h:903
BaseObject::GetFirstTag
BaseTag * GetFirstTag(void)
GeListNode::InsertUnder
void InsertUnder(GeListNode *bl)
Definition: c4d_baselist.h:1865
GeListHead
Definition: c4d_baselist.h:2010
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
BaseDocument
Definition: c4d_basedocument.h:490
BaseContainer
Definition: c4d_basecontainer.h:46