SimSet Class Reference

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 ()
Integer	findObjectByInternalName (string name, [bool searchChildren]?)
Integer	getCount ()
Integer	getObject (index)
Boolean	isMember (object)
void	listObjects ()
void	pushToBack (object)
void	remove (obj1, [obj2]*)
void	reorderChild (SimObject child1, SimObject child2)
Public Member Functions inherited from SimObject
Integer	clone ([copyDynamicFields=false]?)
void	delete ()
Integer	getId ()
void	setName (newName)
String	getName ()
String	getClassNamespace ()
String	getSuperClassNamespace ()
void	setClassNamespace (nameSpace)
void	setSuperClassNamespace ()
Boolean	isMethod (string methodName)
String	call (methodName, [args]*)
void	dumpClassHierarchy ()
void	dump ()
Boolean	isMemberOfClass (string classname)
String	getClassName ()
String	getFieldValue (fieldName)
Boolean	setFieldValue (fieldName, value)
Integer	getDynamicFieldCount ()
String	getDynamicField (index)
Integer	getFieldCount ()
String	getField (int index)
void	setProgenitorFile (file)
String	getProgenitorFile ()
Integer	getType ()
String	getFieldType (fieldName)
void	setInternalName (string InternalName)
String	getInternalName ()
Boolean	isChildOfGroup (groupID)
Integer	getGroup ()
Boolean	startTimer (callbackFunction, float timePeriod, [repeat]?)
void	stopTimer ()
Boolean	isTimerActive ()
Integer	schedule (time, command, [arg]*)
Boolean	save (fileName, [selectedOnly]?)
void	addFieldFilter (fieldName)
void	removeFieldFilter (fieldName)

Detailed Description

A container for a sequence of unique SimObjects.

Overview

A SimSet is a specized container: an ordered set of references to SimObjects. As the name "set" implies, a SimObject can appear no more than once within a particular SimSet. Attempting to add an object multiple times will not change the SimSet not does it (nor should it) warn you. A SimSet keeps its items ordered, however, so it is more than a mathematical "set." You can reorder the objects.

A Simset only references SimObjects. The deletion of a SimSet will not delete the objects in it. Likewise, removing an object from a SimSet does not delete that object. Note that a SimObject can be a member of any number of SimSets.

When a SimObject is deleted, it will be automatically removed from any SimSets it is in. This is one of a SimSets most powerful features. There can be no invalid references to objects because you can not insert a non-existent reference, and references to SimObjects are automatically removed when those objects are deleted.

Due to its many capabilities, a SimSet is usually the appropriate structure for keeping Collections in Torque2D.*

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 almost 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 by clear() either.  For example...
echo(isObject(Persimmon));
> 1

caveat

Suppose you want to delete the items in a SimSet. Remember that, as you delete each one, it is automatically removed from the SimSet, which in turn changes the index of any items that came after the one you just deleted!

// DO NOT DO THIS!   this may lead to tears!
for (%i = 0; %i < %mySet.getCount(); %i++)
{
    %object = %mySet.getObject(%i);
    %object.delete();
}

The problem is that you delete the object at index 0. This, in turn, moves the objects down one index so that what was at index 1 is not at index 0. But your loop will not try index 0 again, where there is a fresh object. Instead it will skip to index 1. You will only delete half the items.

// fixed it
while (%mySet.getCount() > 0)
{
    %object = %mySet.getObject(0);
    %object.delete();
}

// or this will work too.  see why?
for (%i = %mySet.getCount() - 1; %i >= 0; %i--)
{
    %object = %mySet.getObject(%i);
    %object.delete();
}

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

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

Integer getCount

(

)

Returns

Returns the number of objects in the SimSet

Integer 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

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