Command System: Query Operators
In previous articles we covered executing commands by passing arguments to them, and querying commands to get their values. With a script or plug-in, you could read the queried value, modify it, and execute the command with the new value.
Often all you want to do is increment the value, or set it to it's minimum or maximum value. It seems kind of silly to create an entire script every time you want to do such a simple operation. Query operators, or modified queries, allow you to easily execute a command by adjusting the queried value of one of it's arguments through some simple operators.
A query operator is applied in a similar manner to a query, where the argument being queried is marked with a question mark. Unlike a simple query, the operator then adds one or more other characters and a value indicating how the argument is to be modified. For example, the ?+ addition operator indicates that queries the value (?) and adds (+) to it the number following the plus.
tool.attr prim.cube segmentsX ?+4
As with normal queries, this feature works only on arguments that support querying.
The operators only function on arguments matching any of the following criteria:
- Arguments with numeric datatypes, including integers, floats, distances, angles, lights, time, uvcoords, percent, memory, pixel and axis. The math and step operators always apply. If the argument's range is capped, the ?min and/or ?max operators may also be supported.
- Arguments that define their control type as a popup. This includes arguments that provide TextValueHints. These implicitly support the ?min and ?max operators.
- Arguments with the boolean datatype. Applying the math or step operators simply toggles the boolean's state, while ?min sets it to false and ?max sets it to true.
Addition and subtraction query operators can be used on both raw values and with units. To use with units, include the operator before the square braces. This is most useful for dealing with angles in degrees instead of their raw mode of radians.
tool.attr prim.cube cenX ?+[45.0] tool.attr prim.cube cenX value:?-[45.0]
Mathematical query operators support adding, subtracting, multiplying and dividing values.
Adding and Subtracting Values
Basic math can be performed on arguments with numeric datatypes. This is done with the ?+ and ?- operators followed by a number. A command such as this could be used to increase the number of segments on the X axis of the Cube primitive tool by 2:
tool.attr prim.cube segmentsX ?+2
Numeric values can be scaled using ?* and ?/ followed by a number. This works similarly to adding and subtracting values. This command would double the size of the Cube primitive tool on the Y axis:
tool.attr prim.cube sizeY ?*2
Numeric argument values can also be incremented or decremented in steps. These steps are the same as when clicking and dragging on a minislider, and scale based on the size of the value.
Stepping is done with ?+ and ?-, but without adding a number to the end. Here we'll move the Cube primitive tool's center into the Z axis using the standard step.
tool.attr prim.cube cenZ ?-
Stepping can also be used on boolean values, which, simply toggles the value on or off.
Coarse and Fine Steps
Holding down the ctrl or shift keys while dragging a minislider control will perform finer or coarser adjustments. This is also supported as a query operator.
Fine steps are done with ?<+ and ?<-, while coarse steps are done with ?>+ and ?>-. This again moves the Cube primitive tool's center into the Z axis, but now using a fine step.
tool.attr prim.cube cenZ ?<-
Minimum and Maximum
Many command arguments are limited to a specific numeric range. For example, the number of segments for a primitive tool can't go negative, and there are a fixed number of possible options for arguments featuring TextValueHints or which directly define popups. ?min and ?max are used to jump to an argument's minimum or maximum value.
tool.attr prim.cube segmentsX ?min
Boolean arguments a specially handled by query operators. Booleans are often represented as simple checkmark buttons in the interface. Using any of the ?+, ?-, ?<+, ?<-, ?>+ or ?>- operators will simply toggle from true to false and back again. This makes it easy to toggle boolean arguments on and off.
Integer List Arguments
There are many cases where a command's argument is represented as a list of choices. The argument datatype is usually an integer or string, and querying with ? will return the appropriate value. In the UI, these arguments often appear as popups or mutually exclusive buttons.
Query operators can be used to step forward and backward through a list. When used in this way, the list argument is treated as an integer. ?+, ?-, and the coarse and fine variants can be used to change to the next or previous option in the list. When the beginning of the list is hit with one of the ?- variants, it will loop back to the end of the list. Similarly, the ?+ variants will cause it to loop back to the beginning. If you would prefer to stop at the end or beginning of a list, you can use ?+1 or ?-1, as the ?+n and ?-n operators do not loop.
Text Hint Arguments
Often you might want to toggle between a subset of values in a text hint based list. For example, it might be useful to toggle between color wireframe and no wireframe while skipping over uniform wireframe when 'view3d.wireframeOverlay is mapped to a key. The specific subset of options cab be specified via the text hint list query operator.
This operator takes a list of text hint choices separated by vertical bar characters, |, and wrapped in parentheses. The argument is queried, and if one of the options in the list matches the current value, the next option in the list is used, looping around to the beginning of the list if applicable. If none of the specified options match the queried value, the first entry in the list is returned. These entries are walked in the order they are presented, allowing you to set your own arbitrary ordering, although care should be taken to ensure that each option should appear no more than once for proper behavior.
Query Operators Table
This table lists all of the query operators for easy reference. In this example, the argument is of the distance datatype with a minimum value of 0.0 m and a maximum value of 100.0 m. The Modified Value column shows the results of the Example column applied to a base value of 40 m.