Main Index : Reference :

BaseContainer

Description

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

Definition

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

  [int] GetId();
  [bool] SetId([int] id); 
  
  // Setters
  [bool] SetData([int] id, [any type] data); // Recommended!
  [bool] InsData([int] id, [any type] data);

  // Random access
  [any type] GetData([int] id);
  [int] GetInt([int] id, [[int] preset = 0]);
  [float] GetFloat([int] 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)]);
  [Marker] GetMarker([int] id, [[Marker] preset = new(Marker)]);
  [BaseContainer] GetContainer([int] id);

  // Sequential access
  [int] FindIndex([int] id);
  [int] GetIndexId([int] index);
  [any type] GetIndexData([int] index);

  // Linked objects
  [BaseList2D] GetObject([int] id, [BaseDocument] doc, [[int] instanceof]);
  [bool] SetObject([int] id, [BaseList2D] link);
	
  [bool] CopyTo([BaseContainer] bc);
  [BaseContainer] GetClone();
}

Explanation

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 C4D 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.

Members

GetId()

[int] GetId();

Returns the id of the container.

SetId( id )

[bool] SetId([int] id);

Sets the id of the container to id. Returns TRUE if successful.


SetData( id, data )

[bool] SetData([int] id, [any type] data);

Sets the element with the specified id to data. Overwrites any previous elements with that id. Returns TRUE if successful.

InsData( id, data )

[bool] InsData([int] id, [any type] 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! Returns TRUE if successful.


GetData( id )

[any type] GetData([int] id);

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

GetInt( id, preset )

[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.

GetFloat( id, preset )

[float] GetFloat([int] 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.

GetVector( id, preset )

[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.


GetString( id, preset )

[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.

GetMatrix( id, preset )

[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.


GetFilename( id, preset )

[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.

GetTime( id, preset )

[BaseTime] GetTime([int] id, [[BaseTime] preset = new(Time)]);

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.

GetMarker( id, preset )

[Marker] GetMarker([int] id, [[Marker] preset = new(Marker)]);

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.

GetContainer( id )

[BaseContainer] GetContainer([int] id);

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


FindIndex( id )

[int] FindIndex([int] id);

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

GetIndexId( index )

[int] GetIndexId([int] index);

Return the id of the element with the specified sequential index. If there's no such element it returns NOTOK.

GetIndexData( index )

[any type] GetIndexData([int] index);

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


GetObject( id, doc, instanceof )

[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.

SetObject( id, obj )

[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. Returns TRUE if successful.


CopyTo( bc )

[bool] CopyTo([BaseContainer] bc);

Copies the contents of the container to the container bc. Returns TRUE if successful.

GetClone()

[BaseContainer] GetClone();

Returns a copy of the container.

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);