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 NameLengthDescription
TTT3Tag (always = 030)
LLL3Length of the following data
Title1Var.Title 1
FS1Field separator (Hex 1C)
Title2Var.Title 2
FS1Field separator (Hex 1C)
Title3Var.Title 3
FS1Field separator (Hex 1C)
Mode1Input Mode:
  • 0=Normal (display characters as entered)
  • 1=Password mode (characters are replaced by *)
FS1Field separator (Hex 1C)
MaskVar.See below.
FS1Field separator (Hex 1C)
UserCharVar.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 NameLengthDescription
TTT3Tag (always = 030)
LLL3Length of the following data
ActionButtonVar.If field 11 Completion Code = 000 (success), returns code for key pressed:
  • 777=Enter (green) key
  • 888=Cancel (red) key
FS1Field separator (Hex 1C)
DataVar.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 #, ValueDescription
0001,36Transaction Type
0011,14124030000User Data. See Field 0011 (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

Additional Request Samples (field 5001)

Value in Field 5001Screen Use
030049Enter AmountFSFSFS0 FS/d/d/d/d/d/d/d/d/d/d/D./D/D US$FSPrompt for dollar amount
030041Enter Date (YYMMDD)FSFSFS0FS/d/d///d/d///d/dFSPrompt for date
030039Enter Time (HHMMSS)FSFSFS0FS/d/d:/d/d:/d/dFSPrompt for time
030036Enter PasswordFSFSFS1FS/c/c/c/c/c/c/c/cFSPrompt for password

Response

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