GeListHead Manual

About

A GeListHead object is the root of a list or tree of GeListNode elements. See also GeListNode Manual.

GeListHead objects are an instance of ID_LISTHEAD.

Allocation/Deallocation

GeListHead objects can be created with the usual tools:

The creation of GeListHead objects is typically only needed in custom NodeData based plugin classes that internally store custom objects (see also Heads and Branches).

Access

It is possible to get the root GeListHead from every member of that list or tree:

// This example loops through all selected objects and tags.
// For each selected element the GeListHead is accessed to
// get the first child object of that list.
doc->GetSelection(selection);
// loop through all elements of the selection
for (Int32 i = 0; i < selection->GetCount(); ++i)
{
C4DAtom* const atom = selection->GetIndex(i);
if (atom == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// check if the C4DAtom is a GeListNode
if (atom->IsInstanceOf(Tgelistnode) == false)
continue;
GeListNode* const node = static_cast<GeListNode*>(atom);
GeListHead* const head = node->GetListHead();
// check if the list head can be accessed
if (head)
{
GeListNode* const child = head->GetFirst();
// check if the child is a BaseList2D object
if (child && child->IsInstanceOf(Tbaselist2d))
{
const BaseList2D* const child2D = static_cast<BaseList2D*>(child);
ApplicationOutput("First Child Element: " + child2D->GetName());
}
}
}

GeListHead objects can also be obtained using GeListNode::GetBranchInfo():

// 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)
{
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());
}
}
}

See also GeListNode Heads and Branches and BaseList2D::GetMain() at BaseList2D Read-Only Properties.

Navigation

GeListHead itself is based on GeListNode. So instances of GeListHead can be organized in a list or tree:

See Edit Lists and Trees.

Parent

The parent of a GeListHead instance is typically the object that owns that instance/branch.

GeListHead::SetParent() is normally used directly after the creation of a GeListHead instance.

// This example allocates a new GeListHead in a custom object's "Init" function.
// The "node" argument of "Init" is used as the parent object.
_branchHead = GeListHead::Alloc();
if (_branchHead == nullptr)
return false;
_branchHead->SetParent(node);
_branchName = String("My Branch");

List Content

A GeListHead is a root of a list of GeListNode elements. These elements can be obtained with:

New elements can be added to the list with:

All elements of a list can easily be deleted with:

// This example removes all existing markers using the list head.
BaseList2D* const marker = GetFirstMarker(doc);
if (marker)
{
GeListHead* const head = marker->GetListHead();
if (head == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
head->FlushAll();
}

Further Reading