Go to: Synopsis. Return value. Related.
Flags. Python
examples.
workspace( [string] , [active=boolean], [baseWorkspace=string], [create=string], [directory=string], [expandName=string], [fileRule=[string, string]], [fileRuleEntry=string], [fileRuleList=boolean], [filter=boolean], [fullName=boolean], [list=boolean], [listFullWorkspaces=boolean],
[listWorkspaces=boolean],
[newWorkspace=boolean],
[objectType=[string, string]],
[objectTypeEntry=string],
[objectTypeList=boolean],
[openWorkspace=boolean],
[projectPath=string],
[removeFileRuleEntry=string],
[removeVariableEntry=string],
[renderType=[string, string]],
[renderTypeEntry=string],
[renderTypeList=boolean],
[rootDirectory=boolean],
[saveWorkspace=boolean],
[shortName=boolean], [update=boolean], [updateAll=boolean], [variable=[string, string]], [variableEntry=string], [variableList=boolean])
Note: Strings representing object names and
arguments must be separated by commas. This is not depicted in the
synopsis.
workspace is undoable, queryable, and NOT editable.
Create, open, or edit a workspace associated with a given workspace
file. The string argument represents the workspace. If no workspace
is specified then the current workspace is assumed. A workspace
provides the underlying definition of a Maya Project. Each project
has an associated workspace file, named workspace.mel, which is
stored in the project root directory. The workspace file defines a
set of rules that map file types to their storage, either relative
to the project root or as an absolute location. These rules are
used when resolving file paths at runtime. The workspace command
operates directly on the low-level definition of the workspace to
read, change and store the definition to the underlying file. Use
of this command is not generally required, for most purposes it is
recommended that project definition changes be done via the Project
Window in the User Interface.
In query mode, return type is based on queried flag.
translator
active, baseWorkspace, create, directory,
expandName, fileRule, fileRuleEntry, fileRuleList, filter, fullName,
list, listFullWorkspaces, listWorkspaces, newWorkspace, objectType, objectTypeEntry, objectTypeList, openWorkspace, projectPath, removeFileRuleEntry, removeVariableEntry, renderType, renderTypeEntry, renderTypeList, rootDirectory, saveWorkspace, shortName, update,
updateAll, variable, variableEntry, variableList
Long name (short name) |
Argument types |
Properties |
newWorkspace(n) |
boolean |
|
|
This specifies that a new workspace is being created. If a
workspace with this name already exists, the command will
fail. |
|
openWorkspace(o) |
boolean |
|
|
Open the workspace. The workspace becomes the current
workspace. |
|
active(act) |
boolean |
|
|
This flag is a synonym for -o/openWorkspace. |
|
saveWorkspace(s) |
boolean |
|
|
Save the workspace. Workspaces are normally saved when Maya
exits but this flag will make sure that the data is flushed to
disk. |
|
baseWorkspace(bw) |
string |
|
|
A workspace may be based on another workspace. This means that
all the settings in the base workspace apply to this workspace
unless they are explicitly overridden. |
|
listWorkspaces(lw) |
boolean |
|
|
Returns a list of all the currently defined workspace
names. |
|
listFullWorkspaces(lfw) |
boolean |
|
|
Returns a list of the full path names of all the currently
defined workspaces. |
|
list(l) |
boolean |
|
|
This option will list the current workspace directory. If a
path is specified for the "workspaceFile" then the contents of that
directory will be listed. Otherwise, the contents of the directory
set with the -dir flag will be listed. |
|
directory(dir) |
string |
|
|
This option will set the current workspace directory to the
path specified. When queried it will return the current workspace
directory. This directory is used as an initial directory for the
fileBrowser and is part of the search path used for locating
files. It should not be confused with the current working
directory as used by the pwd and chdir commands. When
the file browser is used, it will set this value to the last
location navigated to. |
|
create(cr) |
string |
|
|
Create a new directory. If the directory name is not a full
path name, it will be created as a subdirectory of the "current"
directory set with the -dir flag. |
|
rootDirectory(rd) |
boolean |
|
|
Returns the root directory of the workspace. |
|
objectType(ot) |
[string, string] |
|
|
This flag is obsolete. All default locations will be added to
the fileRules going forward. |
|
objectTypeList(otl) |
boolean |
|
|
This flag is obsolete. This will now return the same results as
fileRuleList going forward. |
|
objectTypeEntry(ote) |
string |
|
|
This flag is obsolete. This will now return the same as
fileRuleEntry. |
|
fileRule(fr) |
[string, string] |
|
|
Set the default location for a file. The first parameter is the
fileRule name(scenes, images, etc) and the second is the location.
When queried, it returns a list of strings. The elements of the
returned list alternate between fileRule names and the
corresponding location. There is typically one file rule for each
available translator. Environment variables are supported. You can
set multiple path for the file rule by separating them with
semicolons (;) on Windows and colons(:) on MacOSX and Linux. Note
that whitespace at the beginning and end of each item in the
separated sequence is significant and will be included as part of
the path name (which is not usually desired unless the pathname
does actually start or end with spaces). A valid filerule name
cannot contain multiple byte characters. |
|
fileRuleList(frl) |
boolean |
|
|
Returns a list of the currently defined file rules. |
|
fileRuleEntry(fre) |
string |
|
|
Return the location for the given fileRule. |
|
removeFileRuleEntry(rfr) |
string |
|
|
Remove the given file rule from the specified workspace. If the
workspace name is not specified, the given file rule will be
removed from the current workspace. |
|
renderType(rt) |
[string, string] |
|
|
This flag is obsolete. All default render types will be added
to fileRules going forward. |
|
renderTypeList(rtl) |
boolean |
|
|
This flag is obsolete, use fileRuleList going forward. |
|
renderTypeEntry(rte) |
string |
|
|
This flag is obsolete, use fileRuleEntry going forward |
|
variable(v) |
[string, string] |
|
|
Set or query the value of a project variable. Project variables
are used when expanding names. See the -en/expandName flag
below. |
|
variableList(vl) |
boolean |
|
|
Return a list of all variables in the workspace. |
|
variableEntry(ve) |
string |
|
|
Given a variable name, will return its value. |
|
removeVariableEntry(rve) |
string |
|
|
Remove the given variable from the specified workspace. If the
workspace name is not specified, the given variable will be removed
from the current workspace. |
|
shortName(sn) |
boolean |
|
|
Query the short name of the workspace. |
|
fullName(fn) |
boolean |
|
|
Return the full name of the workspace. |
|
expandName(en) |
string |
|
|
Query for the full path location of a filename using the
current workspace definition. The path may be a project relative
file name, a full path name or a variable name. The return value is
always a full path name. If the path is an empty string, the return
value will be the project root directory. Variable expansion is
supported, and will consider both variables defined in the
workspace as well as environment variables. There are three formats
supported for expanding variable names: %variableName%,
$variableName, ${variableName}. Maya will first attempt to find
matching variables defined in the current workspace, then search
for a matching environment variable. The tilde character ('~') is
also supported. If a tilde is located at the beginning of a
variable, Maya will only consider and expand environment variables,
and will leave the tilde in the expanded result. On linux platforms
only, a tilde can be used to expand a user's home directory, using
the form ~username, ~, or ~/. When specified as ~username, it will
be replaced with the corresponding user's home directory. When
specified as ~ or ~/, it will be replaced with the value of the
HOME environment variable. |
|
projectPath(pp) |
string |
|
|
Convert filePath passed as argument to a filename that is
relative to the project root directory (if possible) and return it.
If the filePath is not under the project root directory, a full
path name will be returned. |
|
update(u) |
boolean |
|
|
This flag reads all the workspace definitions from the project
directory. It is used by Maya at startup time to find the available
workspaces. |
|
updateAll(ua) |
boolean |
|
|
This flag is a synonym for -u/update. |
|
filter(f) |
boolean |
|
|
Flag can appear in Create mode of
command |
Flag can appear in Edit mode of command |
Flag can appear in Query mode of command |
Flag can have multiple arguments, passed
either as a tuple or a list. |
import maya.cmds as cmds
# Set the current workspace to "alphabet".
cmds.workspace( 'alphabet', openWorkspace=True )
# Save the current workspace settings (for "alphabet").
cmds.workspace( saveWorkspace=True )
# Create a new workspace named "newWorkspace".
cmds.workspace( 'newWorkspace', newWorkspace=True )
# The settings of "newWorkspace" are based on "default" workspace
cmds.workspace( baseWorkspace='default' )
# Return the list of existing workspaces
cmds.workspace( listWorkspaces=True )
# Result: default newWorkspace
# Add a scriptJob to run on workspaceChanged events
def workspaceChangedCallback():
print 'My workspaceChangedCallback was called'
workspaceChangedID = cmds.scriptJob( event = ["workspaceChanged", workspaceChangedCallback] )
# add a file rule to the current workspace
cmds.workspace(fileRule = ['newFileRuleName', 'newFileRuleValue'])
My workspaceChangedCallback was called #workspaceChangedCallback was called
# look up the value of the file rule entry
cmds.workspace(q = True, fileRuleEntry = 'newFileRuleName')
# Result: newFileRuleValue
# remove specified file rule entry
cmds.workspace(removeFileRuleEntry = 'newFileRuleName')
My workspaceChangedCallback was called #workspaceChangedCallback is called
# kill the scriptJob with the number
cmds.scriptJob(kill = workspaceChangedID)
# The following example shows how to expand environment and workspace variables
# expand a path value to be a full path relative to the project directory
# relative path example
cmds.workspace( expandName = 'relativePathName')
# Result: /h/userName/maya/projects/newWorkspace/relativePathName/
# full path example
cmds.workspace( expandName = '/h/userName/maya/projects/default/')
# Result: /h/userName/maya/projects/default/
# The following examples show various formats for expanding workspace and
# environment variables.
# add a variable to the current workspace
cmds.workspace(variable = ['newVariableName', 'newVariableValue'])
cmds.workspace( expandName = '%newVariableName%')
# Result: /h/userName/maya/projects/newWorkspace/newVariableValue/
# add an environment variable with the same as the workspace variable
maya.mel.eval('putenv "newEnvVariableName" "newEnvVariableValue"')
cmds.workspace( expandName = '%newEnvVariableName%')
# Result: /h/userName/maya/projects/newWorkspace/newEnvVariableValue/
# The following example shows how conflicting names in both workspace
# and environment variables are resolved.
# add a environment variable with the same name as a workspace variable
maya.mel.eval('putenv "newVariableName" "newEnvVariableValue"')
# maya considers workspace variables first before matching environment variables
cmds.workspace( expandName = '%newVariableName%')
# Result: /h/userName/maya/projects/newWorkspace/newVariableValue/
# When a tilde is used, maya will only consider the environment variable
# not the workspace variable.
cmds.workspace( expandName = '~%newVariableName%')
# Result: /h/userName/maya/projects/newWorkspace/~newEnvVariableValue/
# The following example shows how to set multiple paths into a fileRule value
cmds.workspace(fileRule = ['newMultiPathFileRuleName', '/h/userName/maya/projects/default;newFileRuleValue'])
multipath = cmds.workspace(q = True, fileRuleEntry = 'newMultiPathFileRuleName')
# Result : /h/userName/maya/projects/default;newFileRuleValue
# The following will only return the first expanded path.
cmds.workspace( expandName = multipath)
# Result : /h/userName/maya/projects/default
# Note that white space at the beginning or end of each path is significant.
# Add a file rule that uses multiple paths with the white space at the beginning and end of each path
cmds.workspace(fileRule = ['newMultiPathFileRuleName', ' /h/userName/maya/projects/default ; newFileRuleValue '])
# Querying and expanding the path value shows that the white space is still included.
multipath = cmds.workspace(q = True, fileRuleEntry = 'newMultiPathFileRuleName')
# Result : /h/userName/maya/projects/default ; newFileRuleValue
# Find the current workspace area.
cmds.workspace( q=True, directory=True )
# Result : /h/userName/maya/projects/default
# Note that the "current working directory" as defined by the
# 'pwd' and 'chdir' commands is unrelated to the directories
# used by the workspace command
#
cmds.pwd()
# Result : /usr/tmp
cmds.chdir( '/tmp' )
getcwd()
# Result : /tmp
cmds.workspace( q=True, directory=True )
# Result : /h/userName/maya/projects/default
cmds.workspace( directory='/h/userName/maya/projects/commercial' )
getcwd()
# Result : /tmp