Input GUI Commands

Window
HelpFor
InputString
InputFilename
InputMultiline
Input
Button
Boxes
Choice
Submit
AppHelp
XY
XYSize
Positioning
Color Map Table
Font Table
Align Table
Label Type Table
Box Type Table

Window

window      
{               
    name      "A GUI Interface"
    xysize    720 486 
    color     46
    scroll 
    resizable
}

Every input file must at least have one window definition. For each window defined, it encompasses all widgets defined below it. Commands that can appear within a window block:

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

    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 "Prompt Text" "Dbase-Name" "Default Text"

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

Input

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"

InputFilename is a new (102.31n+) shortcut way to define filename prompts using a single line, instead of the multiline

Input

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"
    :

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

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"

Sets the name of the input prompt, as shown on the screen to the left of the input window. Text must be quoted. Use labelfont and/or labelsize to change the font.

dbname "text"

Sets the 'database name' for this input widget. This name will appear in the temporary file created which contains key/value pairs; the 'key' will be the dbname specified here, the value will be the text entered in the input widget.

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.

apphelp on

Creates a help button that links to the global

AppHelp

help { multiline text }

Creates a "?" help button. If the user hits it, the 'multiline text' is displayed to the user in a popup window.

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

	help
	{
	    This is a test.
	    So is this
	}

default "text"

Sets the default text for the input field. Note; this will be overridden by any settings in the 'input datafile', specified on the commandline as 'input -f datafile'.

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

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

To embed literal characters, such as '$', use '\' to escape the character, eg. '\${HOME}' will prevent the expansion of the variable, using the literal text '${HOME}'.

multiline

Enables multiple lines to be entered by the user, such as paragraphs of text. It's recommended you also use xysize or xywh to make the widget large enough for the user to type multiple lines.

align {val}

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

align value table

labelfont {val}

Sets the font used by name. See the

font table

labelsize {val}

Sets the size of the font used by name in pixels. Or maybe it's points. Whatever. Be happy you can see text at all.

helpfontface {val}

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

font table

helpfontsize {val}

Sets the size of the font used in help popups.

xy {x} {y}

Sets absolute x/y positions for the lower left corner of the widget. Does not affect xysize (eg. doesn't affect width or height).

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.

color {val}

Sets the background color of the input box, according to this

Color Map Chart

Button

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

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

name "text"

Sets the name that shows up on the button. Use labelfont and/or labelsize to change the font. Text must be quoted.

labelcolor {val}

Sets the color for the name text. See this

color value chart

labelfont {val}

Sets the font used by name. See this

Font Table

labelsize {val}

Sets the size of the font used by name in pixels. Or points. Whatever.

color {val}

Sets the background color of the button, according to this

Color Map Chart

command "the_command"

Sets the command that's executed when the button is hit.

When the button is hit, three 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"

Useful for having a button cause a procedural modification to the data in the current form.

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"

Sets the command that's executed when the button is hit. Differs from command in that the command's output is simply sent to stdout/stderr. Command must be quoted. Under Microsoft Windows, a console window is opened for "the_command" to run in.

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"

Microsoft Windows only; under Unix these flags are ignored.

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+) Sets the window index for the window to be closed when you hit this button. So if you define two windows, 'winclose 0' will hide the first one, 'winclose 1' will close the second one. This is useful to have a button close the one of the defined windows, usually the current one.

winshow {window_index}

(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

hide

xy {x} {y}

Sets absolute x/y positions for the lower left corner of the widget. Does not affect xysize (eg. doesn't affect width or height).

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

Align Table

type {value}

Sets the type of box. See the

Box Type Table

color {value}

Sets the background color of the box, according to this

Color Map Chart

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

boxaround {x} {y}

Causes the box to adjust itself to the text string set by 'name "text"'.

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}

Sets the font used by name. See this

Font Table

labeltype {val}

See this

Label Type Table

labelsize {val}

Sets the size of the font used by name in pixels. Or maybe it's points. Whatever. Be happy you can see text at all.

labelcolor {val}

Sets the background color of the 'name "text"' string, according to this

Color Map Chart

help { multiline text }

Defines help text for this input field. When help is defined, a "?" button appears to the left of the input field. If the user hits it, the 'multiline text' is displayed to the user.

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

	help
	{
	    This is a test.
	    So is this
	}

helpfontface {val}

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

font table

helpfontsize {val}

Sets the size of the font used in help popups.

xy {x} {y}

Sets absolute x/y positions for the lower left corner of the box. Does not affect xysize (eg. doesn't affect width or height).

xysize {w} {h}

Sets the initial size (width and height) of the box. If unspecified, the box default size is 200x20 for no good reason. Does not affect the current 'default' position of the box.

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

Align Table

type {value}

Sets the type of chooser. Um, I'm not sure what these values do in this context. Try it and see.

color {value}

Sets the background color of the chooser according to this

Color Map Chart

labelfont {val}

Sets the font used by name. See this

Font Table

labeltype {val}

See this

Label Type Table

labelsize {val}

Sets the size of the font used by name in pixels. Or maybe it's points. Whatever. Be happy you can see text at all.

labelcolor {val}

Sets the background color of the 'name "text"' string, according to this

Color Map Chart

apphelp on

Creates a help button that links to the global

AppHelp

help { multiline text }

Defines help text for this input field. When help is defined, a "?" button appears to the left of the input field. If the user hits it, the 'multiline text' is displayed to the user.

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

	help
	{
	    This is a test.
	    So is this
	}

helpfontface {val}

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

font table

helpfontsize {val}

Sets the size of the font used in help popups.

xy {x} {y}

Sets absolute x/y positions for the lower left corner of the chooser. Does not affect xysize (eg. doesn't affect width or height).

xysize {w} {h}

Sets the initial size (width and height) of the chooser. If unspecified, the chooser default size is 200x20 for no good reason. Does not affect the current 'default' position of the chooser.

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"

Sets the 'database name' for the chooser. This name will appear in the temporary file created which contains key/value pairs; the 'key' will be the dbname specified here, the value will be the text entered in the input widget.

Submit

apphelp on

Creates a help button that links to the global

AppHelp

apphelp
{
   ..html text..
}

Defines html help documentation for the application. This text can be made available to the user in two ways;

If 'apphelp on' is defined for Submit, which creates a "Help" button the user can hit to jump to the top of the document.
If any input fields has 'apphelp on' defined, and no "help" defined. This will create a "?" button which the user can hit to jump into the document. The input field's "dbname" will be used as the link to jump to. So if the dbname for the field is XXX, the HTML document should contain <A NAME="XXX"> for the help button to link to the HTML text properly.

XY

When a widget is defined, it automatically increments the 'Y' value so that the next defined widget will appear directly below it, with 3 pixels of space in between.

XYSize

If a widget defines its own xysize, the global xysize is unaffected.

Positioning

Color Map

color

Font Table

labelfont

Value	Font Face
0	Helvetica
1	Helvetica Bold
2	Helvetica Italic
3	Helvetica Bold/Italic

4	Courier
5	Courier Bold
6	Courier Italic
7	Courier Bold/Italic

8	Times
9	Times Bold
10	Times Italic
11	Times Bold/Italic

12	Symbol
13	Screen
14	Screen Bold
15	Dingbats

Align Table

align

Value	Description
0	Center
1	Top
2	Bottom
4	Left
8	Right
16	Inside
32	Unused
64	Clip
128	Wrap

Label Type Table

Value	Description
0	FL_NORMAL_LABEL
1	FL_NO_LABEL
2	_FL_SYMBOL_LABEL
3	_FL_SHADOW_LABEL
4	_FL_ENGRAVED_LABEL
5	_FL_EMBOSSED_LABEL
6	_FL_BITMAP_LABEL
7	_FL_PIXMAP_LABEL
8	_FL_IMAGE_LABEL
9	_FL_MULTI_LABEL

Box Type Table

Value	Description
0	FL_NO_BOX
1	FL_FLAT_BOX
2	FL_UP_BOX
3	FL_DOWN_BOX
4	FL_UP_FRAME
5	FL_DOWN_FRAME
6	FL_THIN_UP_BOX
7	FL_THIN_DOWN_BOX
8	FL_THIN_UP_FRAME
9	FL_THIN_DOWN_FRAME
10	FL_ENGRAVED_BOX
11	FL_EMBOSSED_BOX
12	FL_ENGRAVED_FRAME
13	FL_EMBOSSED_FRAME
14	FL_BORDER_BOX
15	_FL_SHADOW_BOX
16	FL_BORDER_FRAME
17	_FL_SHADOW_FRAME
18	_FL_ROUNDED_BOX
19	_FL_RSHADOW_BOX
20	_FL_ROUNDED_FRAME
21	_FL_RFLAT_BOX
22	_FL_ROUND_UP_BOX
23	_FL_ROUND_DOWN_BOX
24	_FL_DIAMOND_UP_BOX
25	_FL_DIAMOND_DOWN_BOX
26	_FL_OVAL_BOX
27	_FL_OSHADOW_BOX
28	_FL_OVAL_FRAME
29	_FL_OFLAT_BOX

Input GUI Commands

Window

color {cval}

hide {val}

menubar

name "text"

resizable

scroll

saveid "string"

xysize {xval} {yval}

HelpFor

InputString

InputFilename

InputMultiline

Input

name "text"

dbname "text"

filebrowser {yes|no}

apphelp on

help { multiline text }

default "text"

multiline

align {val}

labelfont {val}

labelsize {val}

helpfontface {val}

helpfontsize {val}

xy {x} {y}

xysize {w} {h}

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

color {val}

Button

name "text"

labelcolor {val}

labelfont {val}

labelsize {val}

color {val}

command "the_command"

updatecommand "the_command"

system "the_command"

systemflags "flags"

winhide {window_index}

winshow {window_index}

xy {x} {y}

xysize {w} {h}

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

Boxes

name "text"

align {value}

type {value}

color {value}

boxaround {x} {y}

labelfont {val}

labeltype {val}

labelsize {val}

labelcolor {val}

help { multiline text }

helpfontface {val}

helpfontsize {val}

xy {x} {y}

xysize {w} {h}

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

Choice

name "text"

align {value}

type {value}

color {value}

labelfont {val}

labeltype {val}

labelsize {val}

labelcolor {val}

apphelp on

help { multiline text }

helpfontface {val}

helpfontsize {val}

xy {x} {y}

xysize {w} {h}

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

option "text"

default "text"