Tag 030 - Virtual Keyboard
Simplify supports a Virtual Keyboard Message on touch screen devices. This message displays up to three lines of text together with a virtual keyboard.
If the customer presses the Enter key, any text entered on the virtual keyboard is returned in the Virtual Keyboard Response.
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:
|
| FS | 1 | Field separator (Hex 1C) |
| Mask | Var. | See below. |
| FS | 1 | Field separator (Hex 1C) |
| UserChar | Var. | Set allowable characters for the keyboard for Mask = /u or /U, else blank |
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).
WARNING: If the default charset is UTF8 and if you pass a non-UTF8 string all non-utf8 characters are 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 ‘/’
The character ‘|’ marks the beginning of the user character definition, it calls GL_Widget_SetUserChar or ingenico::graphics::Widget::setUserChar. You can also use these functions to define the user characters.
Examples of masks:
The mask “0x/x/x/x/x” accept strings containing a decimal number coded on 4 hex digits preceded by “0x”
The mask “/u/u/u/u|1234” accept strings containing all characters from 1 to 4
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.
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. The buttons in the lower left corner provide access to virtual keyboards for entering alphabetic and other characters.
| API Field #, Value | Description |
|---|---|
| 0001,36 | Transaction Type |
| 0011,14124030000 | User Data. See Field 0011 (User Data). |
| 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
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 |
Response
| API Field #, Value | Description |
|---|---|
| 0001,36 | Transaction Type |
| 0011,14124030000?V102.18B01803 | User Data. See Field 0011 (User Data). |
| 5001,030019777FStest@elavon.com | Non-financial Data
|