Tag 030 - Virtual Keyboard
Simplify supports a Virtual Keyboard Message on touch screen devices. This message displays up to two lines of text at the top of the screen (Title1 field) together with a virtual keyboard.
Title fields should be used in order, starting with Title1. If this is insufficient, Title2 should be used for the additional text, and if necessary Title3. The maximum length of each Title field is 40 characters for the MX915 and 44 characters for the MX925. The maximum length of the formatted input (including any added literals) is 37 for the MX915 and 45 for the MX925.
If the Enter key is pressed, any text entered on the virtual keyboard is returned in the Virtual Keyboard Response.
Virtual Keyboard Message Format
Request
Field 5001
| Field Name | Length | Description |
|---|---|---|
| TTT | 3 | Tag (always = 030) |
| LLL | 3 | Length of the following data |
| Title1 | 0-40 (MX915) 0-44 (MX 925) |
Title 1 |
| FS | 1 | Field separator (Hex 1C) |
| Title2 | 0-40 (MX915) 0-44 (MX 925) |
Title 2 |
| FS | 1 | Field separator (Hex 1C) |
| Title3 | 0-40 (MX915) 0-44 (MX 925) |
Title 3 |
| FS | 1 | Field separator (Hex 1C) |
| Mode | 1 | Input Mode: 0=Normal (display characters as entered) 1=Password mode (characters are replaced by *) (not used) |
| FS | 1 | Field separator (Hex 1C) |
| FormatString | Var | See below. |
| FS | 1 | Field separator (Hex 1C) |
| DisplayString | Var | This is where the literals for the field display are set up. |
Format String
Each character in the FormatString field represents the valid input values for that position.
- C – Corresponding character is a literal, which may not be changed.
- N – Numeric value (0 – 9)
- A – Alpha character (A – Z)
- X– Any character
Display String
If literals are present in the FormatString field, the DisplayString field is used to set up the literals for the field display. The FormatString field determines the input format, regardless of what is in the display string. The format string and the display string (if used) need to be the same length, so the display string will automatically adjust to match the format string by padding with blanks or truncating the last field(s). Eg. (with blanks in the Display string represented as X's):
- Format string: CNNNCCNNNCNNNN
- Display string: (XXX)XXXX-XXXX
This will only allow numeric input, and preserve the literal formatting. The entire display string will be returned to the POS. If the literals are not desired, the POS will need to filter them out.
Response
Field 5001
| 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: 777=Enter (green) key 888=Cancel (red) key |
| FS | 1 | Field separator (Hex 1C) |
| Data | 0-37 (MX915) 0-45 (MX925 |
If ActionButton =777 (Enter), returns formatted input text (if any). |
Sample Virtual Keyboard Message
Request
The following request tells Simplify to display the screen shown below.
| API Field #, Value | Description |
|---|---|
| 0001,36 | Transaction Type |
| 0011,14124030000 | User Data. See Appendix F for the use of this field. |
| 5001, [see value below] | Non-Financial Data
|
5001,030044Enter Email AddressFSFSFS1FSXXXXXXXXXXXXXXXXXXXXFS
Response
| API Field #, Value | Description |
|---|---|
| 0001,36 | Transaction Type |
| 0011,14125020000?V142.18.65_2.18.1 | User Data. See Appendix F for the use of this field. |
| 5001,030019777FSTEST@ELAVON.COM | Non-Financial Data
|
Additional Samples (Request field 5001)
| Value in Field 5001 | Screen Use |
|---|---|
| 030041Enter Date (YYMMDD)FSFSFS0FSNNCNNCNNFSMM/DD/YY | Prompt for date |
| 030041Enter Time (HHMMSS)FSFSFS0FSNNCNNCNNFS : : | Prompt for time |