ReadNum

Description:              This function returns a number read in from the keyboard.

Returns:                    Numeric

Usage:                       Steady State

Format:                      ReadNum(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 number on the screen.

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

                                      Any numeric expression giving the Y screen coordinate of the lower left corner of the number 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 of 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 numeric data from the keyboard. The keys typed are displayed on the screen. Once the enter key is hit and the number entered is 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 the number entered is invalid, the characters will be erased and the number may be entered again. 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.

                             This function is also reset by appearing in a true action trigger or as a parameter of a function which resets its parameters, such as Latch, Toggle or Save.

Example:

setPt = ReadNum(10, 10 { X-Y coordinates },

                14, 4 { Yellow foreground, red background }, 

                0 { Use small text }, 

                0 { No rotation }); 

When this statement becomes active, a prompt will appear on the screen at (10, 10). Any numbers 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, setPt 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 a number more than once from a screen, it is the usual practice to create a parameterized module with 2 or more states with the ReadNum function in one state. Rather than use ReadNum directly on a graphics screen, the parameterized module is used. Then the parameterized module may restart the ReadNum function without having to restart the entire graphics screen.

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

See Also:

Keys | MatchKeys | ReadText | ZEditField