Command @...GET Foundation
Creates a Get object (entry field) and displays it on the screen.
@ <nRow>, <nCol> ;
[SAY <SayExpr> [PICTURE <cSayPicture>] [COLOR <cSayColor>]] ;
GET <VarName> ;
[PICTURE <cGetPicture>] ;
[COLOR <cGetColor>] ;
[WHEN <blPreValid>] ;
[VALID <blPostValid>] | [RANGE <dnMinValue>, <dnMaxValue>] ;
[SEND <message>]
The command @...GET creates a new Get object and displays the value of the variable <VarName> which can be edited later using the Get object. The Get object is added to the GetList array which is referenced by the variable GetList. If no such variable is declared, the Get object is added to the array in the PUBLIC variable GetList. The command READ activates the edit mode for all Get objects found in the GetList array. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the READ command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released.
Display with @...GET
The screen display starts at the coordinates <nRow> and <nCol>. If the SAY option is included, <SayExpr> is output first followed by the entry field or the value of <VarName>. Between the last character of <SayExpr> and the first character of <VarName>, either a blank space (Chr(32)) or the delimiting character defined with SET DELIMITERS TO is output. If a character is specified using SET DELIMITERS TO, SET DELIMITERS must be set to ON for the delimiting character to be displayed.
The color of the display can be controlled by including color values for <cSayColor> and <cGetColor>. If no COLOR options are included, the colors are determined by the system color setting defined with SetColor() (which encompasses five different color values in all). The expression <SayExpr> is always displayed in the default color (first color value). The color for the value of <VarName> depends on the setting SET INTENSITY. If it is turned ON, the display of <VarName> occurs with the fifth color value (unselected Get fields) or with the second color value (highlighted) if no fifth color value is defined. If SET INTENSITY is turned OFF, the value of <Varname> is displayed in the default color (first color value). During execution of the READ command, the current entry field is displayed in the highlighted color (second color value).
If the PICTURE option is not included, the display of the entry field occurs using a default PICTURE format. Otherwise, the PICTURE format <cGetPicture> is used. It provides a character string used to format the value of <VarName> during display and input (when the Get object has the input focus). This character string (the PICTURE format) can consist of two parts: the formatting function and the formatting mask. The default format for PICTURE depends on the data type of the variable <VarName>.
Data type | PICTURE format |
---|---|
Character | Character string filled with "X" |
Numeric | Character string filled with "#" |
Logical | "L" |
Date | "99 99 99" |
The PICTURE formatting function
The formatting function always appears at the beginning of a PICTURE format and begins with the character @ (Chr(64)). One or more characters from the table below appear after this character. Each of the characters following the @ represent a specific formatting rule affecting how the value of<VarName> is displayed in the edit buffer of the Get object. A PICTURE format can consist of only one formatting function. A formatting mask can also be included to format individual characters in the edit buffer. If both are used, the formatting function must appear first and be separated from the formatting mask by a single blank space (Chr(32)).
Function | Data type | Formatting |
---|---|---|
A | C | Only letters are allowed |
B | N | Displays numbers left justified |
C | N | Displays CR (Credit) after positive numbers |
D | C | Displays character strings in SET DATE format |
K | CDLN | Deletes edit buffer when the first key is not a cursor key |
L<c> | N | Fills numeric values with the character <c> from the left |
R | C | Inserts unknown formatting characters into the display, but does not store in the variable |
S<n> | C | Horizontal scroll of entry field when the value is longer than <n>. <n> is an integer determining the width of the entry field. |
X | N | Displays DB (Debit) behind negative numbers |
Z | N | Displays only blank spaces when the value is 0 |
( | N | Displays negative numbers with leading blank spaces in parentheses |
) | N | Displays negative numbers without leading blank spaces in parentheses |
$ | N | Places the country specific currency character in front of a number |
! | C | Converts letter characters to upper case |
The formatting function @S allows editing of values with more characters than fit in the area being displayed on screen. The value <n>determines how many characters are displayed, or the width of the input field on the screen. The width of the edit buffer is either the length of the value <VarName> or, the number of characters in the PICTURE formatting mask.
The formatting function @L specifies a single character to use in filling numeric values from the left.
The formatting function @$ uses the currency character defined in the system country settings and places this character in front of numeric values.
The PICTURE formatting mask
The formatting mask is a character string whose individual characters define rules for formatting the individual characters of <VarName>during display and editing. The characters from the following table are interpreted as formatting characters. Every other character contained in the PICTURE mask is displayed at the corresponding position. When the PICTURE format contains the formatting function @R, these unknown formatting characters are merely inserted into the display, and not copied into the value of <VarName>. If @R is missing, these characters are also copied into <VarName> after editing. The formatting mask can be included along with the formatting function in the PICTURE format. If both are used, the formatting function must precede the formatting mask and they must be separated by a single blank space.
Character | Format |
---|---|
A | Only letter characters permitted |
L | Only T, F, J, Y or N permitted (for logical values) |
N | Only alphanumeric characters permitted |
X | Any character is permitted |
Y *) | Converts J, Y, T to Y or J other characters to N |
9 | Only digits and signs are permitted for numeric values |
! | Lower case letters are converted to upper case |
# | Digits, signed numbers and blank spaces are allowed |
$ | Leading blank spaces are displayed as a dollar sign ($) for numeric values |
* | Leading blank spaces are displayed as an asterisk (*) for numeric values |
, | Displays comma place |
. | Displays decimal point |
|
Editing with @...GET during READ
During editing, the value in the edit buffer of the Get object for the variable <VarName> is displayed as a character string which can be overwritten or changed by the user. Input characters are tested for validity depending on the original data type. For example, a letter character is recognized as invalid and is not copied into the edit buffer for numeric values. When the Get object loses input focus, a type conversion is performed on the contents of the edit buffer to provide a value with the original data type. This value is assigned to the variable <VarName>. The variable <VarName> can belong to any storage class (LOCAL, STATIC, PRIVATE, PUBLIC or a field variable). When an array is referenced in the variable, the array element operator must be included as well as the numeric indexes clearly identifying the array element. The Get object then edits the value in this array element.
The condition <blPreValid> can be specified using the option WHEN, either in the form of a logical expression or in the form of a code block returning a logical value. If this is specified, the Get object receives input focus during the READ command only when the expression <blPreValid> returns the value .T. (true). Otherwise, this Get object is skipped. If a code block is specified, the Get object is passed to it as an argument.
When either the option VALID or the option RANGE is included, data validation occurs when the user attempts to leave the entry field. This occurs just before the Get object loses the input focus. The condition specified in the VALID option can be a logical expression or a code block, just like the condition for the WHEN option. If a code block is specified, it is passed the Get object as an argument. The Get object only loses input focus when the expression or code block <blPostValid> returns the value .T. (true). When an upper and lower limit are defined for the input value using RANGE, the edited value must be within these limits. Otherwise, the Get object remains active and the cursor remains in the corresponding entry field.
If the option RANGE is used for data validation and an invalid value is input, a message appears in the SCOREBOARD area of the screen (uppermost screen row). A message also appears if an invalid date is input for a date value. The display of messages can be included or suppressed using the command SET SCOREBOARD ON | OFF.
Assignments using @...GET during READ
The value in the edit buffer of the current Get object is assigned to the variable <VarName> when the user attempts to leave the input field (see the command READ for information about navigation keys). The assignment occurs before VALID or RANGE conditions are tested. An assignment also occurs when a key or an event is tied to a code block (see SetKey(), SET KEY TO or SetAppEvent()). In a procedure called from such a code block, the variable <VarName> can be explicitly assigned a value if it is visible. This value is copied into the edit buffer of the current Get object after termination of the procedure.
If the user ends the editing procedure by pressing the Esc key, the original value is assigned to the variable <VarName>. Data validation using the expression defined in the VALID option is not performed and the READ command terminates. The ability of the Esc key to act as a termination key can be set using the command SET ESCAPE ON | OFF.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.