class MSelectionList

Jump to documentation

public members:

enum	MergeStrategy kMergeNormal kXORWithList kRemoveFromList
	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

Documentation

Description

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.

Functions

MSelectionList:: MSelectionList ()

Description

Class constructor.
Creates an empty selection list.

MSelectionList:: MSelectionList ( const MSelectionList & srcList )

Description

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

Arguments

• srcList the selection list to be copied.

MSelectionList:: ~MSelectionList ()

Description

Class destructor.
Removes the selection list.

MStatus MSelectionList:: clear ()

Description

This method empties the selection list.

Return Value

• Status flag

Status Codes

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

bool MSelectionList:: isEmpty ( MStatus * ReturnStatus ) const

Description

Specifies whether or not the selection list contains any items.

Arguments

• Status flag

Return Value

• result true if the list is empty, false otherwise.

Status Codes

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

unsigned int MSelectionList:: length ( MStatus * ReturnStatus ) const

Description

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

Arguments

• Status flag

Return Value

• number of items in the list

Status Codes

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

MStatus MSelectionList:: getDependNode ( unsigned int index, MObject &depNode ) const

Description

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

Arguments

• index the items position in the list
• depNode storage for the result

Return Value

• return status

Status Codes

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

MStatus MSelectionList:: getDagPath ( unsigned int index, MDagPath &dagPath, MObject &component ) const

Description

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

Arguments

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

Return Value

• return status

Status Codes

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

MStatus MSelectionList:: getPlug ( unsigned int index, MPlug &plug ) const

Description

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

Arguments

• index the items position in the list
• depNode storage for the result

Return Value

• return status

Status Codes

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

MStatus MSelectionList:: add ( const MObject & object, const bool mergeWithExisting )

Description

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.

Arguments

• object The object to add
• mergeWithExisting merge new item with existing one, or add unconditionally to end of list.

Return Value

• 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

MStatus MSelectionList:: add ( const MDagPath & object, const MObject & component, const bool mergeWithExisting)

Description

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.

Arguments

• object The Dag Object to add
• component components of the object
• mergeWithExisting merge new item with existing one, or add unconditionally to end of list.

Return Value

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

Description

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.

Arguments

• matchString object match string

Return Value

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

Description

Add the specified plug to the selection list.

Arguments

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

Return Value

• return status

Status Codes

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

MStatus MSelectionList:: remove ( unsigned int index )

Description

Removes the item at the given index from the list.

Arguments

• index The index of the item to be removed

Return Value

• Status flag

Status Codes

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

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

Description

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.

Arguments

• item A pointer to the replacement object
• index The index of the item to remove from the list

Return Value

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

Description

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.

Arguments

• item the new dag object to place into the list
• component the components of item to add
• index The index of the item to remove from the list

Return Value

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

Description

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.

Arguments

• plug The replacement plug
• index The index of the item to remove from the list

Return Value

• 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 ) const

Description

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.

Arguments

• item The item to check for
• ReturnStatus Status flag

Return Value

• 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, MStatus * ReturnStatus ) const

Description

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.

Arguments

• item the DAG object to check for
• component the components of item to check for
• ReturnStatus Status flag

Return Value

• 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 ) const

Description

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

Arguments

• plug The plug to check for
• ReturnStatus Status flag

Return Value

• 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 ) const

Description

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.

Arguments

• item the DAG object to check for
• component the components of item to check for
• ReturnStatus Status flag

Return Value

• result 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

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

Description

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.

Arguments

• item Dag object to be toggled
• component components of the object
• ReturnStatus Status flag

Return Value

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

Description

Assignment operator.

Arguments

• other the selection list to be copied

Return Value

• A reference to the copied selection list

MStatus MSelectionList:: merge ( const MDagPath & item, const MObject & component, const MergeStrategy strategy )

Description

Merge the given DAG object into the selection list.

Arguments

• item the dependency node to be merged.
• component components of the Dag object to add
• 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.

Return Value

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

Description

Merge the two selection lists.

Arguments

• other the selection list to be merged.
• 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.

Return Value

• Status flag

Status Codes

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

MStatus MSelectionList:: getSelectionStrings ( MStringArray & array ) const

Description

Gets the string representations of the items in the selection list. The strings will be in the format used by the scripting language.

Arguments

• array storage for the returned strings

Return Value

• Status flag

Status Codes

• MS::kSuccess Method successfull

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

Description

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

Arguments

• index index of the element to get
• array storage for the returned strings

Return Value

• Status flag

Status Codes

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

This class has no child classes.