selectionConnection

Go to: Synopsis. Return value. Flags. MEL examples.

Synopsis

selectionConnection [-activeCacheList] [-activeCharacterList] [-activeList] [-addScript script] [-addTo string] [-characterList] [-clear] [-connectionList] [-defineTemplate string] [-deselect name] [-editor string] [-exists] [-filter string] [-findObject name] [-global boolean] [-highlightList] [-identify] [-keyframeList] [-lock boolean] [-modelList] [-object name] [-parent string] [-remove string] [-removeScript script] [-select name] [-setList] [-switch] [-useTemplate string] [-worldList] string

selectionConnection is undoable, queryable, and editable.

Selection connections are UI objects which contain a list of model objects. Selection connections are useful for specifying which objects are to be displayed within a particular editor. Editor's have three plug sockets where a selection connection may be attached. They are:

mainListConnection

an input socket which contains a list of objects that are to be displayed within the editor

selectionConnection

an output socket which contains a list of objects that are selected within the editor

highlightConnection

an input socket which contains a list of objects that are to be highlighted within the editor

There are several different types of selection connections that may be created. They include:

activeList

a selection connection which contains a list of everything in the model which is active (which includes geometry objects and keys)

modelList

a selection connection which contains a list of all the geometry (i.e. excluding keys) objects that are currently active

keyframeList

a selection connection which contains a list of all the keys that are currently active

worldList

a selection connection which contains a list of all the objects in the world

objectList

a selection connection which contains one model object (which may be a set)

listList

a selection connection which contains a list of selection connections

editorList

a selection connection which contains a list of objects that are attached to the mainListConnection of the specified editor

setList

a selection connection which contains a list of all the sets in the world

characterList

a selection connection which contains a list of all the characters in the world

highlightList

a selection connection which contains a list of objects to be highlighted in some fashion

Below is an example selectionConnection network between two editors. Editor 1 is setup to display objects on the activeList. Editor 2 is setup to display objects which are selected within Editor 1, and objects that are selected in Editor 2 are highlighted within Editor 1:

-- Editor 1--       -- Editor 2--
inputList-->| main |      |  |->| main |      |
|      | sele |--|  |      | sele |--|
|->| high |      |     | high |      |  |
|   -------------       -------------   |
|------------- fromEditor2 -------------|

The following commands will establish this network:

selectionConnection -activeList inputList;
selectionConnection fromEditor1;
selectionConnection fromEditor2;
editor -edit -mainListConnection inputList Editor1;
editor -edit -selectionConnection fromEditor1 Editor1;
editor -edit -mainListConnection fromEditor1 Editor2;
editor -edit -selectionConnection fromEditor2 Editor2;
editor -edit -highlightConnection fromEditor2 Editor1;

Note: to delete a selection connection use the deleteUI command
Note: commands which expect objects may be given a selection connection instead, and the command will operate upon the objects wrapped by the selection connection
Note: the graph editor and the dope sheet are the only editors which can use the editor connection to the highlightConnection of another editor
WARNING: some flag combinations may not behave as you expect. The command is really intended for internal use for managing the outliner used by the various editors.

Return value

In query mode, return type is based on queried flag.

Flags

Long name (short name)	Argument types	Properties
-exists(-ex)
Returns true|false depending upon whether the specified object exists. Other flags are ignored.
-defineTemplate(-dt)	string
Puts a command in a mode where any other flags and args are parsed and added to the command template specified in the argument. They will be used as default arguments in any subsequent invocations of the command when templateName is set as the current template.
-useTemplate(-ut)	string
Force the command to use a command template other than the current one.
-parent(-p)	string
The name of a UI object this should be attached to. When the parent is destroyed, the selectionConnection will auto-delete. If no parent is specified, the connection is created in the current controlLayout.
-filter(-f)	string
Optionally specifies an itemFilter for this connection. An empty string ("") clears the current filter. If a filter is specified, all the information going into the selectionConnection must first pass through the filter before being accepted. NOTE: filters can only be attached to regular selectionConnections. They cannot be attached to any connection created using the -act, -mdl, -key, -wl, -sl, -cl, -lst, -obj, or -ren flags. We strongly recommend that you do not attach filters to a selectionConnection --- it is better to attach your filter to the editor that is using the selectionConnection instead.
-global(-g)	boolean
A global selection connection cannot be deleted by any script commands.
-activeList(-act)
Specifies that this connection should reflect the active list (geometry objects and keys).
-modelList(-mdl)
Specifies that this connection should reflect the modeling (i.e. excluding keys) portion of the active list.
-keyframeList(-key)
Specifies that this connection should reflect the animation portion of the active list.
-worldList(-wl)
Specifies that this connection should reflect all objects in the world.
-object(-obj)	name
Specifies that this connection should wrap around the specified object (which may be a set). Query will return all the members of the selection connection (if the connection wraps a set, the set members will be returned)
-setList(-sl)
Specifies that this connection should reflect all the sets in the world.
-characterList(-cl)
Specifies that this connection should reflect all the characters in the world.
-activeCharacterList(-acl)
Specifies that this connection should reflect the characters that objects on the active list belong to.
-activeCacheList(-atc)
Specifies that this connection should reflect the cache that objects on the active list belong to.
-highlightList(-hl)
Specifies that this connection is being used as a highlight list.
-connectionList(-lst)
Specifies that this connection should contain a list of selection connections.
-switch(-sw)
Acts as a modifier to -connectionList which sets the list of objects to be the first non-empty selection connection. selection connections are tested in the order in which they are added.
-editor(-ed)	string
Specifies that this connection should reflect the -mainListConnection of the specified editor.
-addTo(-add)	string
The name of a selection connection that should be added to this list of connections.
-remove(-rm)	string
The name of a selection connection that should be removed from this list of connections.
-findObject(-fo)	name
Find a selection connection in this list that wraps the specified object.
-identify(-id)
Find out what type of selection connection this is. May be: activeList | modelList | keyframeList | worldList | objectList listList | editorList | connection | unknown
-lock(-lck)	boolean
For activeList connections, locking the connection means that it will not listen to activeList changes.
-clear(-clr)
Remove everything from the selection connection.
-addScript(-as)	script
Specify a script to be called when something is added to the selection.
-removeScript(-rs)	script
Specify a script to be called when something is removed from the selection.
-select(-s)	name
Add something to the selection. This does not replace the existing selection.
-deselect(-d)	name
Remove something from the selection.

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can be used more than once in a command.

MEL examples

//    Example 1.
//
//    Create a window with two Outliner editors and a
//    selection connection network.  Editor 1 will display the
//    current scene's active list.  Editor 2 will display the items
//    selected in Editor 1.
//
string $window = `window -wh 400 300`;
paneLayout -configuration "vertical2";
string $editor1 = `outlinerEditor`;
string $editor2 = `outlinerEditor`;

//    Create the selection connection network.
//
string $inputList = `selectionConnection -activeList`;
string $fromEditor1 = `selectionConnection`;
string $fromEditor2 = `selectionConnection`;
editor -edit -mainListConnection $inputList $editor1;
editor -edit -selectionConnection $fromEditor1 $editor1;
editor -edit -mainListConnection $fromEditor1 $editor2;
editor -edit -selectionConnection $fromEditor2 $editor2;

showWindow $window;

//    Create some objects and select them.
//
sphere; cone; cylinder;
select -all;

// Now as you select objects on the left side, they will be
// displayed on the right side.  You can also add a callback
// script to do further processing on the list when objects
// are added. (Use -removeScript for when objects are removed.)

global proc addScriptCallback(string $array[])
{
    print "Contents of callback array:\n";
    print $array;
}

selectionConnection -e -addScript addScriptCallback $fromEditor1;


//    Example 2.
//
//    Create a selection connection for a paritcular object.  Delete
//    the selection connection and the object.
//
sphere -name sphere;

//    Create a selection connection to wrap the sphere.
//
selectionConnection -object sphere holder;

//    Select the sphere using the selection connection.
//
select holder;

//    Delete the members (sphere) of the selection connection
//
delete holder;

//    Delete the selection connection (does not delete the members of
//    the selection connection.
//
deleteUI holder;