Inherits SimObject.

Inherited by ModuleDefinition, and NameTags.

Public Member Functions
void	add (obj1,[obj2]*)

void	bringToFront (object)

void	callOnChildren (string method,[string args]*)

void	clear ()

void	deleteObjects ()

int	findObjectByInternalName (string name,[bool searchChildren]?)

int	getCount ()

int	getObject (index)

bool	isMember (object)

void	listObjects ()

void	pushToBack (object)

void	remove (obj1,[obj2]*)

void	reorderChild (SimObject child1, SimObject child2)

Public Member Functions inherited from SimObject
string	call (functionName,[args]*)

int	clone ([bool copyDynamicFields?=false]?)

void	delete ()

void	dump ()

void	dumpClassHierarchy ()

const char *	getClassName ()

string	getClassNamespace ()

string	getDynamicField (index)

int	getDynamicFieldCount ()

string	getField (int index)

int	getFieldCount ()

const char *	getFieldType (fieldName)

const char *	getFieldValue (fieldName)

int	getGroup ()

int	getId ()

string	getInternalName ()

const char *	getName ()

string	getProgenitorFile ()

string	getSuperClassNamespace ()

int	getType ()

bool	isChildOfGroup ()

bool	isMemberOfClass (string classname)

bool	isMethod (const char *methodName)

bool	isMethod (string method name)

bool	isTimerActive ()

bool	save (fileName,[selectedOnly]?)

int	schedule (time, command,[arg]*)

void	setClassNamespace ()

bool	setFieldValue (fieldName, value)

void	setInternalName (string InternalName)

void	setName (newName)

void	setProgenitorFile (file)

void	setSuperClassNamespace ()

bool	startTimer (callbackFunction, float timePeriod,[repeat]?)

void	stopTimer ()

Additional Inherited Members
Static Public Member Functions inherited from SimObject
static S32 QSORT_CALLBACK	compareFields (const void a, const void b)

Detailed Description

A container for a sequence of unique SimObjects. Torque2D will automatically remove references to any SimObjects as they are deleted.

Overview

A SimSet is an ordered set of references to SimObjects. As the name implies, a SimObject can appear no more than once within a particular SimSet. Attempting to add an object to a SimSet twice will not change the SimSet nor warn you. However, a SimObject can be a member of any number of SimSets and acts independently of any SimSet it is in.

A Simset merely references your SimObjects. The deletion of a SimSet does not affect the SimObjects it holds, and removing a SimObject from a SimSet does not delete the SimObject.

If a SimSet contains a SimObject and that SimObject is deleted, that SimObject will also be automatically removed from the SimSet. This is one of its most powerful features.

Note that only SimObjects can be held in SimSets. Strings, for instance, can not. But, because SimObject is the base class for almost all script classes, you can add any script class to a SimSet.

The SimSet's member objects are stored initially in the order of insertion (add()), and can be removed (remove()), retrieved (getObject()), and queried (isMember()). The SimSet can have all its members counted (getCount()), printed (listObjects()), and removed (clear()). A member can be reordered via bringToFront() and pushToBack(), or re-ordered relative to another via reorderChild().

Examples

Creating and Adding

We create the SimSet, then create objects to put in it, then we add them all in.

new SimSet(Fruit);
echo(Fruit.getCount());
> 0
// Apple, Pear, etc will be SimObjects
new SimObject(Apple);
new SimObject(Pear);
new SimObject(Orange);
new SimObject(Fig);
new SimObject(Persimmon);
// add our fruit to the SimSet named Fruit
Fruit.add(Apple);
Fruit.add(Pear);
Fruit.add(Orange);
Fruit.add(Fig);
Fruit.add(Persimmon);
echo(Fruit.getCount());
> 5

Uniqueness

Continuing the above example, each member of the SimSet appears exactly once: the SimSet is a mathematically proper set.

// Apple is already added.
Fruit.add(Apple);
echo(Fruit.getCount());
> 5

Re-ordering

The members of a SimSet are well ordered. Let us move a different object to the front.

echo(Fruit.getObject(0).getName());
> Apple
Fruit.bringToFront(Persimmon);
echo(Fruit.getObject(0).getName());
> Persimmon

Now we move a different member to the back.

Fruit.pushToBack(Apple);
echo(Fruit.getObject(4).getName());
> Apple

Finally, we move the Fig member to precede Pear. Note that all of the other members retain their relative order.

Fruit.listObjects();
> 2887,"Persimmon": SimObject 
> 2884,"Pear": SimObject 
> 2885,"Orange": SimObject 
> 2886,"Fig": SimObject 
> 2883,"Apple": SimObject 
Fruit.reorderChild(Fig, Pear);
Fruit.listObjects();
> 2887,"Persimmon": SimObject 
> 2886,"Fig": SimObject 
> 2885,"Orange": SimObject 
> 2884,"Pear": SimObject 
> 2883,"Apple": SimObject 

Removing

echo(Fruit.isMember(Apple));
> 1
Fruit.remove(Apple);
echo(Fruit.isMember(Apple));
> 0
// Apple was not deleted
echo(isObject(Apple));
> 1
Fruit.clear();
echo(Fruit.getCount());
> 0
// The fruit SimObjects are not deleted.  For example...
echo(isObject(Persimmon));
> 1

Member Function Documentation

void add	(	obj1	,
		[obj2] *
	)

Appends given SimObject (or list of SimObjects) to the SimSet.

Parameters

obj_1..obj_n list of SimObjects to add

Returns: No return value

void bringToFront ( object )

Brings SimObject to front of set. If the SimObject is not in the set, do nothing.

Returns: No return value.

void callOnChildren	(	string	method,
		[string args] *
	)

Call a method on all objects contained in the set.

Parameters

method	The name of the method to call.
args	The arguments to the method.

Note: This method recurses into all SimSets that are children to the set.

See Also: callOnChildrenNoRecurse" )

void clear ( )

Clears the Simset This does not delete the cleared SimObjects.

Returns: No return value

void deleteObjects ( )

Deletes all the objects in the SimSet.

Returns: No return value

int findObjectByInternalName	(	string	name,
		[bool searchChildren] ?
	)

Returns the object with given internal name

Parameters

name	The internal name of the object you wish to find
searchChildren	Set this true if you wish to search all children as well.

Returns: Returns the ID of the object.

int getCount ( )

Returns: Returns the number of objects in the SimSet

int getObject ( index )

Returns a member SimObject of the SimSet

Parameters

index into this ordered collection (zero-based).

Returns: Returns the ID of the desired object or -1 on failure

bool isMember ( object )

Returns: Returns true if specified object is a member of the set, and false otherwise

void listObjects ( )

Prints the object data within the set

Returns: No return value

void pushToBack ( object )

Sends item to back of set. If the SimObject is not in the set, do nothing.

Returns: No return value.

void remove	(	obj1	,
		[obj2] *
	)

Removes given SimObject (or list of SimObjects) from the SimSet.

Parameters

obj_1..obj_n list of SimObjects to remove The SimObjects are not deleted. An attempt to remove a SimObject that is not present in the SimSet will print a warning and continue.

Returns: No return value

void reorderChild	(	SimObject	child1,
		SimObject	child2
	)

Bring child 1 before child 2 Both SimObjects must already be child objects. If not, the operation silently fails.

Parameters

child1	The child you wish to set first
child2	The child you wish to set after child1

Returns: No return value.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation