Public Types | Public Member Functions | Static Public Member Functions

MSelectionList Class Reference

This reference page is linked to from the following overview topics: Querying the Scene Graph, MGlobal::setActiveSelectionList(), MSelectionList, MItSelectionList, MGlobal::selectByName(), 3.6 Render Loop Overrides, Using .NET assembly attributes, Appendix E: API and Devkit limitations.


Search for all occurrences

Detailed Description

A list of MObjects.

This class implements a list of MObjects.

The global selection list is a special case where the objects on the list are also active objects in Maya.

Besides the usual list methods, this class also provides an add method which retrieves objects from Maya, such as dependency nodes, by name.

Examples:

animExportUtil.cpp, animImportExport.cpp, animInfoCmd.cpp, apiMeshShape.cpp, apiMeshShape.h, apiMeshShapeUI.cpp, apiMeshShapeUI.h, apiSimpleShapeUI.cpp, apiSimpleShapeUI.h, blindComplexDataCmd.cpp, blindDoubleDataCmd.cpp, blindShortDataCmd.cpp, cgfxAttrDef.cpp, cgfxShaderCmd.cpp, cgfxShaderCmd.h, cleanPerFaceAssignmentCmd.cpp, closestPointCmd.cpp, closestPointOnCurveCmd.h, closestPointOnNurbsSurfaceCmd.cpp, clothPaintAttrCmd.cpp, clusterWeightFunction.cpp, componentScaleManip.cpp, convertEdgesToFacesCmd.cpp, convertVerticesToEdgesCmd.cpp, convertVerticesToFacesCmd.cpp, createClipCmd.cpp, customAttrManip.cpp, cvColorShader.cpp, cvExpandCmd.cpp, cvPosCmd.cpp, dagMessageCmd.cpp, dagPoseInfoCmd.cpp, deletedMsgCmd.cpp, exportJointClusterDataCmd.cpp, findFileTexturesCmd.cpp, findTexturesPerPolygonCmd.cpp, fluidInfoCmd.cpp, getAttrAffectsCmd.cpp, helix2Cmd.cpp, hlslShader.cpp, instancerListCmd.cpp, intersectCmd.cpp, intersectOnNurbsSurfaceCmd.cpp, lassoTool.cpp, latticeNoiseCmd.cpp, lepTranslator.cpp, lineManip.cpp, lineManipContainer.cpp, listLightLinksCmd.cpp, listPolyHolesCmd.cpp, lockEvent.cpp, marqueeTool.cpp, meshOpCmd.cpp, meshRemapCmd.cpp, meshRemapTool.h, meshReorderCmd.cpp, meshReorderTool.cpp, meshReorderTool.h, motionPathCmd.cpp, motionTraceCmd.cpp, moveCurveCVsCmd.cpp, moveManip.cpp, moveNumericTool.cpp, moveTool.cpp, narrowPolyViewer.cpp, narrowPolyViewer.h, nodeInfoCmd.cpp, nodeMessageCmd.cpp, NodeMonitor.cpp, objExport.cpp, particlePathsCmd.cpp, particleSystemInfoCmd.cpp, peltOverlapCmd.cpp, pfxInfoCmd.cpp, pointOnMeshCmd.cpp, polyExporter.cpp, polyMessageCmd.cpp, quadricShape.cpp, referenceQueryCmd.cpp, rotateManip.cpp, ShapeMonitor.cpp, ShapeMonitor.h, spiralAnimCurveCmd.cpp, splitUVCmd.cpp, squareScaleManip.cpp, surfaceBumpManip.cpp, surfaceTwistCmd.cpp, translateCmd.cpp, and whatisCmd.cpp.

#include <MSelectionList.h>

List of all members.

Public Types

enum  MergeStrategy { kMergeNormal = 0, kXORWithList, kRemoveFromList }
 

Specifies how to merge objects with those already in the list.

More...

Public Member Functions

 MSelectionList ()
 Class constructor.
 MSelectionList (const MSelectionList &src)
 Copy constructor.
virtual ~MSelectionList ()
 Class destructor.
MStatus clear ()
 This method empties the selection list.
bool isEmpty (MStatus *ReturnStatus=NULL) const
 Specifies whether or not the selection list contains any items.
unsigned int length (MStatus *ReturnStatus=NULL) const
 This method returns the number of selection items in the list.
MStatus getDependNode (unsigned int index, MObject &depNode) const
 Get a handle for the dependency node of the given element of the selection list.
MStatus getDagPath (unsigned int index, MDagPath &dagPath, MObject &component=MObject::kNullObj) const
 Get the dag path and component (may be NULL) of the given element of the selection list.
MStatus getPlug (unsigned int index, MPlug &plug) const
 Get the plug at the specified index of the selection list.
MStatus add (const MObject &object, const bool mergeWithExisting=false)
 Add the specified DG node to the end of the selection list.
MStatus add (const MDagPath &object, const MObject &component=MObject::kNullObj, const bool mergeWithExisting=false)
 Add the specified DG node to the end of the selection list.
MStatus add (const MString &matchString, const bool searchChildNamespacesToo=false)
 Add the specified object(s) to the selection list.
MStatus add (const MPlug &plug, const bool mergeWithExisting=false)
 Add the specified plug to the selection list.
MStatus remove (unsigned int index)
 Removes the item at the given index from the list.
MStatus replace (unsigned int index, const MObject &item)
 Remove the item at the given index in the list and replace it with the given object.
MStatus replace (unsigned int index, const MDagPath &item, const MObject &component=MObject::kNullObj)
 Remove the item at the given index in the list and replace it with the given Dag item (or components).
MStatus replace (unsigned int index, const MPlug &plug)
 Remove the item at the given index in the list and replace it with the given plug.
bool hasItem (const MObject &item, MStatus *ReturnStatus=NULL) const
 Determines whether or not the given dependency node is in this selection list.
bool hasItem (const MDagPath &item, const MObject &component=MObject::kNullObj, MStatus *ReturnStatus=NULL) const
 Determines whether or not the given DAG object is in this selection list.
bool hasItem (const MPlug &plug, MStatus *ReturnStatus=NULL) const
 Determines whether or not the given plug is in this selection list.
bool hasItemPartly (const MDagPath &item, const MObject &component, MStatus *ReturnStatus=NULL) const
 This method differs from hasItem in that it determines whether or not at least one of the components of the the given DAG object are in this selection list.
MStatus toggle (const MDagPath &item, const MObject &component=MObject::kNullObj)
 Removes those components of the given selection item which are on the selection list, and adds those parts which are not.
MSelectionListoperator= (const MSelectionList &other)
 Assignment operator.
MStatus merge (const MSelectionList &other, const MergeStrategy strategy=kMergeNormal)
 Merge the two selection lists.
MStatus merge (const MDagPath &object, const MObject &component=MObject::kNullObj, const MergeStrategy strategy=kMergeNormal)
 Merge the given DAG object into the selection list.
MStatus getSelectionStrings (MStringArray &array) const
 Gets the string representations of the items in the selection list.
MStatus getSelectionStrings (unsigned int index, MStringArray &array) const
 Gets the string representation of the given item in the selection list.

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Member Enumeration Documentation

Specifies how to merge objects with those already in the list.

Enumerator:
kMergeNormal 

If the object is not already on the list, add it.

kXORWithList 

Exclusive OR: if the object is already on the list, remove it, otherwise add it.

kRemoveFromList 

Remove the object from the list.


Constructor & Destructor Documentation

Class constructor.

Creates an empty selection list.

MSelectionList ( const MSelectionList srcList)

Copy constructor.

This constructor will copy the contents of the given selection list into the newly create selection list.

Parameters:
[in]srcListthe selection list to be copied.
~MSelectionList ( ) [virtual]

Class destructor.

Removes the selection list.


Member Function Documentation

MStatus clear ( )

This method empties the selection list.

Returns:
Status flag
Status Codes:
Examples:
cgfxShaderCmd.cpp, convertEdgesToFacesCmd.cpp, convertVerticesToEdgesCmd.cpp, convertVerticesToFacesCmd.cpp, lassoTool.cpp, latticeNoiseCmd.cpp, listLightLinksCmd.cpp, meshRemapCmd.cpp, and objExport.cpp.
bool isEmpty ( MStatus ReturnStatus = NULL) const

Specifies whether or not the selection list contains any items.

Parameters:
[in]ReturnStatusStatus flag
Returns:
true if the list is empty, false otherwise.
Status Codes:
Examples:
animImportExport.cpp.
unsigned int length ( MStatus ReturnStatus = NULL) const

This method returns the number of selection items in the list.

Parameters:
[out]ReturnStatusflag
Returns:
Number of items in the list
Status Codes:
Examples:
animInfoCmd.cpp, cgfxAttrDef.cpp, cgfxShaderCmd.cpp, createClipCmd.cpp, dagMessageCmd.cpp, deletedMsgCmd.cpp, exportJointClusterDataCmd.cpp, fluidInfoCmd.cpp, listPolyHolesCmd.cpp, moveNumericTool.cpp, nodeMessageCmd.cpp, objExport.cpp, particlePathsCmd.cpp, particleSystemInfoCmd.cpp, pfxInfoCmd.cpp, pointOnMeshCmd.cpp, and polyMessageCmd.cpp.
MStatus getDependNode ( unsigned int  index,
MObject depNode 
) const

Get a handle for the dependency node of the given element of the selection list.

Parameters:
[in]indexthe items position in the list
[out]depNodestorage for the result
Returns:
Return status
Status Codes:
Examples:
animInfoCmd.cpp, cgfxAttrDef.cpp, cgfxShaderCmd.cpp, closestPointOnNurbsSurfaceCmd.cpp, clothPaintAttrCmd.cpp, clusterWeightFunction.cpp, deletedMsgCmd.cpp, fluidInfoCmd.cpp, hlslShader.cpp, intersectOnNurbsSurfaceCmd.cpp, latticeNoiseCmd.cpp, nodeMessageCmd.cpp, NodeMonitor.cpp, objExport.cpp, particlePathsCmd.cpp, particleSystemInfoCmd.cpp, pfxInfoCmd.cpp, polyMessageCmd.cpp, and ShapeMonitor.cpp.
MStatus getDagPath ( unsigned int  index,
MDagPath dagPath,
MObject component = MObject::kNullObj 
) const

Get the dag path and component (may be NULL) of the given element of the selection list.

Parameters:
[in]indexthe items position in the list
[out]dagPathstorage for the dag path of the item
[out]componentstorage for a handle for the component. This will be null if there is no component
Returns:
Return status
Status Codes:
Examples:
apiMeshShape.cpp, closestPointOnNurbsSurfaceCmd.cpp, clusterWeightFunction.cpp, convertEdgesToFacesCmd.cpp, convertVerticesToEdgesCmd.cpp, convertVerticesToFacesCmd.cpp, cvColorShader.cpp, dagMessageCmd.cpp, exportJointClusterDataCmd.cpp, findTexturesPerPolygonCmd.cpp, intersectOnNurbsSurfaceCmd.cpp, listLightLinksCmd.cpp, listPolyHolesCmd.cpp, moveNumericTool.cpp, narrowPolyViewer.cpp, objExport.cpp, peltOverlapCmd.cpp, pointOnMeshCmd.cpp, and ShapeMonitor.cpp.
MStatus getPlug ( unsigned int  index,
MPlug plug 
) const

Get the plug at the specified index of the selection list.

Parameters:
[in]indexthe items position in the list
[out]plugstorage for the result
Returns:
Return status
Status Codes:
Examples:
animInfoCmd.cpp.
MStatus add ( const MObject object,
const bool  mergeWithExisting = false 
)

Add the specified DG node to the end of the selection list.

If mergeWithExisting is true, the given item is unconditionally added to the end of the list. Otherwise, If the item is already on the list, it is moved from its current position to the end of the list.

Parameters:
[in]objectThe object to add
[in]mergeWithExistingmerge new item with existing one, or add unconditionally to end of list.
Returns:
Status flag
Status Codes:
Examples:
animInfoCmd.cpp, apiMeshShape.cpp, apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, cgfxShaderCmd.cpp, closestPointCmd.cpp, clothPaintAttrCmd.cpp, convertEdgesToFacesCmd.cpp, convertVerticesToEdgesCmd.cpp, convertVerticesToFacesCmd.cpp, createClipCmd.cpp, cvExpandCmd.cpp, cvPosCmd.cpp, findFileTexturesCmd.cpp, fluidInfoCmd.cpp, getAttrAffectsCmd.cpp, hlslShader.cpp, intersectCmd.cpp, lassoTool.cpp, latticeNoiseCmd.cpp, listLightLinksCmd.cpp, meshRemapCmd.cpp, meshReorderCmd.cpp, narrowPolyViewer.cpp, NodeMonitor.cpp, objExport.cpp, particleSystemInfoCmd.cpp, peltOverlapCmd.cpp, pfxInfoCmd.cpp, pointOnMeshCmd.cpp, quadricShape.cpp, ShapeMonitor.cpp, and whatisCmd.cpp.
MStatus add ( const MDagPath object,
const MObject component = MObject::kNullObj,
const bool  mergeWithExisting = false 
)

Add the specified DG node to the end of the selection list.

If mergeWithExisting is true, the given item is unconditionally added to the end of the list. Otherwise, If the item is already on the list, it is moved from its current position to the end of the list. If the item was already on the list, and had components specified, the components from the given item are merged into those of the existing item.

Parameters:
[in]objectThe Dag Object to add
[in]componentcomponents of the object
[in]mergeWithExistingmerge new item with existing one, or add unconditionally to end of list.
Returns:
Status flag
Status Codes:
  • MS::kSuccess Object successfully added to the list
  • MS::kInvalidParameter item is null or contains an invalid DagPath, or the component parameter is not a handle to a valid component
  • MS::kFailure Error adding the object to the list
MStatus add ( const MString matchString,
const bool  searchChildNamespacesToo = false 
)

Add the specified object(s) to the selection list.

There is an option to search all child namespaces. The object name should be specified in the same way it would be in the MEL language. It is possible to use wildcard characters, so multiple objects may be added in one method call.

NOTE: the actual namespace being searched is important. In relativeNames mode (see the method MNamespace::relativeNames), the search starts in the current namespace but with relativeNames mode off, the search starts with the root namespace.

Parameters:
[in]matchStringobject match string
[in]searchChildNamespacesToooptional parameter to specify that child namespaces will also be searched. A value of true enables child namespace searching; a value of false (the default) only searches within the namespace. See the above description for details on which namespace gets searched.
Returns:
Return status
Status Codes:
MStatus add ( const MPlug plug,
const bool  mergeWithExisting = false 
)

Add the specified plug to the selection list.

Parameters:
[in]plugthe plug to add
[in]mergeWithExistingmerge new item with existing one, or add unconditionally to end of list.
Returns:
Return status
Status Codes:
MStatus remove ( unsigned int  index)

Removes the item at the given index from the list.

Parameters:
[in]indexThe index of the item to be removed
Returns:
Status flag
Status Codes:
MStatus replace ( unsigned int  index,
const MObject item 
)

Remove the item at the given index in the list and replace it with the given object.

The given index must not be greater than the current number of items on the list.

Parameters:
[in]itemA pointer to the replacement object
[in]indexThe index of the item to remove from the list
Returns:
Status flag
Status Codes:
MStatus replace ( unsigned int  index,
const MDagPath item,
const MObject component = MObject::kNullObj 
)

Remove the item at the given index in the list and replace it with the given Dag item (or components).

The given index must not be greater than the current number of items on the list.

Parameters:
[in]itemthe new dag object to place into the list
[in]componentthe components of item to add
[in]indexThe index of the item to remove from the list
Returns:
Status flag
Status Codes:
MStatus replace ( unsigned int  index,
const MPlug plug 
)

Remove the item at the given index in the list and replace it with the given plug.

The given index must not be greater than the current number of items on the list.

Parameters:
[in]plugThe replacement plug
[in]indexThe index of the item to remove from the list
Returns:
Status flag
Status Codes:
bool hasItem ( const MObject item,
MStatus ReturnStatus = NULL 
) const

Determines whether or not the given dependency node is in this selection list.

Note that if the selection list contains a DAG node, the overloaded version of this method that takes an MDagPath must be used. A dag path will not compare identically to a DG node, even if they both refer to the same node.

Parameters:
[in]itemThe item to check for
[out]ReturnStatusStatus flag
Returns:
true if the item is in this list, false otherwise
Status Codes:
bool hasItem ( const MDagPath item,
const MObject component = MObject::kNullObj,
MStatus ReturnStatus = NULL 
) const

Determines whether or not the given DAG object is in this selection list.

If the component argument is non-null, then this method will only return true of all the components of the given DAG object are on the selection list.

Parameters:
[in]itemthe DAG object to check for
[in]componentthe components of item to check for
[out]ReturnStatusStatus flag
Returns:
true if the item or component is in this list, false otherwise
Status Codes:
bool hasItem ( const MPlug plug,
MStatus ReturnStatus = NULL 
) const

Determines whether or not the given plug is in this selection list.

Parameters:
[in]plugThe plug to check for
[out]ReturnStatusStatus flag
Returns:
true if the plug is in this list, false otherwise
Status Codes:
bool hasItemPartly ( const MDagPath item,
const MObject component,
MStatus ReturnStatus = NULL 
) const

This method differs from hasItem in that it determines whether or not at least one of the components of the the given DAG object are in this selection list.

This method is only applicable when multiple components are provided.

Parameters:
[in]itemthe DAG object to check for
[in]componentthe components of item to check for
[out]ReturnStatusStatus flag
Returns:
true if at least one of the components in this list, false otherwise
Status Codes:
Examples:
ShapeMonitor.cpp.
MStatus toggle ( const MDagPath item,
const MObject component = MObject::kNullObj 
)

Removes those components of the given selection item which are on the selection list, and adds those parts which are not.

This method does nothing if no components are provided.

Parameters:
[in]itemDag object to be toggled
[in]componentcomponents of the object
Returns:
Status flag
Status Codes:
MSelectionList & operator= ( const MSelectionList other)

Assignment operator.

Parameters:
[in]otherthe selection list to be copied
Returns:
A reference to the copied selection list
MStatus merge ( const MSelectionList other,
const MergeStrategy  strategy = kMergeNormal 
)

Merge the two selection lists.

Parameters:
[in]otherthe selection list to be merged.
[in]strategythe merging strategy. It can be one of the the following:
Returns:
Status flag
Status Codes:
Examples:
listLightLinksCmd.cpp.
MStatus merge ( const MDagPath item,
const MObject component = MObject::kNullObj,
const MergeStrategy  strategy = kMergeNormal 
)

Merge the given DAG object into the selection list.

Parameters:
[in]itemthe dependency node to be merged.
[in]componentcomponents of the Dag object to add
[in]strategythe merging strategy. It can be one of the following:
Returns:
Status flag
Status Codes:
  • kSuccess Method successfull
  • MS::kInvalidParameter item is null or contains an invalid DagPath, or the component parameter is not a handle to a valid component
  • kFailure Operation failed
MStatus getSelectionStrings ( MStringArray array) const

Gets the string representations of the items in the selection list.

The strings will be in the format used by the scripting language.

Parameters:
[out]arraystorage for the returned strings
Returns:
Status flag
Status Codes:
Examples:
cgfxShaderCmd.cpp, convertEdgesToFacesCmd.cpp, convertVerticesToEdgesCmd.cpp, convertVerticesToFacesCmd.cpp, and cvExpandCmd.cpp.
MStatus getSelectionStrings ( unsigned int  index,
MStringArray array 
) const

Gets the string representation of the given item in the selection list.

The strings will be in the format used by the scripting language. More than one string will be returned in the case that the item in the selection list has a component that that contains elements that are not contiguous (eg CV's 2 and 8 are selected on a surface).

Parameters:
[in]indexindex of the element to get
[out]arraystorage for the returned strings
Returns:
Status flag
Status Codes:
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList
MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList MSelectionList