Edit

(System Library)

Description: This module draws an edit field with (optional) title and/or bevel.

Returns: Nothing

Usage: Steady State

Format: \System\Edit(X1, Y1, X2, Y2, Title, Variable [, FocusID, Trigger, View, DataType, DrawBevel, VertAlign, AlignTitle, LowLimit, HighLimit, Style, PrefixValue, SuffixValue])

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

Any numeric expression giving the X coordinate on the screen of one side of the edit field.

Y1 { numeric } { required } { no default }

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

X2 { numeric } { required } { no default }

Any numeric expression giving the X coordinate on the screen of the side of the edit field 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 edit field, whichever is the opposite of Y1.

Title { text } { required } { no default }

Any text expression to be used as a title for the field.

Variable { text } { required } { no default }

A variable whose value is set by the edit field.

FocusID { numeric } { optional } { no default }

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

Trigger { numeric } { optional } { no default }

A parameter whose value is derived from ZEditField and can therefore be set to "0" (internal buffer changed), "1" ("Enter" key pressed), or "2" (focus lost). If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.

View { numeric } { optional } { default: varies – see note }

An optional parameter indicating how to display the edit field, as follows:

View	Display Mode
0	Invisible
1	Normal (color scheme - no graying)
2	Grayed-out (only if FocusID is 0)

This parameter may be used to force an edit field with a FocusID of 0 to be displayed normally, rather than allowing it to default to its grayed color. Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out. The default value is 2 if FocusID is 0 and 1 otherwise.

DataType { numeric } { optional } { default: 4 }

An optional parameter that is any numeric expression giving the type of data accepted by the edit field as follows:

DataType	Description
0	Byte (unsigned)
1	Short (2 byte signed)
2	Long (4 byte signed)
3	Double precision floating point (8 byte signed)
4	Text
5	Octal (4 byte unsigned)
6	Hexadecimal (4 byte unsigned)

For types 0 - 2, if the number entered into the field is prefaced by a "0x" the value is taken to be hexadecimal format, and if it is prefaced by a "0" it is considered to be octal. In either case, the value is converted to decimal format when return is pressed or the focus is lost.

For type 5, regardless of whether or not the number entered into the field is prefaced by a "0" the value is taken to be octal and will be displayed as such. The actual type of Variable will be text.

Type 6, like type 5 will be kept in its declared format of hexadecimal regardless of whether or not the number entered into the field is prefaced by a "0x". The actual type of Variable will be text

The default value is 4 - text.

DrawBevel { Boolean } { optional } { default: false }

An optional parameter that is any logical expression; if true (non-0) a bevel is drawn around the edit field, if false (0) no bevel is drawn. If the edit field is beveled, its size will become fixed and will be the same as that for a droplist. The default value is false.

VertAlign { numeric } { optional } { default: 0 }

An optional parameter that is any numeric expression that sets the vertical alignment of the edit field according to one of the following options:

VertAlign	Vertical Alignment
0	Top
1	Center
2	Bottom

Whether or not the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle { Boolean } { optional } { default: true }

An optional parameter that is any logical expression; if true (non-0) the title is included in the calculation for vertical alignment, if false(0) it is added to the edit field after it (and its bevel if one exists) has been vertically aligned. The default is true.

LowLimit { numeric } { optional } { no default: }

An optional parameter that is any expression giving the minimum value or minimum number of characters to be accepted by the edit field (depending on the data type). This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value less than LowLimit is entered in the field (or there are too few characters, in the case of text value), the variable set by the field will revert to the previous value.

HighLimit { numeric } { optional } { no default: }

An optional parameter that is any numeric expression giving the maximum value or maximum number of characters to be accepted by the edit field (depending on the data type). This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value greater than HighLimit is entered in the field (or there are too many characters, in the case of text value), the variable set by the field will revert to the previous value.

Style { numeric } { optional } { default: 0 }

Comprised of the arithmetic sum of the following fields, to yield the desired effects.

Bits 2^0 and 2^1 are reserved for bit compatibility with WinComboCtrl, and should be set to "0".

Bits 2^2 to 2^4 define input character handling. They can be set according to the following values:

Style	Definition
0	Input is passed to script code as typed.
4	Input is converted to all uppercase.
8	Input is converted to all lowercase.
16	Input is masked. Any characters typed will appear as asterisks. (useful for password fields)

Bits 2^5 controls multi-line edit controls.

Style	Definition
32	Multiline editing. Setting this bit causes a typed <CR> (Enter or Return) to be interpreted as "move to the start of the next line". Text that contains <CR> characters has a line break inserted at each <CR>.

Bits 2^6 and 2^8 are reserved.

Bit 2^9 defines and enables exact use of application-defined geometry. The default is to perform auto-geometry modification to give the best fit.

Style	Definition
512	Enable application-defined geometry.

PrefixValue { text } { optional } { no default: }

An optional parameter indicating the text expression that should be displayed immediately before (i.e. to the left of) the editable part of the control.

SuffixValue { numeric } { optional } { no default: }

An optional parameter indicating the text expression that should be displayed immediately after (i.e. to the right of) the editable part of the control.

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 height of the edit field is constant, with X1 and X2 defining its width, and Y1 and Y2 defining the boundaries in which it is to be confined vertically, which may or may not include the added height of a title and bevel, depending on the alignment used and if they exist.

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

Examples:

System\Edit(10, 50 { Top left corner - fixed },

VStatus(Self, 13) - 10, 20

{ Bottom right corner -

varies with window width },

"Description" { Title },

Desc { Var to update }

{ Remainder of parameters not used, so omitted });

System\Edit(20, 110, 120, 70 { Outline of field },

"Name", Name { Title; var to update },

2, DoneFlag { Focus ID, trigger },

Invalid { Default display },

2 { Long integer values },

Invalid { Default of no bevel },

1 { Center the editfield },

1 { Include title in alignment },

Invalid { No minimum value },

100 { Maximum acceptable value });