ReadText

Description:              This function returns text characters read in from the keyboard.

Returns:                    Text

Usage:                       Steady State

Format:                      ReadText(X, Y, Foreground, Background, Size, Rotation)

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

                                      Any numeric expression giving the X screen coordinate of the lower left corner of the text on the screen.

                                    Y  { numeric }  { required }  { no default: }

                                      Any numeric expression giving the Y screen coordinate of the lower left corner of the text on the screen.

                                    Foreground  { numeric }  { required }  { no default: }

                                      Any numeric expression giving the color of the characters to be displayed.

                                    Background  { numeric }  { required }  { no default: }

                                      Any numeric expression giving the color of the background area for the output characters.

                                    Size  { numeric }  { required }  { no default: }

                                      Any numeric expression giving the height of the characters in units of Y screen coordinates. If this value results in a specification of less than 12 screen pixels high, the text will be the small text (8 pixels high); otherwise, the text will be the large text. A Size less than 0 is invalid.

                                    Rotation  { numeric }  { required }  { no default: }

                                      Any numeric expression giving the orientation of the output. A value of 0 specifies normal left to right horizontal output. The number gives the multiples of 90 degree counterclockwise rotations for the output. For example, a value of 1 would have a vertical output reading from bottom to top. Only the portion of Rotation before the decimal point is significant.

Comments:               This function allows the operator to enter character data from the keyboard. The keys typed are displayed on the screen. Once the <enter> key is hit and the data are valid, keys are no longer accepted from the keyboard. The <backspace> key can be used to erase the last characters typed before the <enter> key is hit.

                             If any of the parameters are invalid, the function is reset and the input will start from the beginning again once the parameters become valid. The function is also reset by appearing in a true action trigger or as a parameter of a function which resets it parameters such as Latch, Toggle or Save.

Example:

batch = ReadText(10, 20 { X-Y coordinates },

                 1, 14 { Blue foreground, yellow background }, 

                 0 { Use small text }, 

                 0 { No rotation }); 

When this statement becomes active, a prompt will appear on the screen at (10, 20). Any characters typed on the keyboard will be displayed, and the prompt will advance from left to right. Since this is a destructive graphics statement, any underlying graphics will be destroyed. When the [ENTER] key is pressed, batch will be updated to the value entered. The statement is now done, and nothing further happens until the state stops and restarts, when this action is repeated.

Because it is normal to want to enter text more than once from a screen, it is the usual practice to create a parameterized module with 2 or more states with ReadText in one state. Rather than use ReadText directly on a graphics screen, the parameterized module is used. Then the parameterized module may restart the ReadText function without having to restart the entire graphics screen.

Don't activate more than one ReadText or ReadNum statement at a time - all keystrokes will appear in all active keyboard functions simultaneously.

See Also:

Keys | MatchKeys | ReadNum | ZEditField