Command @...GET | Xbase++ | Alaska Software

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>]

<nRow>

<nRow> is a numeric value specifying the row position where the values of <SayExpr> and the Get object are displayed.

<nCol>

<nCol> is a numeric value specifying the column position at which the values of <SayExpr> and the Get object (the contents of the entry field) are displayed. When the option SAY is included, the value of <SayExpr> is displayed in front of the Get object. If the option SAY is not included, the Get object is displayed at the position <nCol>.

<SayExpr> is an expression of any data type except object which is output at the coordinates <nRow> and <nCol> in front of the display of the entry field. When a PICTURE clause is attached to the SAY, the value of <SayExpr> is formatted according to the picture format <cSayPicture>.

<cSayPicture> is a character string containing a picture format. This optional argument determines the formatting for output of <SayExpr> (see below).

<cSayColor>, the first of two @...GET color options, is a character string specifying the color used to display <SayExpr>.

<VarName> is the name of the variable whose value is to be displayed and edited using the Get object. The variable <VarName>can belong to any storage class. If the storage class is ambiguous, by default the variable is associated with the storage class FIELD (field variable). When <VarName> references an array, the index operator [] and the numeric indexes (pointers) identifying the array element must also be specified. The value of <VarName> can only be of character, date, numeric or logical data type. Other data types cannot be edited with @...GET.

<cGetPicture> is a character string specifying formatting options for the value of <VarName> during display and editing.

<cGetColor>, the second of the two @...GET color options, is a character string containing two color values. The first color value specifies the color for the Get object when it is displayed and does not have input focus. The second color value specifies the color during editing. In other words, this second color is used to display the value of <VarName> while the Get object has input focus. If <cGetColor> contains only a single color value, this color is used for display and during editing. When the option is not included, the system color setting defined with SetColor() is used.

<blPreValid> is an optional condition tested during the READ command, before a Get object receives input focus (before it is activated). When the condition returns the value .T. (true), the Get object receives the input focus. Otherwise, it is skipped. <blPreValid> can also specify a code block that must return a logical value when evaluated. The Get object is passed to the code block prior to the Get object receiving input focus.

<blPostValid> is an optional condition tested during the READ command before a Get object loses input focus (before it is deactivated). When the condition returns the value .T. (true), the Get object loses the input focus. Otherwise, it remains active. <blPostValid> can also specify a code block returning a logical value. The Get object is passed to the code block prior to the Get object losing input focus.

<dnMinValue> specifies the smallest valid value for the variable <VarName> and is only significant for numeric or date values. Before the Get object loses input focus during the command READ, its current value is compared to<dnMinValue>. If the value is less than <dnMinValue>, the Get object retains input focus.

<dnMaxValue> specifies the greatest valid value for the variable <VarName> and is only significant with numeric or date values. Before the Get object loses the input focus during the command READ, its current value is compared to <dnMaxValue>. If the value is greater than <dnMaxValue>, the Get object retains the input focus.

<message> differs from ordinary parameters. <message> is a message sent to the Get object after it has been created. This parameter is often used to set a user defined Get reader for the default Get system. See the function GetReader().

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
The formatting of Y (Yes) or J (Ja) is country specific

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.

@...GET


// In the example, various variables are initialized. 
// They can be edited by Get objects created with 
// different options. 

PROCEDURE Main 
   LOCAL cString := "Xbase++" 
   LOCAL dDate   := Date() 
   LOCAL lBoolean:= .F. 
   LOCAL nNumber := 11123.45 
   LOCAL cText   := "A very long character string" 

   @ 2, 2 SAY "Character  :" GET cString 
   @ 3, 2 SAY "Date value :" GET dDate ; 
                           RANGE Date(),Date()+365 

   @ 4, 2 SAY "Boolean    :" GET lBoolean ; 
                         PICTURE "Y" 

   @ 5, 2 SAY "Number     :" GET nNumber ; 
                            WHEN lBoolean ; 
                           VALID nNumber > 1000 

   @ 6, 2 SAY "Scroll     :" GET cText ; 
                           COLOR "N/BG,W+/B" ; 
                         PICTURE "@S10" 
   READ 

RETURN

@...GET using VALID code block

// In the example, a code block which passes the Get 
// object to a function is specified using the VALID 
// option. In this function, a value is assigned 
// to the variable using the method :varPut() and can then 
// be edited from the Get object. 

PROCEDURE Main 
   LOCAL GetList := {} 
   LOCAL cString := Space(12) 

   @ 10, 10 SAY "Character value:" GET cString ; 
                             VALID {|oGet| DefaultValue(oGet) } 
   READ 
RETURN 

FUNCTION DefaultValue( oGet ) 

   IF Empty( oGet:Buffer )           // edit buffer is empty 
      oGet:varPut( "Default value" ) // assign default value 
   ENDIF 

RETURN .T.                           // validation is .T. (true)

@...GET using field variables

// In the example, two Get objects are created which edit 
// data from different work areas 

PROCEDURE Main 

   USE Customer ALIAS Cust NEW 
   APPEND BLANK 

   USE Invoice ALIAS Inv NEW 
   APPEND BLANK 

   @ 10,10 SAY "CustomerNo:" GET Cust->CustomerNo 
   @ 11,10 SAY " InvoiceNo:" GET Inv->InvNo 
   READ 

   CLOSE DATABASES 
RETURN

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.

Command @...GET Foundation