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: 0=Normal (display characters as entered)
1=Password mode (characters are replaced by *)
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

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:
777=Enter (green) key 888=Cancel (red) key
FS 1 Field separator (Hex 1C)
Data Var. If ActionButton =777 (Enter), returns formatted input text (if any).

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

error_outline

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

WARNING : 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.

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 11 (User Data).
5001,[see value below] Non-Financial Data
    030=Tag
    057=Length of data
    Enter Email Address=Title1
    0=Input mode (not used)
    /c/c/c/c/c/c/c/c/c/c/c/c/c/c/c/c=Mask

5001,030057Enter Email AddressFSFSFS0FS/c/c/c/c/c/c/c/c/c/c/c/c/c/c/c/cFS

sample enter email screen

Response

API Field #, Value Description
0001,36 Transaction Type
0011,14124030000?V102.18B01803 User Data. See Field 11 (User Data).
5001,030019777FStest@elavon.com Non-financial Data
    030=Tag
    019=Length of data
    777=Enter key pressed
    test@elavon.com=User input

Additional 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