TorqueScript Reference

- Main Page
- Related Pages
- Modules
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | List of all members
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.