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:

GeListHead::Alloc(): Creates a new GeListHead.
GeListHead::Free(): Destroys the given GeListHead.

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:

GeListNode::GetListHead(): Returns the GeListHead root of the element's 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 != nullptr)
    {
      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)
  {
    ApplicationOutput("Branch " + String::IntToString(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());
      }
    }
  }

Navigation

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

GeListHead::InsertBefore(): Inserts the element before the given GeListNode in the list.
GeListHead::InsertAfter(): Inserts the element after the given GeListNode in the list.
GeListHead::InsertUnder(): Inserts the element under the given GeListNode.
GeListHead::InsertUnderLast(): Inserts the element as the last child element under the given GeListNode.
GeListHead::Remove(): Removes the element from the 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(): Sets the parent of the GeListHead.
GeListHead::GetParent(): Returns the parent of the GeListHead.

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:

GeListHead::GetFirst(): Returns the first element of the list.
GeListHead::GetLast(): Returns the last element of the list.

New elements can be added to the list with:

GeListHead::InsertFirst(): Inserts the given element as the first element of the list.
GeListHead::InsertLast(): Inserts the given element as the last element of the list.
GeListHead::Insert(): Inserts the given element as a child or after another elements.

All elements of a list can easily be deleted with:

GeListHead::FlushAll(): Clears the list. The list elements will be properly deallocated.

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

Table of Contents