Input GUI Commands

(New in 102.31m+) Opens the window in a 'hidden' state if value is 1.

hide {val}

This is disabled by default.

Use this to define a window that should not be show by default when the application is run. The window can be told to open later by hitting a button whose winshow window index is set to this window.

saveid "string"

By tying a unique name to each form, the user will be warned if they try to Import a form file that was Exported from a different form.

'string' should be descriptive of the type of form this is, as the string will be shown in the error presented to the user when they try to Import the file into a different form.

xysize {xval} {yval}

Sets the initial size of the window. If unspecified, the window appears 720x486.

HelpFor

Don't use this if you're using the newer HTML oriented

inputstring "Prompt Text" "Dbase-Name" "Default Text"

HelpFor is used to pre-define helptext for the InputString and InputFilename commands. This allows one to define the help text in a higher section of the file, away from the definition of the input fields, to prevent clutter. Example:

    helpfor "SceneFilename"
    {
        Enter the scene filename. Must be an absolute path.
	Use UNC paths when possible to avoid cross platform issues.
    }
    :
    inputfilename "Scene Filename" "SceneFilename" "//foo/bar"
    :

InputString

InputString is a new (102.31n+) shortcut way to define input fields using a single line, instead of the multiline Input commands.

This command uses the current XY value for the position, and the current XYSize for the size of the input field.

Example:

    apphelp
    {
    :
        <A NAME="RenderOpts">
	<H1>Render Options</H1>
	HTML Documentation on the Render Options field goes here..
	:
    }
    :
    xy 100 100
    xysize 320 24
    :
    inputstring "Render Options" "RenderOpts" ""
    :

InputFilename

inputfilename "Prompt Text" "Dbase-Name" "Default Text" ["Filter"]

InputFilename is a new (102.31n+) shortcut way to define filename prompts using a single line, instead of the multiline Input commands with the filebrowser enabled.

(New in 102.31p)

See the 'input' command's filebrowserfilter for the possible wildcard character strings that can be specified for the filter.

This command uses the current XY value for the position, and the current XYSize for the size of the input field. The filebrowser button is enabled, so the user can select filenames.

Example:

    apphelp
    {
    :
        <A NAME="SceneFilename">
	<H1>Scene Filename</H1>
	HTML Documentation on the Scene Filename field goes here..
	:
    }
    :
    xy 100 100
    xysize 320 24
    :
    inputfilename "Scene Filename" "SceneFilename" "//foo/bar" "*.scn"
    :

InputMultiline

inputmultiline "Prompt Text" "Dbase-Name" "Default Text"

InputMultiline is a new (102.31n+) shortcut way to define multiline string prompts using a single line definition, instead of the longer Input specification with 'multiline' enabled.

This command uses the current XY value for the position, and the current XYSize for the size of the input field. The 'multiline' option is enabled, so that several lines of input can be specified by the user.

If an 'apphelp' document has been defined, then a help button is automatically created, and linked to the global 'apphelp' using the 'dbname' field as the link.

Example:

    apphelp
    {
    :
        <A NAME="Cpus">
	<H1>Cpus</H1>
	HTML Documentation on the Cpus field goes here..
	:
    }
    :
    xy 100 100
    xysize 320 24
    :
    inputmultiline "Cpus" "Cpus" ""
    :

Input

input
{
    name         "Job Title"
    labelsize    14
    dbname       "JobTitle"
    default      "TEST_${USER}"
    xysize       280 24
    helpfontface 13
    helpfontsize 14
    help
    {
        The title for your job, which shows up
        in the job reports and audit logs.
    }
}

Input prompts allow the user to enter single or multiline text.

name "text"

labelfont

labelsize

dbname "text"

dbname

filebrowser {yes|no}

Enables a file browser button to appear next to the input widget, so the user can bring up a file browser on the filename currently in the input box.

filebrowserfilter "*.foo"

(New in 102.31p)

* matches any sequence of 0 or more characters.
? matches any single character.
[set] matches any character in the set. Set can contain any single characters, or a-z to represent a range. To match ] or - they must be the first characters. To match ^ or ! they must not be the first characters.
[^set] or [!set] matches any character not in the set.
{X|Y|Z} or {X,Y,Z} matches any one of the subexpressions literally.
\x quotes the character x so it has no special meaning.
x all other characters must be matched exactly.

Multiple filters can be specified. Examples:

filebrowserfilter "*.shk" # *.shk only
filebrowserfilter "*.{ma|mb}" # *.ma and *.mb files
filebrowserfilter "*.aif[fc]" # *.aiff and *.aifc

apphelp on

Creates a help button that links to the global

Sets the alignment of the name text. Values can be added together. See the

help { multiline text }

Opening and closing braces must appear on new lines, eg:

	help
	{
	    This is a test.
	    So is this
	}

default "text"

input -f datafile

"text" may contain environment variables (which are expanded before being displayed), eg.

    default "The home variable is set to ${HOME}"

'\${HOME}'

'${HOME}'

multiline

xysize

xywh

align {val}

align value table

labelfont {val}

Sets the font used in help popups defined by help. See the

labelsize {val}

name

helpfontface {val}

(New in 102.31m+)
Sets the font used by the input field. See the

helpfontsize {val}

help

textfont {val}

Sets the pixel size of the widget. Does not affect the current 'default' position of the widget.

textsize {val}

(New in 102.31m+)

xy {x} {y}

xysize

xysize {w} {h}

xywh {x} {y} {w} {h}

Sets absolute position and size of widget.

color {val}

Input prompts allow the user to enter single or multiline text.

Button

button
{
    name        "Stop"
    xysize      100 30
    system      "rsh how 'echo STOP > /dev/console'"
    color       9
}

name "text"

labelfont

labelsize

labelcolor {val}

name

color value chart

labelfont {val}

Font Types

labelsize {val}

name

color {val}

(New in 102.31m+) Sets the window index for the window to be opened when you hit this button. So if you define two windows, 'winopen 0' will open the first one, 'winopen 1' will open the second one. This is useful to have a button open another defined window. It usually works best if the window to be opened was defined with its

command "the_command"

When the button is hit, these things happen:

The current form is saved to a file
The command is executed. It can use the INPUT_DBASE environment variable to determine the filename of the saved form, which the program can load (but not modify) and act on.

The program's output will be displayed in a pop up window if showfail 1 is configured for the button, and the command returns a non-zero exit code.

Similar to system "text", which does not absorb the program's output, and simply invokes the system(2) C library call.

Command must be quoted.

updatecommand "the_command"

When the button is hit, these things happen:

The current form is saved to a file
The 'command' program is executed.
The program should use the INPUT_DBASE environment variable to determine the filename of the saved form file, which it can load, modify, and rewrite.
The (modified) form is then reloaded as the current form, updating the screen with any mods applied by the program.

The program's output will be displayed in a pop up window if showfail 1 is configured for the button, and the command returns a non-zero exit code.

Command must be quoted.

system "the_command"

command

When the button is hit, these things happen:

The current form is saved to a file
The command is executed. It can use the INPUT_DBASE environment variable to determine the filename of the saved form, which the program can load (but not modify) and act on.

systemflags "flags"

Controls how the system command is executed. 'flags' must be quoted. 'flags' is a combination of one or more letter flags shown below. If unspecified, the default behavior is:

No console window is opened.
The program blocks until the command finishes executing.
Commands are run in a CMD shell

'flags' is a combination of one or more of these single letter flags:

c	Create a console window
m	creates console window minimized
b	background the process (don't wait)
s	stdio inheritance (default off)
e	exec; don't run commands in a 'cmd' shell

Here are some examples:

`systemflags ""`	No console window is opened. The main program blocks until the program finishes executing. Command is run in a CMD shell.
`systemflags "c"`	A console window is opened. The main program blocks until the program finishes executing. Command is run in a CMD shell.
`systemflags "cm"`	A console window is opened minimized. The main program blocks until the program finishes executing. Command is run in a CMD shell.
`systemflags "b"`	No console is opened. The command is run in the background; the main program does not wait. Command is run in a CMD shell.

winhide {window_index}

(New in 102.31m+)

winshow {window_index}

hide

xy {x} {y}

xysize

xysize {w} {h}

Sets the pixel size of the widget. Does not affect the current 'default' position of the widget.

xywh {x} {y} {w} {h}

Sets absolute position and size of widget.

Boxes

box
{
    name      "Submit Maya"
    labelsize 36
    align     0
    type      0
    labeltype 4
    labelfont 0
    xysize    600 30
    color     52
    boxaround 0 0
}

Let you create boxes of color, and/or place short text strings into your GUI, such as title headings and comments.

name "text"

Sets the text displayed in the box.

align {value}

Sets the alignment of the text. The value can be logically ORed values from the

Alignment Types

type {value}

Sets the type of box. See the

Box Types

color {val}

Note: if the box is transparent (default), it will have no color.

boxaround {x} {y}

If {x} and {y} are zero, the box fits exactly the size of the text, otherwise these values are added to the width and height of the box, eg. width += x; height += y;

labelfont {val}

Font Types

labeltype {val}

See this

Label Types

labelsize {val}

name

labelcolor {val}

Sets the font used in help popups defined by help. See the

help { multiline text }

help

"?"

Opening and closing braces must appear on new lines, eg:

	help
	{
	    This is a test.
	    So is this
	}

helpfontface {val}

Sets the initial size (width and height) of the box. If unspecified, the box default size is based on the global

helpfontsize {val}

help

xy {x} {y}

xysize

xysize {w} {h}

xysize

xywh {x} {y} {w} {h}

Sets absolute position and size of box.

Choice

choice
{
    name      "Make Logdir?"
    dbname    "MakeLogdir"
    labelsize 14
    option    "yes"
    option    "no"
    xysize    100 24
    helpfontface 4
    helpfontsize 14
    help
    {
	Should the logdir be created if one is set,
	but doesn't already exist?

	    yes   # Create the log directory if not already there
	    no    # No, don't create the log directory
    }
}

Creates a 'pulldown' menu chooser that lets the user select from a list of choices. The chosen item is saved into the key/value file; the text of the chooser is used as the 'value'.

name "text"

Sets the text displayed next to the chooser, based on the 'align' value.

align {value}

Sets the alignment of the text. The value can be logically OR-ed values from the

Alignment Types

type {value}

Um, I'm not sure what these values do in this context. Try it and see.

color {val}

labelfont {val}

Font Types

labeltype {val}

See this

Label Types

labelsize {val}

name

labelcolor {val}

Creates a help button that links to the global

apphelp on

Sets the font used in help popups defined by help. See the

help { multiline text }

help

"?"

Opening and closing braces must appear on new lines, eg:

	help
	{
	    This is a test.
	    So is this
	}

helpfontface {val}

(New in 102.31m+)
Sets the font used by the chooser popup. See the

helpfontsize {val}

help

textfont {val}

Sets the initial size (width and height) of the chooser. If unspecified, the chooser default size is based on the global

textsize {val}

(New in 102.31m+)

xy {x} {y}

xysize

xysize {w} {h}

xysize

xywh {x} {y} {w} {h}

Sets absolute position and size of chooser.

option "text"

Adds an option to the chooser. "text" is what is shown in the chooser, and is put into the key/value file if the user chooses it.

default "text"

Sets which 'option "text"' is the default. If unset, the first 'option "text"' is the default.

dbname "name"

dbname

Submit

submit
{
    submitname   "Submit"
    cancelname   "Cancel"
    submitcolor  51
    cancelcolor  51
    submitcmd    "myprogram -submit" 
    showfail     1
}

Creates the 'submit' and 'cancel' buttons that are usually common to all submission based forms.

apphelp on

Creates a help button that links to the global

The text displayed inside the 'Cancel' button. Normally "Cancel", but it can be anything you want.

cancelname "string"

cancelcolor {val}

If 'exitok' is set to 1, and the command exits successfully (with a return value of 0), the main program will exit.

exitok {0|1}

helpcolor {val}

Sets the text in the help button. By default, this is "?".

helpname "string"

helpfontface {val}

Sets the font used in help popups defined by help. See the

helpfontsize {val}

help

labelfont {val}