getkbd_entry()
Provides display and keyboard entry functions for a variety of input applications. This function combines the display, delay, key detection, data input, and data validation routines.
Prototype #include <aclconio.h>
int getkbd_entry(int h_clock, char *msg, char *outbuf, unsigned wait, unsigned type, char szKeyMap[][CHAR_PER_KEY],
int KeyMapSize, int va_alist, ...);
Parameters
h_clock Clock device handle.
msg Message to display.
outbuf Where to hold the return data. wait Wait time, in 10-ms increments.
type Type of data entry desired, valid values are: • NUMERIC
• ALPHANUM
• NUMERIC|PASSWORD
• ALPHANUM|PASSWORD
• AMOUNT
• KEYMAP long va_alist
Variable arguments that depend on type:
• If type is NUMERIC, ALPHANUM, NUMERIC| PASSWORD or
ALPHANUM_PASSWORD:
getkbd_entry(h_clock, msg, out_buf, wait, type, char SzKeyMap[][CHAR_PER_KEY], int KeyMapSize, int max, int min),
int max maximum number of digits (max= 9) int min minimum number of digits (min=0) • If type is KEYMAP:
getkbd_entry(h_clock, msg, out_buf, wait, type, SzKeyMap, KeyMapSize, err_wait, err_msg, keys) int err_wait = length of time to display err_msg, in half- second increments.
char *err_msg = error message displayed for invalid entries long keys bitmap of the keys that can be entered.
• If type is AMOUNT:
getkbd_entry(h_clock, msg, out_buf, wait, type, szKeyMap[][CHAR_PER_KEY], KeyMapSize, frac, max, min) long max = maximum value allowed.
long min = minimum value allowed.
FUNCTION CALLS getkbd_entry()
Return Values
The display capability of this function uses prompt() to display an optional
message for n number of 10-ms increments, as specified by the wait parameter. During this display time, any keypress terminates the display and begins the data entry. Should the user fail to enter the data during the display period, the function
szKeyMap [] {CHAR_PER_KEY]
Key map specifying the mapping of the logical alphanumeric keys to the physical keys on the keypad.
char szKeyMap[MAX_ALPNUM_KEYS][CHAR_PER_KEY]= {"0- +%", "1QZ.\\", "2ABC&", "3DEF%", "4GHI*", "5JKL/", "6MNO~", "7PRS^", "8TUV[", "9WXY]", "*,'\":", "#=:$?" };
For Vx680 terminal, the key map specifying the mapping of the
logical alphanumeric keys to the physical keys on the keypad is: char szKeyMap[MAX_ALPNUM_KEYS][CHAR_PER_KEY_VX680]= {"0- +%", "1QZqz.\\", "2ABCabc&", "3DEFdef%", "4GHIghi*", "5JKLjkl/", "6MNOmno~", "7PRSprs^", "8TUVtuv[", "9WXYwxy]", "*,'\":", "#=:$?" }
By default, in the Verix eVo ACT library, CHAR_PER_KEY is defined as 6 and for Vx680 terminals, the
CHAR_PER_KEY_VX680 is defined as 8. Hence the application can have five chars per key in the key-mapping array. User can modify this value by calling set_chars_per_key_value(). Based on the value set by the user, the szKeyMap array should be passed to the library APIs. There is no validation done on the array size by the library.
KeyMapSize Size of the specified key map.
va_alist One or more null-terminated strings to concatenate. The argument list is null-terminated (defined in STDIO.H).
Success: > 0: Length of string stored in out_buf. Failure: 0: Time out occurred.
-1: Device read error. -2: Parameter out of range.
-3: clear key pressed (not provided for mapped entry type). -4: Invalid entry type specified.
-5: User pressed enter key when null data entry is permitted.
NOTE All five input parameters are required. No parameter can be omitted from any call. The prompt can be suppressed by supplying a null message parameter.
FUNCTION CALLS getkbd_entry()
ends and returns zero. If the data entry fails, the content of the output buffer is unchanged. If an out-of-range amount is entered, getkbd_entry() beeps and an invalid value remains displayed. The user can edit the entry using the backspace key. All data is returned as a null-terminated string.
Data entry can be divided into three categories: standard entry, mapped key entry, and amount entry. The data entry category is specified by the type parameter and determines the syntax of the getkbd_entry() call. #defines for the type options are supplied in ACLCONIO.H.
Standard Mode Data
Standard mode data entry is selected when type is NUMERIC, ALPHANUM, NUMERIC|PASSWORD, and ALPHANUM|PASSWORD.
This mode entry is suitable for entering account numbers, expiration dates, passwords, sequence numbers, and so on.
Standard entry options permit ALPHANUM and NUMERIC data entry in either clear mode—where each character is echoed to the screen as it is entered—or
PASSWORD mode—where an asterisk (*) character is written to the screen for each character entered at the keyboard. This option uses SVC_KEY_TXT().
Password type selection is accomplished by ORing either the ALPHANUM or NUMERIC options with the PASSWORD option. If the min parameter is zero, null data entry is permitted and the user can only press the enter key. If the min parameter is not zero and the user presses the enter key, getkbd_entry() error beeps and starts another data entry time out.
Cell Phone Mode
The cell phone mode is specific to Vx680 terminals. This feature enables the user
to key in the alpha numeric text without using the alpha keys, which are
traditionally used in other terminals. Each key has the corresponding key value and alphabets. The user can click once to display the numeric value and click twice, thrice and four times to display capital letter of the respective keys. Fifth, sixth and seventh click displays those respective keys in small letters. The ninth click will display the special character. Refer to the getkbd_entry()API for
more details on key mapping. NOTE
If the value of outbuf is F1-F4 or ALPHA key, a blank pixel is displayed when printed on the screen.
FUNCTION CALLS getkbd_entry()
The time out value for displaying the character simultaneously is set by
#KEY_TIMER environmental variable. If the value of the environmental variable is greater than 20, then the variable value is set as 20. If the value of the
environmental variable is less than 0, then 2 is set as the default value.
Mapped Key Entry
Mapped key entry accepts a bitmapped long integer indicating the valid keys for the entry. This is useful to prompt the user with a display and restricting input to a limited number of keystrokes, such as Y/N entries.
The key map is created by ORing the values of the valid keys. #defines are provided in ACLCONIO.H for all standard Verix eVo terminal keys, as well as the screen-addressable keys.
Mapped key entry returns after the time out specified expires or a key contained in the key map is entered. A single key is accepted and its null-terminated value is placed in the output buffer.
Mapped key entry also accepts an error message and error display time. If an error message is supplied, a prompt message should also be provided. The error message is displayed for the specified number of half seconds after any invalid keypress. If data entry starts while the error message is displayed, the routine immediately reads and processes the new input. If no entry occurs during the error message display, the prompt message redisplays. This display restarts the time out, providing another timed entry period. The error message can also provide a secondary prompt, such as:
PromptMsg = ABORT TRANS? Error Msg = 9= YES OR 6= NO
The following table lists the defines for the individual key definitions. NOTE
Cell phone mode for keying in characters is supported only in Vx680 terminal.
Table 15 Key Definitions
Key Define [0] KM_0 [1] KM_1 [2] KM_2 [3] KM_3 [4] KM_4 [5] KM_5 [6] KM_6 [7] KM_7 [8] KM_8 [9] KM_9
FUNCTION CALLS getkbd_entry()
Amount Mode Data
The entry amount is selected by AMOUNT type. Amount entry uses
SVC_KEY_NUM() to accept numeric entries suitable for use in monetary- formatted amounts. SVC_KEY_NUM() restricts the maximum number of input characters to 15, and the maximum number of decimal places to 10. This routine further restricts input to those values that can be represented by a signed long value (-2147483648 to 2147483648), including decimal places. For example, 1000000 may represent:
•
$1,000,000: 0 decimal places•
$100,000.0: 1 decimal place•
$1.000000: 6 decimal placesPositive and negative values are permitted. The alpha key (if present) can toggle a “-” sign at the beginning of the data input. No checks are provided and
overrange conditions are undefined.
[*] KM_STR [#] KM_PND [CANCEL] KM_ESC [CLEAR] KM_CLR [BACKSPACE] KM_BS [ALPHA] KM_AL [FUNC/ ENTER] KM_CR
[a] KM_a: leftmost screen-addressable key
[b] KM_b: second from the left screen-addressable key [c] KM_c: third from the left screen-addressable key
[d] KM_d: fourth from the left screen-addressable key (additional screen-addressable keys)
[e] KM_e: fifth screen-addressable key [f] KM_f: sixth screen-addressable key [g] KM_g: seventh screen-addressable key [h] KM_h: eighth screen-addressable key [f0] KM_f0:ninth screen-addressable key [f5] KM_f5:tenth screen-addressable key
All keys KM_ALL
No keys KM_NONE
Up Arrow key KM_DOWN
Down Arrow key KM_UP
Table 15 Key Definitions (continued)
FUNCTION CALLS getkbd_entry()
The frac parameter allows the user to specify the number of decimal places included in formatting the input. max and min parameters must provide enough digits to permit the use of a specified number of decimal places. This is useful in international monetary environments and in applications using tax tables, gasoline prices, and so on.
When specifying negative max or min parameters, it is not possible to specify a negative value between 0 and -1. This is due to the inability to preserve leading zeros.
Formatting the amount on the display can be controlled by ORing any of the following values with the AMOUNT in the type parameter:
•
RDXPSEPN radix decimal point and no separator: 1000000.00•
RDXPSEPC radix decimal point and comma separator: 1,000,000.00•
RDXCSEPN radix comma no separator: 1000000,00•
RDXCSEPP radix comma and decimal point separator: 1.000.000,00 If a format is not specified in the type, RDXSEPN is the default.Example getkbd_entry(h_clock, msg, output, 100, AMOUNT| RDXPSEPC,
szKeyMap[][CHAR_PER_KEY], KeyMapSize, 2, 100000L, 100L);
Displays msg for up to one second using the amount input, a decimal point as radix, and a comma separator using two decimal places with 1,000.00, as the maximum value, and 1.00 as the minimum value.
Example char szKeyMap[MAX_ALPNUM_KEYS][CHAR_PER_KEY]= {"0- +%", "1QZ.\\",
"2ABC&", "3DEF%", "4GHI*", "5JKL/", "6MNO~", "7PRS^", "8TUV[", "9WXY]", "*,'\":", "#=:$?" };
Dependencies Verix eVo SDK
ACL prompt(), ctons1(), keyin_mapped(), ERR_BEEP(), keyin_amt_range(),
set_chars_per_key_value()
A user entering mapped type data with a map passed with no bits set “on” (1), is unable to register any keypress. The routine continues to loop each time a user presses a key, and returns when the time out expires.
szKeyMap [] {CHAR_PER_KEY] The key map specifying the mapping of the logical alphanumeric keys to the physical keys on the keypad.
KeyMapSize Size of the specified key map.
NOTE Only limited parameter verification is performed. If the wait parameter is zero, no time-out value is used. For AMOUNT type entry, max cannot be less than min and frac cannot be larger than the number of characters required to represent the larger of max or min. For AMOUNT type, values between zero and minus one cannot be specified, such as, 001 with a fractional value of 2.
FUNCTION CALLS getxy()
For mapped key entry, if an error message is specified but the error time parameter is zero, the message displays briefly and is then overwritten by the prompt (if provided).
See Also prompt(), prompt_at(), display(), display_at(), keyin_mapped(), keyin_amt_range() Example The linked example code file demonstrates use of getkbd_entry(). Also see the
EXTRANS.C example program.
getxy()
Returns the x and y coordinate values of the cursor relative to the current window. The upper-left corner of the window is position 1,1. The x and y values provided by this function can be used in a gotoxy() call to correctly position the cursor within a window. This function differs from wherecur(), which returns the physical position of the cursor. For example, if a window is defined using the coordinates 3,1, 10,1 and the cursor is in the “home” position, getxy() returns 1,1, and wherecur() returns 3,1.
Prototype #include <aclconio.h>
int getxy(unsigned *x, unsigned *y);
Parameters
Return Values
Dependencies Verix eVo SDK
See Also window(), gotoxy(), wherecur()
Example The linked example code file demonstrates use of getxy().
x x coordinate.
y y coordinate.
Success: 0: Success.
Failure: -1: The current cursor position is outside the boundaries of the current window.
FUNCTION CALLS