MSelectionList Class Reference

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, footPrintNode.cpp, getAttrAffectsCmd.cpp, helix2Cmd.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, surfaceTwist.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.
MSelectionList &	operator= (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

enum MergeStrategy

Search for all occurrences

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

Enumerator:

kMergeNormal	If the object is not already on the list, add it. Search for all occurrences
kXORWithList	Exclusive OR: if the object is already on the list, remove it, otherwise add it. Search for all occurrences
kRemoveFromList	Remove the object from the list. Search for all occurrences

---

Constructor & Destructor Documentation

MSelectionList

(

)

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]

srcList

the selection list to be copied.

~MSelectionList

(

)

[virtual]

Class destructor.

Removes the selection list.

---

Member Function Documentation

MStatus clear

(

)

Search for all occurrences

This method empties the selection list.

Returns:

Status flag

Status Codes:

• MS::kSuccess The list was successfully reset.
• MS::kFailure Error resetting list.

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

Search for all occurrences

Specifies whether or not the selection list contains any items.

Parameters:

[in]

ReturnStatus

Status flag

Returns:

true if the list is empty, false otherwise.

Status Codes:

• MS::kSuccess Method successfully returned a result
• MS::kFailure Error in the selection list

Examples:

animImportExport.cpp.

unsigned int length

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

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

Parameters:

[out]

ReturnStatus

flag

Returns:

Number of items in the list

Status Codes:

• MS::kSuccess Method successfully returned a result
• MS::kFailure Error in the selection list

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

Search for all occurrences

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

Parameters:

[in]	index	the items position in the list
[out]	depNode	storage for the result

Returns:

Return status

Status Codes:

• MS::kSuccess Method successfully returned item
• MS::kFailure Error returning item

Examples:

animInfoCmd.cpp, cgfxAttrDef.cpp, cgfxShaderCmd.cpp, closestPointOnNurbsSurfaceCmd.cpp, clothPaintAttrCmd.cpp, clusterWeightFunction.cpp, deletedMsgCmd.cpp, fluidInfoCmd.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

Search for all occurrences

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

Parameters:

[in]	index	the items position in the list
[out]	dagPath	storage for the dag path of the item
[out]	component	storage for a handle for the component. This will be null if there is no component

Returns:

Return status

Status Codes:

• MS::kSuccess Method successfully returned item
• MS::kFailure Error returning item

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

Search for all occurrences

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

Parameters:

[in]	index	the items position in the list
[out]	plug	storage for the result

Returns:

Return status

Status Codes:

• MS::kSuccess Method successfully returned item
• MS::kFailure Error returning item

Examples:

animInfoCmd.cpp.

MStatus add	(	const MObject &	object,
		const bool	mergeWithExisting = false
	)

Search for all occurrences

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]	object	The object to add
[in]	mergeWithExisting	merge 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 is not a handle to a dependency node
• MS::kFailure Error adding the object to the list

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, 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
	)

Search for all occurrences

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]	object	The Dag Object to add
[in]	component	components of the object
[in]	mergeWithExisting	merge 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
	)

Search for all occurrences

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]	matchString	object match string
[in]	searchChildNamespacesToo	optional 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:

• MS::kSuccess Objects successfully added to the list
• MS::kInvalidParameter No matches were found for the string

MStatus add	(	const MPlug &	plug,
		const bool	mergeWithExisting = false
	)

Search for all occurrences

Add the specified plug to the selection list.

Parameters:

[in]	plug	the plug to add
[in]	mergeWithExisting	merge new item with existing one, or add unconditionally to end of list.

Returns:

Return status

Status Codes:

• MS::kSuccess Plug was successfully added to the list
• MS::kFailure Invalid plug

MStatus remove

(

unsigned int

index

)

Search for all occurrences

Removes the item at the given index from the list.

Parameters:

[in]

index

The index of the item to be removed

Returns:

Status flag

Status Codes:

• MS::kSuccess Item was successfully removed
• MS::kFailure Error removing item

MStatus replace	(	unsigned int	index,
		const MObject &	item
	)

Search for all occurrences

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]	item	A pointer to the replacement object
[in]	index	The index of the item to remove from the list

Returns:

Status flag

Status Codes:

• MS::kSuccess The replacement was successfull
• MS::kInvalidParameter item is null or is not a handle to a dependency node, or the index is larger than the list size
• MS::kFailure The replacement falied

MStatus replace	(	unsigned int	index,
		const MDagPath &	item,
		const MObject &	component = MObject::kNullObj
	)

Search for all occurrences

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]	item	the new dag object to place into the list
[in]	component	the components of item to add
[in]	index	The index of the item to remove from the list

Returns:

Status flag

Status Codes:

• MS::kSuccess The replacement was successfull
• MS::kInvalidParameter item is null or is not a handle to a dependency node, or the index is larger than the list size
• MS::kFailure The replacement falied

MStatus replace	(	unsigned int	index,
		const MPlug &	plug
	)

Search for all occurrences

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]	plug	The replacement plug
[in]	index	The index of the item to remove from the list

Returns:

Status flag

Status Codes:

• MS::kSuccess The replacement was successfull
• MS::kInvalidParameter item is null or is not a handle to a dependency node, or the index is larger than the list size
• MS::kFailure The replacement falied

bool hasItem	(	const MObject &	item,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

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]	item	The item to check for
[out]	ReturnStatus	Status flag

Returns:

true if the item is in this list, false otherwise

Status Codes:

• MS::kSuccess Method successfully returned a result
• MS::kInvalidParameter item is null or is not a handle to a dependency node
• MS::kFailure unable to attempt test

Examples:

footPrintNode.cpp.

bool hasItem	(	const MDagPath &	item,
		const MObject &	component = MObject::kNullObj,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

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]	item	the DAG object to check for
[in]	component	the components of item to check for
[out]	ReturnStatus	Status flag

Returns:

true if the item or component is in this list, false otherwise

Status Codes:

• MS::kSuccess Method successfully returned a result
• MS::kInvalidParameter item is null or contains an invalid DagPath, or the component parameter is not a handle to a valid component
• MS::kFailure unable to attempt test

bool hasItem	(	const MPlug &	plug,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

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

Parameters:

[in]	plug	The plug to check for
[out]	ReturnStatus	Status flag

Returns:

true if the plug is in this list, false otherwise

Status Codes:

• MS::kSuccess Method successfully returned a result
• MS::kInvalidParameter item is null or is not a handle to a dependency node
• MS::kFailure unable to attempt test

bool hasItemPartly	(	const MDagPath &	item,
		const MObject &	component,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

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]	item	the DAG object to check for
[in]	component	the components of item to check for
[out]	ReturnStatus	Status flag

Returns:

true if at least one of the components in this list, false otherwise

Status Codes:

• MS::kSuccess method successfully returned a result
• MS::kInvalidParameter item is null or contains an invalid DagPath, or the component parameter is not a handle to a valid component
• MS::kFailure unable to attempt test

Examples:

ShapeMonitor.cpp.

MStatus toggle	(	const MDagPath &	item,
		const MObject &	component = MObject::kNullObj
	)

Search for all occurrences

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]	item	Dag object to be toggled
[in]	component	components of the object

Returns:

Status flag

Status Codes:

• MS::kSuccess Method successfull
• MS::kInvalidParameter item is null or is not a handle to a dependency node
• MS::kFailure Error doing toggle

MSelectionList & operator=

(

const MSelectionList &

other

)

Assignment operator.

Parameters:

[in]

other

the selection list to be copied

Returns:

A reference to the copied selection list

MStatus merge	(	const MSelectionList &	other,
		const MergeStrategy	strategy = kMergeNormal
	)

Search for all occurrences

Merge the two selection lists.

Parameters:

[in]	other	the selection list to be merged.
[in]	strategy	the merging strategy. It can be one of the the following:

• MSelectionList::kMergeNormal Add the target item if it is not already in the list.
• MSelectionList::kXORWithList XOR the item with the list.
• MSelectionList::kRemoveFromList Remove the item in the list if it exists in the list.

Returns:

Status flag

Status Codes:

• kSuccess Method successfull
• MS::kInvalidParameter other is an empty list
• kFailure Operation failed

Examples:

listLightLinksCmd.cpp.

MStatus merge	(	const MDagPath &	item,
		const MObject &	component = MObject::kNullObj,
		const MergeStrategy	strategy = kMergeNormal
	)

Search for all occurrences

Merge the given DAG object into the selection list.

Parameters:

[in]	item	the dependency node to be merged.
[in]	component	components of the Dag object to add
[in]	strategy	the merging strategy. It can be one of the following:

• MSelectionList::kMergeNormal Add the target item if it is not already in the list.
• MSelectionList::kXORWithList XOR the item with the list.
• MSelectionList::kRemoveFromList Remove the item in the list if it exists in the list.

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

Search for all occurrences

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]

array

storage for the returned strings

Returns:

Status flag

Status Codes:

• MS::kSuccess Method successfull

Examples:

cgfxShaderCmd.cpp, convertEdgesToFacesCmd.cpp, convertVerticesToEdgesCmd.cpp, convertVerticesToFacesCmd.cpp, and cvExpandCmd.cpp.

MStatus getSelectionStrings	(	unsigned int	index,
		MStringArray &	array
	)		const

Search for all occurrences

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]	index	index of the element to get
[out]	array	storage for the returned strings

Returns:

Status flag

Status Codes:

• MS::kSuccess Method successfull
• MS::kInvalidParameter Index is out of range
• MS::kFailure Error getting the item

const char * className

(

)

[static]

Search for all occurrences

Returns the name of this class.

Returns:

The name of this class.