A Group is the client-side representation of a group node on the server, which is a collection of other nodes organized as a linked list. The Nodes within a Group may be controlled together, and may be both Synths and other Groups. Groups are thus useful for controlling a number of nodes at once, and when used as targets can be very helpful in controlling order of execution. (See Order of execution for more details on this topic).
For more on the crucial distinction between client objects and server nodes, see Client vs Server. For information on creating nodes without using objects, see Node Messaging.
N.B. Group is a subclass of Node, and thus many of its most useful and important methods are documented in the Node help file. Please refer to it for more information.
When a Server is booted, there is a top level group with an ID of 0 that defines the root of the tree. This is represented by a subclass of Group: RootNode.
sclang has the notion of a "default group," which is automatically created when the server is booted. This group is the default enclosing group for all Nodes, i.e. it's what you get if you don't specify. In general you should create new Nodes within the default group of a Server rather than in its RootNode. Multiclient setups may have different default groups for each client. See Default Group, Server, and RootNode for more detail.
Some of the methods below have two versions: a regular one which sends its corresponding message to the server immediately, and one which returns the message in an Array so that it can be added to a bundle. It is also possible to capture the messages generated by the regular methods using Server's automated bundling capabilities. See Server and Bundled Server Messages for more detail.
Create and return a Group.
| target |
A target for this Group. If target is not a Group or Synth, it will be converted as follows: If it is a Server, it will be converted to the default_group of that server. If it is nil, to the default_group of the default Server. | ||||||||||
| addAction |
one of the following Symbols:
Note: A Synth is not a valid target for \addToHead and \addToTail. |
The following convenience methods correspond to the add actions above:
Create and return a Group and add it immediately after aNode.
Create and return a Group and add it immediately before aNode.
Create and return a Group. If aGroup is a Group add it at the head of that group. If it is a Server, add it at the head of the default_group of that server. If it is nil, add it at the head of the default_group of the default Server.
Create and return a Group. If aGroup is a Group add it at the tail of that group. If it is a Server, add it at the tail of the default_group of that server. If it is nil, add it at the tail of the default_group of the default Server.
Create and return a Group and use it to replace nodeToReplace, taking its place in its server's node order.
For use in message bundles it is also possible to create a Group object in the client app without immediately creating a group node on the server. Once done one can call methods which create messages to add to a bundle, which when sent to the server will instantiate the group or perform other operations. (See Control, below.)
Create and return a Group object without creating a group node on the server. (This method is inherited from Node and is documented here only for convenience.)
| server |
An optional instance of Server. If nil this will default to the default Server. |
| nodeID |
An optional node ID number. If not supplied one will be generated by the Server's NodeIDAllocator. Normally you should not need to supply an ID. |
After creation, use instance methods newMsg, addToHeadMsg, addToTailMsg, addBeforeMsg, addAfterMsg, addReplaceMsg to instantiate this synth on the server. See Instance Methods below.
Use class method basicNew to create a Synth without instantiating it on the server. Then use the following instance methods:
Returns a message of the type g_new which can be bundled. When sent to the server this message will instantiate this group. If target is nil, it will default to the default_group of the Server specified in *basicNew when this Group was created. The default addAction is \addToHead. (See *new above for details of addActions.
Returns a message of the type g_new which can be bundled. When sent to the server this message will instantiate this group. If aGroup is a Group it will be added at the head of that group. If it is nil, it will be added at the head of the default_group of this Group's server (as specified when *basicNew was called).
Returns a message of the type g_new which can be bundled. When sent to the server this message will instantiate this group. If aGroup is a Group it will be added at the tail of that group. If it is nil, it will be added at the tail of the default_group of this Group's server (as specified when *basicNew was called).
Returns a message of the type g_new which can be bundled. When sent to the server this message will instantiate this group, immediately before aNode.
Returns a message of the type g_new which can be bundled. When sent to the server this message will instantiate this group, immediately after aNode.
Returns a message of the type g_new which can be bundled. When sent to the server this message will instantiate this group, replacing nodeToReplace in the server's node order.
For further methods of controlling Groups (set, map, etc.), see the Node help file.
Move aNode to the head of this group
Move aNode to the tail of this group
Free all the nodes in this group, but do not free this group itself.
Free all Synths in the group, and all Synths in any enclosed groups, but do not free this group or any of its enclosed groups.
Post a representation of this group's node subtree. (Sends a message of the type g_dumpTree.) If postControls is true, then the current Control (arg) values for any synths contained in this group will be posted as well. The default is false.
Queries the server for a message describing this group's node subtree. (Sends a message of the type g_queryTree.) This reply is passed to the action function as an argument. See g_queryTree in Server Command Reference or the example below for information on how the reply is structured.