One thing that is a bit strange about Maya scripting is that the same command can be used in up to three different ways—create, query, and edit modes—with the specifics varying for each of the command flags. This is a byproduct of the fact that the Python functionality is a wrapper around the older MEL-based scripting system, and it can seem a bit confusing when you're getting started. Nevertheless, it is important to understand the differences between the three modes and how to use them.
Open up the Python command reference by going to Help | Python Command Reference and navigate to the documentation for the polyCube command.
Also, be sure to have the script editor open in Maya and be in the Python tab. Alternatively, you can run the example commands Maya's command line; just make sure that you're running in Python mode rather than MEL (click on MEL to switch to Python and Python to switch back to MEL).
First off, take a look at the Properties column. You'll see that every flag has some combination of "C", "E", "Q", and "M" listed. Those refer to the different ways in which a command can be run and have the following meanings:
C: "Create" flag is only relevant when first running the command, such as when you initially create a polygonal primitive
Q: "Query" flag can be queried after the command has been run and can be used to retrieve information about something in the scene
E: "Edit" flag can be edited after the fact
M: "Multiple" flag can be used more than once in a single instance of the command (to create specify multiple points when creating a curve, for example)
For many flags, you'll see a full complement of create, query, and edit, but there are generally at least a few flags that aren't accessible for one or more of the modes.
Let's see how create, edit, and query play out in the case of the polyCube command.
First off, let's make a new cube and store the result in a variable, so we can make use of it later:
myCube = cmds.polyCube()
Now, let's change something about the cube, post-creation by using the edit mode:
cmds.polyCube(myCube, edit=True, subdivisionsX=5)
This will cause the cube that we created with the first command to be altered from the default (no subdivisions in the x axis) to having five.
Now, let's use the query mode to store the new number of divisions to a variable:
numberDivisions = cmds.polyCube(myCube, query=True, subdivisionsX=True) print(numberDivisions)
You should see "5.0" as the output. Note that even though the number of divisions of a polygonal cube must be an integer value, Maya is displaying it as "5.0".
The important thing to note for the query and edit modes is that you run the command as you normally would (cmds.polyCube, for example), but with the following three key differences:
The inclusion of the name of the object as the first argument. This can either be the name directly as a string
("pCube1", for example), or a variable.The inclusion of either
edit=Trueorquery=Trueas an argument.Additional arguments, with the specifics based on whether you're running the command in the query or edit mode.
For the edit mode, you'll want to specify the name of the property you want to change, along with the new value. For the query mode, you'll want to just include the name of the property and "=True". Think of this as saying that it is True that you want to know the value of the property. Note that you can only query a single flag at a time. If you need to query multiple values, run the command multiple times, changing the flag you pass in.
Although many of the most-used properties can be used in all three modes, there are numerous examples of ones that cannot be, mainly because it wouldn't make sense to do so. For example, it's perfectly reasonable to set construction history on or off when creating a new object, and it's certainly reasonable to query that after the fact, but what would it mean to use the edit mode to enable construction history on an object that didn't already have it? That would require rebuilding the history of the object, which may have been manipulated in various ways since it was created. As a result, the "constructionHistory" (or "ch") flag only offers the Create and Query options.
You might think that this is all a bit clunky, and if all we wanted to do was set the number of subdivisions for a newly created cube, you would be correct. However, it's important to understand the different command modes, both to get information after the fact and because it's an important part of building user interface elements and getting information from them.
We'll be making the extensive use of the Query mode to retrieve information from user interface elements throughout the rest of the book, starting in Chapter 2, Creating User Interfaces.