In query mode, return type is based on queried flag.
| Long name (short name) |
Argument types |
Properties |
-name(-n) |
string |
 |
|
This flag only permits the EDITING of the name of the Heads-Up
Display. |
|
-exists(-ex) |
|
  |
|
This flag returns whether the given object exists in the
Heads-Up Display layout. An object name must be supplied with this
command. This flag cannot be combined with any other flag. |
|
-refresh(-r) |
|
|
|
This flag forces the given Heads-Up Display element to refresh,
updating the value displayed. This flag cannot be combined with any
other flag. |
|
-label(-l) |
string |
|
|
Text string that appears to the left of the desired
information. |
|
-layoutVisibility(-lv) |
boolean |
|
|
Sets the visibility of Heads-Up Display layout on and off. This
does not modify individual visibilities of heads-up displays, but
turns off the layout so that no heads-up displays will draw to
screen. Personalized settings for the visibilities of HUDs are kept
safe. This flag can only be used by itself, excepting edit and
query. |
|
-visible(-vis) |
boolean |
|
|
Sets the visibility of the Heads-Up Display on and off. |
|
-allowOverlap(-ao) |
boolean |
|
|
Sets the Heads-Up Display to be visible regardless of
overlapping section widths/limitations (see -s/section flag
description for more details). |
|
-section(-s) |
int |
|
|
Defines the section the HUD will appear in. There are 10
sections divided across the screen. Five columns and two rows make
up the ten element matrix which divide the main viewport. Here is a
visual layout of the sections.
________________________
| | | | | |
| | | | | |
| 0 | 1 | 2 | 3 | 4 |
| | | | | |
|____|____|____|____|____|
| | | | | |
| | | | | |
| 5 | 6 | 7 | 8 | 9 |
| | | | | |
|____|____|____|____|____|
Each section is denoted by a number from 0 to 9 as illustrated
above. For example, if the second column of the top row was
desired, the section would be defined as: -sec 1 To prevent HUD
objects from displaying over each other and causing a clutter of
letters, each row has a defined visibility precedence, where each
section would have a visibility priority level. Depending on each
priority level, when the screen space begins to shrink to a point
where the section widths of a given row begin to collide, the HUD
automatically compensates for this by removing the sections of
least priority. These sections are made invisible and a warning is
issued to inform the user of the removal. This continues until only
the section of highest priority remains. For each row, the
priorities are defined as follows. Using the top row as an example:
Section 0, has the highest priority, followed by Section 4, making
the outermost sections of highest priority. Next in the list is
Section 2, and lastly Sections 1 and 3 are of the equal and least
priority. This priority structure can be applied to the bottom row
as well. The two outermost sections have the highest priority,
followed by the middle section, and finally the remaining two
sections are of lowest priority. This means that as the viewport
gradually decreases in width to the point where sections in the top
row begin to overlap, sections 1 and 3 will be removed from view
first, followed by section 2, and finally section 4. A similar note
is provided below for the block layout. |
|
-block(-b) |
int |
|
|
Denotes the individual block that the HUD will reside in,
within a section. Each section is composed of a single column of
blocks. The total number of blocks contained within each section is
variable. The number of blocks that will be visible within each
section is dependent on the size of blocks contained in each
section and the current size of the window. Blocks begin
enumerating from 0 and flexibly increase based on need. The
resultant output string of each HUD is formatted within each block,
using parameters defined by the formatting flags listed below (eg.
justify, padding, labelWidth and dataWidth). The layout is shown in
the following diagram:
__________________________________________
| | | | | | |
| P | J | LW | DWX | J | P |
|_____|_____|________|_________|_____|_____|
P = Sub-block of width, padding
J = Justification of the entire block
LW = Sub-block of width, labelWidth
DWX = X number of sub-blocks of width, dataWidth, for X data elements.
Block Layout The above diagram shows the layout of each
block. The widths: padding, labelWidth and dataWidth are defined by
their respective flags. To elaborate on the layout of the blocks,
First the padding of the block is calculated. Then the two main
sub-blocks (LW and DWX) in the above diagram, are justified and
positioned together between the left and right margins of the
block. The widths of the main sub-blocks are not variable based on
it's contents. The only sub-block in the above diagram which is
unique is the DWX sub-block which actually represents X number of
sub-blocks, where X is the number of data elements returned by the
command. Block Positioning Blocks on the top section begin
from the top edge of the main viewport, while the bottom section
begins from the bottom edge. Blocks are dynamically removed from
visibility from the midpoint of the viewport. So, a relatively
large block number will not draw to the viewport. Lastly, there can
be at most one HUD occupying a block at any time. Trying to
position a HUD in an occupied block will result in an error. Keep
this in mind when positioning the HUD. |
|
-nextFreeBlock(-nfb) |
int |
|
|
Returns the block number of the next free block in a given
section. |
|
-lastOccupiedBlock(-lob) |
int |
|
|
Returns the block number of the last occupied block in a given
section. |
|
-blockSize(-bs) |
string |
|
|
Sets the height of each block. Available heights are: small,
medium and large. In pixel measurements, each corresponds to a 20,
35 or 50 pixel height, respectively. |
|
-padding(-p) |
int |
|
|
Specifies the width of both the left and right margins of a
block. Default value is 15 pixels. |
|
-blockAlignment(-ba) |
string |
|
|
Specifies the alignment of the block within its respective
column. Available alignments are: "center", "left" and "right". The
default alignment is "left". |
|
-labelFontSize(-lfs) |
string |
|
|
Sets the font size of the label. Available sizes are: small and
large. |
|
-dataFontSize(-dfs) |
string |
|
|
Sets the font size of the returned data. Available sizes are:
small and large. |
|
-dataAlignment(-da) |
string |
|
|
Specifies the alignment of the data blocks and the data text,
within a HUD block. Available alignments are: "left" and "right".
The default alignment is "left". |
|
-labelWidth(-lw) |
int |
|
|
Specifies the pixel width of the virtual "textbox" which will
hold the label. The contents of this "textbox" will be left
justified. If the width of the actual label exceeds the width of
the "textbox," the label will be truncated to fit within the
dimensions of the "textbox." (To see a layout of a block, see the
description of the -block flag.) |
|
-dataWidth(-dw) |
int |
|
|
Specifies the pixel width of the virtual "textbox" which will
hold a data value. For commands which return more than one value
(ie. arrays), one of these "textboxes" will be created for each
data element, each with this specified width. If the width of the
data value exceeds the width of the "textbox", the data value will
be truncated to fit within the dimensions of the "textbox." (To see
a layout of a block, see the description of the -block flag.) |
|
-decimalPrecision(-dp) |
int |
|
|
Sets the decimal precision of any floating point value returned
by the command. The valid range of precision values are 1 to
8. |
|
-showGrid(-sg) |
|
|
|
This flag will toggle the display of the grid lines of the HUD
layout. |
|
-gridColor(-gco) |
int |
|
|
This flag specifies a color for the grid lines using the
inactive color palette. Specifying an index number between 1 to 23
will select the corresponding color in the palette. |
|
-command(-c) |
script |
|
|
Specifies the procedure or script to run, in order to obtain
the desired information. This must return a value or an array of
values. A warning will be displayed if the command does not return
a value. This flag MUST always be accompanied by a trigger flag
(eg. a condition flag, an event flag, an attachToRefresh flag,
etc.). |
|
-nodeChanges(-nc) |
string |
 |
|
Works only with selection based triggers (ie.
"SelectionChanged" or "SomethingSelected"), otherwise this flag is
ignored. This flag attaches the HUD script to execute on specific
node changes of any selected node. This flag is used to set a
nodeChange. In order to reset a nodeChange, use the
-rnc/resetNodeChanges flag. To view a list of all available node
changes, use the -lnc/listNodeChanges flag. The following is a list
of available node changes and their function:
attributeChange: The script will be sensitive to any attribute changes in the currently
selected nodes.
connectionChange: The script will be sensitive to any connection changes in the currently
selected nodes.
instanceChange: The script will be sensitive to any changes to an instance in the
currently selected nodes.
On query mode, this flag will return the values of all nodeChanges
in pairs of values (the name of the nodeChange followed by its
value).
WARNING: (Performance Warning)
Attaching a nodeChange trigger to a selection based trigger can cause a large
performance drop, if the node change that is being watched is caused by the
HUD script itself.
With this said, an attempt should be made to keep the HUD command/script
simple and limited to retrieving data. Changing an attribute, creating or
modifying a connection or instance will all result in a performance drop.
|
|
-resetNodeChanges(-rnc) |
string |
|
|
This flag will reset a specificied nodeChange back to false.
This flag only operates under the edit flag. See the description
for the -nc/nodeChanges flag for further details. |
|
-attachToRefresh(-atr) |
|
|
|
Attaches the command to the refresh process. The script is then
run each time an idle refresh is run and updates directly following
it. |
|
-conditionTrue(-ct) |
string |
|
|
A trigger which runs the command (to sample the data), when the
named condition becomes true. The named condition must be
pre-defined or a user defined boolean. To get a list of what
conditions exist, use the -lc/listConditions flag. |
|
-conditionFalse(-cf) |
string |
|
|
A trigger which runs the command (to sample the data), when the
named condition becomes false. The named condition must be
pre-defined or a user defined boolean. To get a list of what
conditions exist, use the -lc/listConditions flag. |
|
-conditionChange(-cc) |
string |
|
|
A trigger which runs the command (to sample the data), when the
named condition changes. The named condition must be pre-defined or
a user defined boolean. To get a list of what conditions exist, use
the -lc/listConditions flag. |
|
-event(-ev) |
string |
|
|
Runs the command when the named event occurs. The named event,
must be a pre-defined Maya event. To get a list of what events
exist, use the -le/listEvents flag. |
|
-attributeChange(-ac) |
string |
|
|
Runs the command when the named attribute changes value. The
string must identify both the dependency node and the particular
attribute. If the dependency node is deleted, this HUD is removed
(even if the deletion is undoable). |
|
-connectionChange(-con) |
string |
|
|
Runs the command when the named attribute changes its
connectivity. The string must identify both the dependency node and
the particular attribute. If the dependency node is deleted, this
HUD is removed (even if the deletion is undoable). |
|
-disregardIndex(-di) |
|
|
|
This flag can only be used in conjunction with the
-ac/attributeChange flag. If it is specified, and the HUD is
attached to a multi (indexed) attribute, then the HUD command will
run no matter which attribute in the multi changes. |
|
-allDescendants(-ad) |
|
|
|
This flag can only be used in conjunction with the
-ac/attributeChange flag. If it is specified, and the HUD is
attached to a compound or multi attribute, then the HUD command
will run due to changes to the specified attribute as well as
changes to its descendants. |
|
-preset(-pre) |
string |
|
|
This setting is used to select certain pre-defined HUDs, some
of which retrieve specific data, that is unobtainable through
normal MEL commands or scripts. This flag is mutually exclusive
from the command and trigger flag combination. However, presets can
work with all other headsUpDisplay attribute flags (ie. block
alignment, label, dataFontSize, etc.), unless otherwise specified
below. To obtain a list of available presets, use the
-lp/listPresets flag on this command. The following is a list of
available presets and a description of each:
- cameraNames
- This will return the camera name that the view is looking
through, in the data block, for each view that the HUD is drawing
to.
- polyVerts
- This will return three values in the data block, regarding the
number of vertices that are visible by the camera.
- 1st Value: Represents the number of camera visible vertices,
both active and inactive.
- 2nd Value: Represents the number of camera visible vertices, on
active objects only.
- 3rd Value: Represents the number of camera visible vertices,
that are active.
- polyEdges
- This will return three values in the data block, regarding the
number of edges that are visible by the camera. The order of these
three values are similar to the polyVerts preset.
- polyFaces
- This will return three values in the data block, regarding the
number of faces that are visible by the camera. The order of these
three values are similar to the polyVerts preset.
- polyUVs
- This will return three values in the data block, regarding the
number of UVs that are visible by the camera. The order of these
three values are similar to the polyVerts preset.
- polyTriangles
- This will return three values in the data block, regarding the
number of triangles that are visible by the camera. The order of
these three values are similar to the polyVerts preset.
- frameRate
- This will return a single string carrying both the frame rate
and the "fps" string in the data block. It updates on each
refresh.
- viewAxis
- This will draw the orientation of the grid axes within the HUD.
It updates on each refresh. While this preset can take in all
attribute flags, the only one which will have an effect are block
attribute related flags (ie. block alignment and block size). The
block dimensions of this preset are: blockSize - "large" and
blockWidth - "50", which results in a 50x50 pixel region.
- distanceFromCamera
- This will return in the data block the distance from the view's
camera to the centre of the bounding box containing the selected
objects in the view.
|
|
-listConditions(-lc) |
|
|
|
This flag will return a string array containing all names of
the available conditions. |
|
-listEvents(-le) |
|
|
|
This flag will return a string array containing all names of
the available events. |
|
-listHeadsUpDisplays(-lh) |
|
|
|
This flag will return a string array containing all names of
existing HUDs. |
|
-listNodeChanges(-lnc) |
|
|
|
This flag will return a string array containing all names of
the available node changes. |
|
-listPresets(-lp) |
|
|
|
This flag will return a string array containing all names of
the available preset HUDs. |
|
-scriptResult(-sr) |
|
|
|
This flag is only used in conjunction with the query flag.
Calling a query on this flag returns the most recent result of the
HUD. |
|
-remove(-rem) |
|
|
|
This command will remove a given HUD object, given a specified
HUD name. This flag will override all other flags and is mutually
exclusive from the other remove flags. |
|
-removeID(-rid) |
int |
|
|
This command will remove a given HUD object, given a specified
HUD ID number assigned to it at creation time. This flag will
override all other flags and is mutually exclusive from the other
remove flags. |
|
-removePosition(-rp) |
int int |
|
|
This command will remove the contents of a specific block
location in the HUD layout. This flag will override all other flags
and is mutually exclusive from the other remove flags. Syntax for
this flag is: -removePosition/rp [section] [block]. |
|
-setOption(-so) |
string string |
|
|
This flag will edit the option specified by the first string.
Current options are: smpPolyCount - "cage" or "smp" - in smooth
mesh preview, determines the poly count display |
|
-getOption(-op) |
string |
|
|
This flag will return the value of the option specified by the
string. See setOption for a list of options
In query mode, this flag needs a value.
|
|