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, cvColorShader.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.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, const bool searchChildNamespacesToo=false)
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

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:
Examples:

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:
Examples:

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:
Examples:

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:
Examples:

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:
Examples:

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:
Examples:

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:
Examples:

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

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:

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:

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:

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:

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:

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:

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:

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:

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:
Examples:

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:

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:
Returns:
Status flag
Status Codes:
Examples:

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:
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:
Examples:

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:

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6