AtomArray Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Array Elements
• Drag and Drop
• Copy
• Further Reading

About

An AtomArray object is used to store multiple pointers to C4DAtom based elements. See C4DAtom Manual.

Access

An AtomArray is typically used to define a selection of scene elements:

• BaseDocument::GetSelection(): Fills the given AtomArray with the selected objects and tags.
• BaseDocument::SetSelection(): Adds the given element to the current selection or starts a new selection.
• BaseDocument::GetActiveObjects(): Returns the current multi-selection of BaseObject objects.
• BaseDocument::GetActivePolygonObjects(): Returns the currently selected polygon objects.
• BaseDocument::GetActiveObjectsFilter(): Returns the currently selected BaseObjects that match the given filters.
• BaseDocument::GetActiveMaterials(): Returns the current multi-selection of BaseMaterial objects.
• BaseDocument::GetActiveTags(): Returns the current multi-selection of BaseTag objects.

See also BaseDocument Selections.

Allocation/Deallocation

An AtomArray object can be created with the usual tools.

• AtomArray::Alloc(): Creates a new AtomArray.
• AtomArray::Free(): Delete the given AtomArray.

Array Elements

Several functions can be used to edit the elements of the array:

• AtomArray::GetCount(): Returns the number of elements in the array.
• AtomArray::GetIndex(): Returns the C4DAtom pointer stored at the given index.
• AtomArray::Append(): Appends a C4DAtom pointer to the array.
• AtomArray::Flush(): Flushes the array. Won't delete the referenced elements.
• AtomArray::Remove(): Removes the given C4DAtom pointer from the array.
• AtomArray::Find(): Returns the index of the given C4DAtom pointer.

  // This example creates an AtomArray to get the selected elements of a BaseDocument.
 
  AutoAlloc<AtomArray> selection;
  if (selection == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // get selection
  doc->GetSelection(selection);
 
  // loop through selected elements
  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 given C4DAtom is a BaseList2D element
    if (atom->IsInstanceOf(Tbaselist2d))
    {
      const BaseList2D* const baseList2d = static_cast<BaseList2D*>(atom);
      ApplicationOutput("Name: " + baseList2d->GetName());
    }
  }

Objects of a certain type can be removed from the array:

• AtomArray::FilterObject(): Removes object pointers based on the given parameters. See C4DAtom Type.
• AtomArray::FilterObjectChildren(): Removes all objects that have a parent (or ancestor) in the array.

    // This example gets all selected objects of the given BaseDocument.
    // The selection is reduced to point objects.
 
    // get selection
    doc->GetActiveObjects(selection, GETACTIVEOBJECTFLAGS::NONE);
 
    selection->FilterObject(NOTOK, Opoint);
 
    const Int32 objCount = selection->GetCount();
    ApplicationOutput("Number of selected point objects: " + String::IntToString(objCount));

Two AtomArray objects can be compared:

• AtomArray::Compare(): Returns true if the arrays are identical.

Drag and Drop

AtomArray objects are also often used to define arguments of drag and drop operations.

• AtomArray::GetUserID(): Returns the user ID.
• AtomArray::SetUserID(): Sets the user ID.
• AtomArray::GetUserData(): Returns a pointer the user data.
• AtomArray::SetUserData(): Sets the pointer to the user data.
• AtomArray::GetPreferred(): Returns the preferred element.
• AtomArray::SetPreferred(): Sets the preferred element.

      // This example checks the received drag&drop message in a GeDialog.
 
      case BFM_DRAGRECEIVE:
      {
        Int32 type = 0;
        void* object = nullptr;
 
        // get drag object
        GetDragObject(msg, &type, &object);
 
        // the object is an AtomArray
        if (type == DRAGTYPE_ATOMARRAY && object)
        {
          AtomArray* const dragObjects = static_cast<AtomArray*>(object);
 
          // end of drag
          if (msg.GetInt32(BFM_DRAG_FINISHED))
          {
            ApplicationOutput(".........."_s);
 
            // check UserID
            // NOTE: replace ID_OBJECTMANAGER with 100004709 define with real value to get rid of '#include "../../../../resource/modules/newman/c4d_symbols.h"'
            if (dragObjects->GetUserID() == 100004709)
              ApplicationOutput("Drag from the Object Manager"_s);
 
            // loop through all dragged objects
            for (Int32 i = 0; i < dragObjects->GetCount(); ++i)
            {
              C4DAtom* draggedAtom = dragObjects->GetIndex(i);
 
              // PrintName() is a custom function
              PrintName(draggedAtom);
            }
 
            // get preferred element
            C4DAtom* preferredAtom = dragObjects->GetPreferred();
 
            // PrintName() is a custom function
            PrintName(preferredAtom);
          }
          else
          {
            return SetDragDestination(MOUSE_COPY);
          }
        }
 
        return false;
        break;
      }

Copy

AtomArray objects can be copied with:

• AtomArray::CopyTo(): Copies the array into the given AtomArray.
• AtomArray::CopyToFilter(): Copies the array into the given AtomArray while applying the filter arguments.

    // This example gets all selected objects of the given BaseDocument.
    // The point object selection is copied into a separate AtomArray.
 
    // get selection
    doc->GetActiveObjects(selection, GETACTIVEOBJECTFLAGS::NONE);
 
    AutoAlloc<AtomArray> pointObjects;
    if (pointObjects == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // copy the references of all point object into the given AtomArray
    if (selection->CopyToFilter(pointObjects, NOTOK, Opoint))
    {
      const Int32 objCount = pointObjects->GetCount();
      ApplicationOutput("Number of selected point objects: " + String::IntToString(objCount));
    }

Further Reading

• C4DAtom Manual