MSelectionList Class Reference
[OpenMaya - API module for common classes]

#include <MSelectionList.h>

List of all members.

---

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, cvExpandCmd.cpp, cvPosCmd.cpp, dagMessageCmd.cpp, dagPoseInfoCmd.cpp, deletedMsgCmd.cpp, exportJointClusterDataCmd.cpp, findFileTexturesCmd.cpp, findTexturesPerPolygonCmd.cpp, fluidInfoCmd.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.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.

Public Types
enum	MergeStrategy { kMergeNormal = 0, kXORWithList, kRemoveFromList }
	Specifies how to merge objects with those already in the list. More...
Public Member Functions
	MSelectionList ()
	MSelectionList (const MSelectionList &src)
virtual	~MSelectionList ()
MStatus	clear ()
bool	isEmpty (MStatus *ReturnStatus=NULL) const
unsigned int	length (MStatus *ReturnStatus=NULL) const
MStatus	getDependNode (unsigned int index, MObject &depNode) const
MStatus	getDagPath (unsigned int index, MDagPath &dagPath, MObject &component=MObject::kNullObj) const
MStatus	getPlug (unsigned int index, MPlug &plug) const
MStatus	add (const MObject &object, const bool mergeWithExisting=false)
MStatus	add (const MDagPath &object, const MObject &component=MObject::kNullObj, const bool mergeWithExisting=false)
MStatus	add (const MString &matchString)
MStatus	add (const MPlug &plug, const bool mergeWithExisting=false)
MStatus	remove (unsigned int index)
MStatus	replace (unsigned int index, const MObject &item)
MStatus	replace (unsigned int index, const MDagPath &item, const MObject &component=MObject::kNullObj)
MStatus	replace (unsigned int index, const MPlug &plug)
bool	hasItem (const MObject &item, MStatus *ReturnStatus=NULL) const
bool	hasItem (const MDagPath &item, const MObject &component=MObject::kNullObj, MStatus *ReturnStatus=NULL) const
bool	hasItem (const MPlug &plug, MStatus *ReturnStatus=NULL) const
bool	hasItemPartly (const MDagPath &item, const MObject &component, MStatus *ReturnStatus=NULL) const
MStatus	toggle (const MDagPath &item, const MObject &component=MObject::kNullObj)
MSelectionList &	operator= (const MSelectionList &other)
MStatus	merge (const MSelectionList &other, const MergeStrategy strategy=kMergeNormal)
MStatus	merge (const MDagPath &object, const MObject &component=MObject::kNullObj, const MergeStrategy strategy=kMergeNormal)
MStatus	getSelectionStrings (MStringArray &array) const
MStatus	getSelectionStrings (unsigned int index, MStringArray &array) const

---

Member Enumeration Documentation

enum MSelectionList::MergeStrategy

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

MSelectionList::MSelectionList

(

)

Class constructor. Creates an empty selection list.

MSelectionList::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::~MSelectionList

(

)

[virtual]

Class destructor. Removes the selection list.

---

Member Function Documentation

MStatus MSelectionList::clear

(

)

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 MSelectionList::isEmpty

(

MStatus *

ReturnStatus = NULL

)

const

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 MSelectionList::length

(

MStatus *

ReturnStatus = NULL

)

const

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 MSelectionList::getDependNode	(	unsigned int	index,
		MObject &	depNode
	)			const

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 MSelectionList::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]	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, 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 MSelectionList::getPlug	(	unsigned int	index,
		MPlug &	plug
	)			const

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 MSelectionList::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]	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 MSelectionList::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]	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 MSelectionList::add

(

const MString &

matchString

)

Add the specified object(s) to the selection list. The object 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.

Parameters:

[in]

matchString

object match string

Returns:

Return status

Status Codes:

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

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

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 MSelectionList::remove

(

unsigned int

index

)

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 MSelectionList::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]	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 MSelectionList::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]	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 MSelectionList::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]	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 MSelectionList::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]	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

bool MSelectionList::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]	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 MSelectionList::hasItem	(	const MPlug &	plug,
		MStatus *	ReturnStatus = NULL
	)			const

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 MSelectionList::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]	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 MSelectionList::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]	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 & 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 MSelectionList::merge	(	const MSelectionList &	other,
		const MergeStrategy	strategy = kMergeNormal
	)

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 MSelectionList::merge	(	const MDagPath &	item,
		const MObject &	component = MObject::kNullObj,
		const MergeStrategy	strategy = kMergeNormal
	)

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 MSelectionList::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]

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 MSelectionList::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]	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