Index : Reference :

BaseContainer

A class used for storing values in many parts of the SDK.

A container is a collection of individual values. Each value has its own id and type. There is no guarantee for a particular order of the values, nor that a value is there in the container. 90% of Amber's internal values are stored in containers and all messages are working with container, so this class is a very essential part of the SDK.

Normally if you want to access a container value you try to get it with GetData(id). If you succeed, the container will return the correct value. If no value with specified id exists, the container will return nil.

Instead of always checking if there is a value, and if it's the right type, there are some convenience functions like GetFloat() that one can use. These function always returns a value of the right type, even when no value with the specified id was found in the container. Additionally you can specify a default value for this case. So in the following example
  
  var v1 = container->GetFloat(1024);
  var v2 = container->GetFloat(1024,100.0);
  

if there is a value with id 1024 in the container you will get the corresponding value, else v1 will be filled with 0.0 (the default empty value) and v2 with 100.0. If used properly these functions guarantee that a plugin will function even if a future version of CINEMA 4D doesn't support all ids any more or introduces new ids.

A container can carry any number of child containers, hence the GetID function and the option to give every container an individual id with the constructor.

One should always keep in mind that there is no guarantee for a value to be in the container. Therefore one should always use default values when accessing the values. Maybe the plugin won't be able to change some values, but it will be working anyway.

Remember: Though the use of containers is very easy, you should try not to store complex data like arrays in them cause this is very time and memory consuming. Containers are ideal for storing just some dozen values, but for a point array you should use C.O.F.F.E.E. arrays.

Example:
  
  // Stores a value in the container
  var bc = new(BaseContainer);
  bc->SetData(MY_ID, "Hello World!");
  
  // Retrieves the value
  var myString = bc->GetString(MY_ID);
  

Definition

class BaseContainer
{
public:
  BaseContainer(int id = NOTOK);

  int GetId();
  bool SetId(int id);


  //Setters
  bool SetData(int id, anytype data);
  bool InsData(int id, anytype data);


  //Random access
  anytype GetData(int id);
  int GetInt(int id, int preset  =  0);
  float GetFloat(ind id, float preset  =  0.0);
  vector GetVector(int id, vector preset  =  vector(0.0));
  string GetString(int id, string preset  =  "");
  Matrix GetMatrix(int id, Matrix preset  =  new(Matrix));
  Filename GetFilename(int id, Filename preset  =  new(Filename));
  BaseTime GetTime(int id, BaseTime preset  =  new(BaseTime));
  GeMarker GetMarker(int id, GeMarker preset  =  new(GeMarker));
  BaseContainer GetContainer(int id);


  //Sequential access
  bool FindIndex(int id);
  int GetIndexId(int index);
  anytype GetIndexData(int index);


  //Linked objects
  BaseList2D GetObject(int id, BaseDocument doc, int instanceof);
  bool SetObject(int id, BaseList2D obj);

  bool CopyTo(BaseContainer bc);
  BaseContainer GetClone();
};

Members

BaseContainer(int id = NOTOK)

Class Constructor

int GetId()

Returns the id of the container.

bool SetId(int id)

Sets the id of the container to id.

Return
bool

TRUE if successful, otherwise FALSE.

bool SetData(int id, anytype data)

Sets the element with the specified id to data. Overwrites any previous elements with that id.

Return
bool

TRUE if successful, otherwise FALSE.

bool InsData(int id, anytype data)

Inserts an element with the specified id and sets it to data. It doesn't overwrite previous elements. This isn't recommended because of the risk for double ids. Use SetData() instead!

Return
bool

TRUE if successful, otherwise FALSE.

anytype GetData(int id)

Returns the element with the specified id. If there is no such element it returns NIL.

int GetInt(int id, int preset = 0)

Returns the integer element with the specified id, if such an element exists. Otherwise it returns the preset value, or 0 if no preset was specified.

float GetFloat(ind id, float preset = 0.0)

Returns the float element with the specified id, if such an element exists. Otherwise it returns the preset value, or 0.0 if no preset was specified.

vector GetVector(int id, vector preset = vector(0.0))

Returns the vector element with the specified id, if such an element exists. Otherwise it returns the preset value, or a zero vector if no preset was specified.

string GetString(int id, string preset = "")

Returns the string element with the specified id, if such an element exists. Otherwise it returns the preset value, or an empty string if no preset was specified.

Matrix GetMatrix(int id, Matrix preset = new(Matrix))

Returns the matrix element with the specified id, if such an element exists. Otherwise it returns the preset value, or an identity matrix if no preset was specified.

Filename GetFilename(int id, Filename preset = new(Filename))

Returns the filename element with the specified id, if such an element exists. Otherwise it returns the preset value, or an empty filename object if no preset was specified.

BaseTime GetTime(int id, BaseTime preset = new(BaseTime))

Returns the time element with the specified id, if such an element exists. Otherwise it returns the preset value, or an empty time object if no preset was specified.

GeMarker GetMarker(int id, GeMarker preset = new(GeMarker))

Returns the marker element with the specified id, if such an element exists. Otherwise it returns the preset value, or an empty marker if no preset was specified.

BaseContainer GetContainer(int id)

Returns the child container element with the specified id, if such an element exists. Otherwise it returns NIL.

bool FindIndex(int id)

Returns TRUE if there exists an item with the specified id. Otherwise returns FALSE.

Return
bool

TRUE if there exists an item with the specified id, otherwise FALSE.

int GetIndexId(int index)

Returns the element with the specified sequential index. If there's no such element it returns NIL.

anytype GetIndexData(int index)

Returns the element with the specified sequential index. If there's no such element it returns NIL.

BaseList2D GetObject(int id, BaseDocument doc, int instanceof)

Returns the baselist element pointed to by the link with the specified id, if such an element exists. Otherwise it returns NIL. You need to pass the document to evaluate the link in. Optionally you can pass a type ID in instanceof (e.g. Obase for objects) to force the function to only return elements of that type.

bool SetObject(int id, BaseList2D obj)

Sets the element with the specified id to a link to obj. Overwrites any previous elements with that id.

Return
bool

TRUE if successful, otherwise FALSE.

bool CopyTo(BaseContainer bc)

Copies the contents of the container to the container bc.

Return
bool

TRUE if successful, otherwise FALSE.

BaseContainer GetClone()

Returns a copy of the container.


Copyright 2014 MAXON. See Plugin Cafe for the latest version. Last modified: 2014-10-03