Tag 030 - Virtual Keyboard
Simplify supports a Virtual Keyboard message on touch screen devices. This message displays up to three lines of text, a virtual keyboard, and an input field showing formatted user input.
Mask and UserChar subfields of API 5001 in the request control how the input field is initialized, the data allowed for user input, and how the data will be formatted. See under Request for more information.
If the customer presses the Enter key, any text entered on the virtual keyboard is returned in API 5001 in the response, formatted as defined by the Mask (except no Input Mode masking).
Field 5001 Format
Request
| Field Name | Length | Description |
|---|---|---|
| TTT | 3 | Tag (always = 030) |
| LLL | 3 | Length of the following data |
| Title1 | Var. | Title 1 |
| FS | 1 | Field separator (Hex 1C) |
| Title2 | Var. | Title 2 |
| FS | 1 | Field separator (Hex 1C) |
| Title3 | Var. | Title 3 |
| FS | 1 | Field separator (Hex 1C) |
| Mode | 1 | Input Mode (Password Flag):
|
| FS | 1 | Field separator (Hex 1C) |
| Mask | Var. | Defines data types allowed as input and how input will be formatted. See further below. |
| FS | 1 | Field separator (Hex 1C) |
| UserChar | Var. | Defines characters allowed as input. Only supported for Masks containing ‘/u’ and/or ‘/U’; else blank. See further below. |
Mask
The mask is a string normal, the format characters are always preceded by ‘/’. The input mask can be set using GL_Widget_SetMask, GL_Widget_SetMaskById or ingenico::graphics::Widget::setMask
note
The default charset is UTF8, to change the charset use the function GL_GraphicLib_SetCharset or ingenico::graphics::GraphicLib::setCharset).
important
If the default charset is UTF8 and you pass a non-UTF8 string all non-UTF8 characters will be replaced by ‘?’.
For the following masks, the fill character is 1 (by default ’_’):
(GL_Widget_SetFillChar1 or ingenico::graphics::Widget::setFillChar1)
/b : accepts a character in binary
/o : accepts a character in octal
/d : accepts a character in decimal
/x : accepts a hexadecimal character
/a : accepts an alphanumeric character
/c : accepts any character
/u : accepts all characters in the range of allowed characters defined by the user
(GL_Widget_SetUserChar or ingenico::graphics::Widget::setUserChar)
For the following masks, the fill character is 2 (by default ‘0’):
(GL_Widget_SetFillChar2 or ingenico::graphics::Widget::setFillChar2)
/B : accepts a character in binary
/O : accepts a character in octal
/D : accepts a character in decimal
/X : accepts a hexadecimal character
/A : accepts an alphanumeric character
/C : accepts any character
/U : accepts all characters in the range of allowed characters defined by the user
(GL_Widget_SetUserChar or ingenico::graphics::Widget::setUserChar )
// : accepts the character ‘/’
Example: The mask “0x/x/x/x/x” accept strings containing a decimal number coded on 4 hex digits preceded by “0x”.
important
If a GL_Widget_SetText or ingenico::graphics::Widget::setText was done before it is not taken into account. Always specify the input mask before loading the default content of the field.
UserChar
User character definition. Defines characters allowed as input. Only supported for Masks containing ‘/u’ and/or ‘/U’, This subfield calls GL_Widget_SetUserChar or ingenico::graphics::Widget::setUserChar.
Example: the Mask plus UserChar “/u/u/u/u<FS>1234” accept strings containing all characters from 1 to 4.
Response
| Field Name | Length | Description |
|---|---|---|
| TTT | 3 | Tag (always = 030) |
| LLL | 3 | Length of the following data |
| ActionButton | Var. | If field 11 Completion Code = 000 (success), returns code for key pressed:
|
| FS | 1 | Field separator (Hex 1C) |
| Data | Var. | If ActionButton =777 (Enter), returns formatted input text (if any). |
Sample Message
Request
The following request tells Simplify to display the screen shown below. Buttons at the bottom of the screen (on the left) provide access to virtual keyboards for entering alphabetic and other characters.
| API Field #, Value | Description |
|---|---|
| 0001,36 | Transaction Type |
| 0011,xxx.. | User Data. See Simplify-Controlled Field Definitions. |
| 5001,[see value below] | Non-Financial Data
|
5001,030057Enter Email AddressFSFSFS0FS/c/c/c/c/c/c/c/c/c/c/c/c/c/c/c/cFS
Response
| API Field #, Value | Description |
|---|---|
| 0001,36 | Transaction Type |
| 0011,xxx.. | User Data. See Simplify-Controlled Field Definitions. |
| 5001,030019777FStest@elavon.com | Non-financial Data
|
| 5002,80378002 | Device serial number (if present) |
Additional Request Samples (field 5001)
| Value in Field 5001 | Screen Use |
|---|---|
| 030049Enter AmountFSFSFS0 FS/d/d/d/d/d/d/d/d/d/d/D./D/D US$FS | Prompt for dollar amount |
| 030041Enter Date (YYMMDD)FSFSFS0FS/d/d///d/d///d/dFS | Prompt for date |
| 030039Enter Time (HHMMSS)FSFSFS0FS/d/d:/d/d:/d/dFS | Prompt for time |
| 030036Enter PasswordFSFSFS1FS/c/c/c/c/c/c/c/cFS | Prompt for password |