- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Static Public Member Functions

# MNamespace Class Reference

# OpenMaya - API module for common classes

Search for all occurrences

## Detailed Description

Namespace.

Overview

The MNamespace class contains methods for efficiently accessing Maya's namespace functionality. In Maya, namespaces form a packaging scheme for defining collections of objects. You can also have a namespace contain other namespaces and thus define a hierarchy. In Maya, namespaces are used by default with file referencing to collect all the objects from the given referenced file. Namespaces are also used for naming UI elements, and of course the user can create namespaces on their own to collect objects together in a logical fashion.

Here are some important definitions:

o Root Namespace: The unnamed namespace at the root of the namespace hierarchy.

o Current Namespace: The currently selected namespace. On startup and after file open and new, Maya assigns the root namespace to be current.

o Absolute Name: An object name that is fully specified from the root downwards (i.e. starts with a leading colon).

o Relative Name: An object name that is relative to the current namespace. Can be enabled via MNamespace::setRelativeNames().

o Root-Relative Name: When relative name lookup is turned off, virtually all name lookups in Maya are relative to the root of the namespace hierarchy.

About naming rules

When specifying the name of an object in a namespace, the namespace name should prefix the name, separated by a colon character (":"). There is a special namespace, the root namespace, which lives at the root of the namespace tree. In effect, the name of the root namespace is the empty string. For example, if we have the object "sphere" and it exists in the root namespace, we could use ":sphere" to identify it.

Since namespaces can be hierarchical, when completely specifying a name one could have several colons and namespaces names in the pathname. If we have the namespace ":a:b:c" that contains the object "sphere", the full namepath for the object would be thus:

:a:b:c:sphere

The leading colon specifies that the namespace lookup occur from the root-level downwards. In effect, the namespace "a" is a child of the root namespace, and "b" is a child of "a", and "c" a child of "b".

The current namespace

Maya has the concept of a "current" namespace. On startup, this defaults to the root namespace. Some operations within Maya are based off the current namespace. For example, if the 'parent' parameter is not specified to MNamespace::addNamespace() then the newly created namespace will be a child of the current namespace.

Relative name lookup

Maya actually has the concept of name lookup based off the current namespace as opposed to lookup based off the root-level namespace which is the default behaviour. In relative mode, if we had the object ":a:b:c:sphere" and the current namespace were ":a:b", we would refer to the sphere as "c:sphere". Similarly, by setting the current namespace to be ":a:b:c" we could then refer directly to sphere in an operation such as a "setAttr", e.g.

setAttr sphere.translateX 10;

If relative mode is off, names are root-relative, thus we would need to refer to the sphere as follows. Note that when relative mode is off, Maya assumes the root namespace to base name lookups on:

setAttr a:b:c:sphere.translateX 10;

Also, we can always specify an absolute namepath (one that starts with a leading colon). An absolute namepath will work with relative name lookup enabled or disabled and is thus an easy way of referring to objects in a way that is name lookup-independent.

The relative mode feature is designed to allow users to write namespace-independent code which is intended to operate upon whatever namespace is current. The method MNamespace::currentNamespace() allows you to query the name of the current namespace.

Relative mode can ge toggled using either MNamespace::setRelativeNames() or the "namespace" command. Turning relative mode "off" causes name lookup to be based off the root namespace. Continuing our example where the current namespace is ":a:b" to refer to the sphere we would now need to use:

setAttr a:b:c:sphere.translateX 10;

Using namespaces with the MNamespace class

Maya provides the "namespace" and "namespaceInfo" commands for dealing with namespaces from the command level, and there are also UI features which control and edit namespaces. All of these work harmoniously with the MNamespace class.

It is important that any user code which exercises MNamespace methods that modify (rather than query) handle undo. For example, if writing a plug-in command that creates a new namespace, the plug-in needs to handle removal of the namespace on undo.

The MNamespace class contains methods to create and remove namespaces, set and query the current namespace, and edit and query the contents of namespaces.

To add individual objects to a namespace, use MSelectionList::add() which is well suited for handling multiple objects having the same name as well as hierarchical namespaces.

`#include <MNamespace.h>`

List of all members.

## Static Public Member Functions
static MStatus | addNamespace (const MString &name, const MString *parent=NULL)
| Create the namespace `name'.
static MString | currentNamespace (MStatus *ReturnStatus=NULL)
| Get the name of the current namespace.
static MStatus | setCurrentNamespace (const MString &name)
| Set the specified namespace to be the current namespace.
static MStringArray | getNamespaces (const bool recurse=false, MStatus *ReturnStatus=NULL)
| Return a list of all namespaces in the current namespace.
static MStringArray | getNamespaces (const MString &parentNamespace, const bool recurse=false, MStatus *ReturnStatus=NULL)
| Return a list of all child namespaces of `parentNamespace', with the option to list only direct children versus all descendents.
static bool | namespaceExists (const MString &name, MStatus *ReturnStatus=NULL)
| Check if a given namespace exists.
static MString | parentNamespace (MStatus *ReturnStatus=NULL)
| Get the name of the current namespace's parent.
static MStatus | removeNamespace (const MString &name, bool removeContents=false)
| Remove the specified namespace.
static MStatus | renameNamespace (const MString &oldName, const MString &newName, const MString *parent=NULL)
| Rename the specified namespace to a new name with optional parent name.
static MObjectArray | getNamespaceObjects (const MString &parentNamespace, const bool recurse=false, MStatus *ReturnStatus=NULL)
| Return an array of MObjects representing the object contained within the specified namespace.
static MStatus | moveNamespace (const MString &src, const MString &dst, const bool force=false)
| Move the contents of the namespace `src' into the namespace `dst'.
static MString | rootNamespace (MStatus *ReturnStatus=NULL)
| Get the name of the root namespace.
static bool | relativeNames (MStatus *ReturnStatus=NULL)
| Query Maya's current "relative name lookup" state.
static MStatus | setRelativeNames (bool newState)
| Set relative name lookup mode.
static MString | getNamespaceFromName (const MString &fullName, MStatus *ReturnStatus=NULL)
| Get namespace from a full name.
static MString | stripNamespaceFromName (const MString &fullName, MStatus *ReturnStatus=NULL)
| Strips the namespace from a full name.
static MString | makeNamepathAbsolute (const MString &, MStatus *ReturnStatus=NULL)
| Make a namepath which is relative to the root into an absolute namepath.
static const char * | className ()
| Returns the name of this class.

## Member Function Documentation

MStatus addNamespace | ( | const MString & | name,
|  | const MString * | parent = `NULL`
| ) |  | `[static]`

Search for all occurrences

Create the namespace `name'.

If the `parent' namespace is given the new namespace will be a child of `parent', otherwise the new namespace will be a child of the current namespace. The new namespace is added, but not made current. To make the new namespace be current use MNamespace::setCurrentNamespace(). Note that adding a namespace changes the scene, so any code that calls this method needs to handle undo.

Parameters:

  [in] | name | The new namespace to create. A qualified or unqualified name may be used. If a qualified name is used and one or more of the higher level namespaces do not already exist, they will be created automatically. For example, if the new name is "a:b:c" and "a" does not yet exist, then it will be created automatically and "b" automatically created beneath it and finally "c" will be created beneath "b".
  [in] | parent | The fully qualified name of the namespace under which the new one is to be created. If not provided then the current namespace will be used. If the name of the new namespace is absolute (i.e. begins with a colon, ":a:b:c") then the 'parent' parameter will be ignored and the new namespace will be created under the root namespace.

Returns:
  The return status code.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kInvalidParameter the given namespace already exists, the namespace name was invalid, or a non-existent parent namespace was specified.

MString currentNamespace | ( | MStatus * | ReturnStatus = `NULL` | ) | `[static]`

Search for all occurrences

Get the name of the current namespace.

This name is returned as an absolute namepath (i.e. fully qualfied from the root namespace downwards, ":a:b:c").

Parameters:

  [out] | ReturnStatus | optionally returns the status code.

Status Codes:
  - MS::kSuccess successfully returned the name of the current namespace.
  - MS::kFailure internal error.

Returns:
  The name of the current namespace as an absolute namepath.

MStatus setCurrentNamespace | ( | const MString & | name | ) | `[static]`

Search for all occurrences

Set the specified namespace to be the current namespace.

The `name' parameter you specify is relative to whatever namespace is current, but any namespace can be specified by passing an absolute name (e.g. :a:b:c). Note that making a namespace current changes the scene, so any code that calls this method needs to handle undo.

To make the root namespace become current, use:

status=MNamespace::setCurrentNamespace(MNamespace::rootNamespace());

Parameters:

  [in] | name | the name of the namespace to make current.

Returns:
  The return status code.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kInvalidParameter `name' does not exist.

MStringArray getNamespaces | ( | const bool | recurse = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Return a list of all namespaces in the current namespace.

Notes: 1) Names returned are always absolute (e.g. :a:b:sphere). 2) The list returned is just the child namespaces (and descendents if `recurse' is true). It thus never contains the root namespace in the list returned.

Parameters:

  [in] | recurse | optional parameter to control whether all namespaces or just top-level namespaces are returned. A value of false (the default if unspecified) causes only the top-level namespaces to be returned. If true, all namespaces will be listed.
  [out] | ReturnStatus | optionally returns the status code.

Returns:
  The list of namespaces in the current namespace.

Status Codes:
  - MS::kSuccess successful execution.

MStringArray getNamespaces | ( | const MString & | parentNamespace,
|  | const bool | recurse = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Return a list of all child namespaces of `parentNamespace', with the option to list only direct children versus all descendents.

To list ALL namespaces in Maya, from the root downwards, specify the root namespace, i.e.:

MStringArray namespaces; namespaces = MNamepsace::getNamespaces( MNamespace::rootNamespace() );

Note: names returned are always absolute (e.g. :a:b:sphere).

Parameters:

  [in] | parentNamespace | the namespace to query.
  [in] | recurse | optional parameter to control whether all descendents or just the direct children are returned. A value of false (the default if unspecified) causes only the direct children of `parentNamespace' to be listed. A value of true causes all descendent namespaces to be returned.
  [out] | ReturnStatus | optionally returns the status code.

Returns:
  The list of namespaces in the namespace specified via the 'namespacesToQuery' parameter.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kInvalidParameter `parentNamespace' does not exist.

bool namespaceExists | ( | const MString & | name,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Check if a given namespace exists.

Parameters:

  [in] | name | the name of the namespace to search for.
  [out] | ReturnStatus | optionally returns the status code.

Status Codes:
  - MS::kSuccess successful execution.

Returns:
  - true the namespace with the given name exists.
  - false the namespace with the given name does not exist.

MString parentNamespace | ( | MStatus * | ReturnStatus = `NULL` | ) | `[static]`

Search for all occurrences

Get the name of the current namespace's parent.

This name is returned as an absolute namepath (i.e. fully qualfied from the root namespace downwards, ":a:b"). If the root namespace is current, this method returns an error.

Parameters:

  [out] | ReturnStatus | optionally returns the status code.

Status Codes:
  - MS::kSuccess successfully returned the name of the current namespace's parent.
  - MS::kFailure the current namespace is the root namespace which has no parent.

Returns:
  The name of the current namespace's parent as an absolute namepath.

MStatus removeNamespace | ( | const MString & | name,
|  | bool | removeContents = `false`
| ) |  | `[static]`

Search for all occurrences

Remove the specified namespace.

Note that removing a namespace changes the scene, so any code that calls this method needs to handle undo.

Parameters:

  [in] | name | specifies the namespace to remove.
  [in] | removeContents | detemine if remove contents of namespace

Returns:
  The return status code.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kInvalidParameter the namespace was not found.
  - MS::kFailure attempting to remove a system namespace, such as the root namespace, or if the namespace is non-empty.

MStatus renameNamespace | ( | const MString & | oldName,
|  | const MString & | newName,
|  | const MString * | parent = `NULL`
| ) |  | `[static]`

Search for all occurrences

Rename the specified namespace to a new name with optional parent name.

Note that removing a namespace changes the scene, so any code that calls this method needs to handle undo.

Parameters:

  [in] | oldName | the name of the namespace to rename.
  [in] | newName | the new name for the namespace.
  [in] | parent | optionally provides the name of the new parent.

Returns:
  The return status code.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kFailure the given namespace already exists, the namespace name was invalid, e.g. "a:b" or it was not found or attempting to rename the root namespace.

MObjectArray getNamespaceObjects | ( | const MString & | parentNamespace,
|  | const bool | recurse = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Return an array of MObjects representing the object contained within the specified namespace.

To query the current namespace, call this method thusly:

MObjectArray objs; objs = MNamespace::getNamespaceObjects( MNamespace::currentNamespace() )

Parameters:

  [in] | parentNamespace | namepath of namespace to query.
  [in] | recurse | optional parameter: false (the default if unspecified) causes only the direct children of `parentNamespace' to be listed. true causes all descendents to be listed as well.
  [out] | ReturnStatus | optionally returns the status code.

Returns:
  The list of objects that belong to the namespace specified by the 'parentNamespace' parameter. If the 'recurse' parameter was also specified as true, the list will contain the objects belonging to any child namespaces.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kInvalidParameter `name' was not found.

MStatus moveNamespace | ( | const MString & | src,
|  | const MString & | dst,
|  | const bool | force = `false`
| ) |  | `[static]`

Search for all occurrences

Move the contents of the namespace `src' into the namespace `dst'.

Note that moving namespace contents changes the scene, so any code that calls this method needs to handle undo.

Parameters:

  [in] | src | source namespace from which objects will be moved.
  [in] | dst | destination namespace to which objects will be moved.
  [in] | force | optional parameter which if true forces the move even if name clashes occur, in which case nodes are renamed to ensure uniqueness. If false, the move will not happen if there are clashes. The default value is false.

Returns:
  The return status code.

Status Codes:
  - MS::kSuccess successful execution.
  - MS::kInvalidParameter the namespace `src' and/or `dst' does not exist.

MString rootNamespace | ( | MStatus * | ReturnStatus = `NULL` | ) | `[static]`

Search for all occurrences

Get the name of the root namespace.

This name is an absolute namepath (i.e. prefixed by a ":"). An example use of this method would be to set the current namespace to the root namespace, and this could be done as follows:

status=MNamespace::setCurrentNamespace(MNamespace::rootNamespace());

Another example would be to test if the current namespace is the root, e.g.

if ( MNamespace::currentNamespace() == MNamespace::rootNamespace() ) {

Parameters:

  [out] | ReturnStatus | optionally returns the status code from the operation.

Status Codes:
  - MS::kSuccess Successfully returned the name of the root namespace.

Returns:
  The name of the root namespace as an absolute namepath.

bool relativeNames | ( | MStatus * | ReturnStatus = `NULL` | ) | `[static]`

Search for all occurrences

Query Maya's current "relative name lookup" state.

Relative name lookup causes lookups to be relative to the current namespace. By default, relative name lookup in Maya is off, which causes name lookups to be relative to the root namespace. For example, if you have the object :a:b:sphere, and the current namespace is ":a:b", in relative name lookup mode you can issue a command like

setAttr sphere.translateX 10;

If relative name lookup is off, you need to specify the full namepath, e.g.

setAttr a:b:sphere.translateX 10;

Parameters:

  [out] | ReturnStatus | returns the status of the query.

Returns:
  true if relatve name lookup is on, false otherwise.

Status Codes:
  - MS::kSuccess successful execution.

MStatus setRelativeNames | ( | bool | newState | ) | `[static]`

Search for all occurrences

Set relative name lookup mode.

Note that turning on or off relativeNames mode can change the scene, so any code that calls this method needs to handle undo. See MNamespace::relativeNames() for details on relative name lookup.

Note: relative name lookup mode is intended for bracketing user code which needs to be namespace-independent. Leaving relative name lookup enabled outside of your specific code could cause functionality such as 3rd-party plugins that assume absolute name lookup to fail.

Parameters:

  [in] | newState | true to turn on relative name lookup, false to turn it off. Maya's default setting is false.

Returns:
  Returns the status code from the operation.

Status Codes:
  - MS::kSuccess successfully set the relativeNames value.

MString getNamespaceFromName | ( | const MString & | fullName,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Get namespace from a full name.

For example, given a full name: "a:b:c:d:ball" this method would return: "a:b:c:d".

NOTE: there is no testing to ensure that the name actually refers to an object that exists.

Parameters:

  [in] | fullName | the full name.
  [out] | ReturnStatus | returns the status of the operation.

Returns:
  Returns the namespace from the full name.

Status Codes:
  - MS::kSuccess found the namespace.
  - MS::kFailure fullName parameter had length of zero.

MString stripNamespaceFromName | ( | const MString & | fullName,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Strips the namespace from a full name.

For example, given a full name: "a:b:c:d:ball" this method would return: "ball".

NOTE: there is no testing to ensure that the name actually refers to an object that exists.

Parameters:

  [in] | fullName | the full name.
  [out] | ReturnStatus | returns the status of the operation.

Returns:
  Returns the name part of a full name.

Status Codes:
  - MS::kSuccess found the namespace.
  - MS::kFailure fullName parameter had length of zero.

Examples:
  lepTranslator.cpp.

MString makeNamepathAbsolute | ( | const MString & | namepath,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Make a namepath which is relative to the root into an absolute namepath.

For example, given the namepath "a:sphere" this method returns ":a:sphere". It also culls out duplicate and trailing separators, e.g. "a:b::c:" will return ":a:b:c".

NOTE: there is no testing to ensure that the name actually refers to an object that exists.

Parameters:

  [in] | namepath | the root-relative namepath.
  [out] | ReturnStatus | returns the status of the operation.

Returns:
  The absolute namepath.

Status Codes:
  - MS::kSuccess successful execution.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace
MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace MNamespace