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 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 (Password Flag):
  • 0=Normal (display characters as entered)
  • 1=Password mode (characters are replaced by * in display)
FS1Field separator (Hex 1C)
MaskVar.Defines data types allowed as input and how input will be formatted. See further below.
FS1Field separator (Hex 1C)
UserCharVar.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 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. Buttons at the bottom of the screen (on the left) provide access to virtual keyboards for entering alphabetic and other characters.

API Field #, ValueDescription
0001,36Transaction Type
0011,xxx..User Data. See Simplify-Controlled Field Definitions.
5001,[see value below]Non-Financial Data
  • 030=Tag
  • 057=Length of data
  • Enter Email Address=Title1
  • 0=Normal input mode (input displayed)
  • /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 #, ValueDescription
0001,36Transaction Type
0011,xxx..User Data. See Simplify-Controlled Field Definitions.
5001,030019777FStest@elavon.comNon-financial Data
  • 030=Tag
  • 019=Length of data
  • 777=Enter key pressed
  • test@elavon.com=User input
5002,80378002Device serial number (if present)

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