Spinbox

(System Library)

Description: This module draws a spinbox with (optional) label.

Returns: Nothing

Usage: Steady State

Format: \System\Spinbox(X1, Y1, X2, Y2, Variable, Label, BoxOnLeft, Alignment, NumChars, LowLimit, HighLimit [, CanEdit, FocusID, TextOption, TextValue, Trigger])

Parameters: X1 { numeric } { required } { no default: }

Any numeric expression giving the X coordinate on the screen of one side of the spinbox and its label.

Y1 { numeric } { required } { no default: }

Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the spinbox.

X2 { numeric } { required } { no default: }

Any numeric expression giving the X coordinate on the screen of the side of the spinbox and its label opposite to X1.

Y2 { numeric } { required } { no default: }

Any numeric expression giving the Y coordinate on the screen of the top or bottom of the spinbox, whichever is the opposite to Y1.

Variable { Variable } { required } { no default: }

The variable whose value is set by the spinbox.

Label { text } { required } { no default: }

Any text expression to be used as a label with the spinbox.

BoxOnLeft { Boolean } { required } { no default: }

Any logical expression; if true (non-0) the spinbox will appear to the left of the label, if false (0) it will be to the right. If this value is invalid, a default value of true will be used.

Alignment { numeric } { required } { default: 0 }

Any numeric expression that sets the alignment of the spinbox and its label according to one of the following options:

Alignment	Horizontal	Vertical
0	Left	Top
1	Right	Top
2	Full	Top
3	Left	Centered
4	Right	Centered
5	Full	Centered
6	Left	Bottom
7	Right	Bottom
8	Full	Bottom

The default value is 0.

NumChars { numeric } { required } { no default: }

Any numeric expression that gives the number of digits wide to make the spinbox; a value of 0 or invalid results in the spinbox being automatically sized to fit the widest number (or text string if TextOption and TextValue are set).

LowLimit { numeric } { required } { no default: }

Any numeric expression giving the lowest permissible value. If the spinbox is editable and a value less than LowLimit is entered, it will revert to the LowLimit value.

HighLimit { numeric } { required } { no default: }

Any numeric expression giving the highest permissible value. If the spinbox is editable and a value greater than HighLimit is entered, it will revert to the HighLimit value.

CanEdit { Boolean } { optional } { default: false }

An optional parameter that is any logical expression; if true (non-0), the number in the field may be edited directly, if false (0), it may not. The default value is false.

Note that the value of this parameter directly affects the TextOption and TextValue parameters' effectiveness. If CanEdit is true, both are ignored.

FocusID { numeric } { optional } { default: 1 }

An optional parameter that is any numeric expression for the focus number of this graphic. If this value is 0, the spinbox will display its current setting, but the value will not be able to be set and the spinbox field will appear grayed out. The default value is 1.

If this parameter is omitted, keyboard input (such as the arrow keys) will be ignored.

TextOption { text } { optional } { no default: }

An optional parameter that is any text expression used to replace a certain value (expressed by TextValue) in the spinbox field. This parameter will be ignored if CanEdit is true.

TextValue { text } { optional } { no default: }

An optional parameter that is any numeric expression for the value in the spinbox that is to be replaced by the text string in TextOption. This parameter will be ignored if CanEdit is true.

Trigger { numeric } { optional } { no default: }

An optional parameter that is a numeric expression. The value in Trigger will become 0 if the user changes the internal buffer (i.e. when the value of the WinEditCtrl as logged in the variable Change transits from invalid to zero). If the user presses any of Enter, the spin box arrows or the arrow buttons on the keyboard, Trigger becomes 1. If the spinbox loses focus, the value of Trigger becomes 2.

Comments: This module is a member of the System Library, and must therefore be prefaced by \System\, as shown in the "Format" section. If the application you are developing is a script application, the System variable must be declared in APPMOD.SRC and need not be prefaced by a backslash in the function call.

The size of the spinbox is constant, with X1, Y1and X2, Y2 defining the position of the checkbox and its label.

For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

The trigger parameter provides an indication that something has changed and therefore the user should be promted to save changes before exiting.

Example:

System\Spinbox(200, 70, 360, 30 { Location of spinbox },

Retries { Variable to change },

"Number of retries"{ Label },

Invalid { Defaults to box on left },

6 { Left, bottom align },

4 { Field width in chars },

0, 100 { Low, high limits },

0 { Not editable },

3 { Focus ID },

"None" { Text replacement },

0 { Use text in index 0 });