KeyPad

KeyPad is a built-in function that displays a Virtual Keyboard (for Thin Clients) or Data Input (for Mobile Access) dialog box in order to prompt the user to enter a value.

Syntax

KeyPad("strTagName",optStrKeyboardName,optNumIsPassword,optStrHint,optNumMin,optNumMax,optNumESign,optStrConfirmation,optRealFmtSpecifier)

KeyPad ( " strTagName " { | ,optStrKeyboardName { | ,optNumIsPassword { | ,optStrHint { | ,optNumMin,optNumMax { | ,optNumESign { | ,optStrConfirmation { | optRealFmtSpecifier} } } } } } } )

strTagName

The name of the project tag that will receive the entered value.

Note: If this parameter is enclosed in quotes, the string literal will be used. Otherwise, the value of the tag/expression will be used.

optStrKeyboardName

The type of Virtual Keyboard that will be displayed (for example, AlphaNumeric, EnhKeypad, or Keypad ).

This parameter is optional; if no value is specified, the default type (as selected in the project settings) will be displayed.

This parameter is ignored when the function is executed on Mobile Access.

optNumIsPassword

A numeric switch that will cause the characters typed by the user to be displayed as asterisks (*). This is useful when the user must enter a password or some other value that should be obfuscated. To set this switch TRUE, specify any value other than 0.

This parameter is optional; if no value is specified, the default value is 0 (FALSE).

optStrHint

A hint or message to the user that will be displayed at the top of the dialog box, if the Show Hint option is selected in the project settings.

This parameter is optional; if either an empty string ("") or no value is specified, no hint will be displayed.

optNumMin,optNumMax

The minimum and maximum values that will be accepted as input. These values will also be displayed as Min and Max hints in the dialog box, depending on how it is configured. For Thin Clients, the keyboard type must be Keypad and the Show MIN/MAX fields option must be selected in the project settings. (These parameters are ignored for all keyboard types other than Keypad.) For Mobile Access, you only need to specify these values.

These parameters are optional, but you must specify both values in order to have them implemented. If you specify only one value — for example, Min but not Max— then it will be ignored.

optNumESign

A numeric switch that will require the user to e-sign the tag value change. The user will be prompted for their username and password, and the event will be recorded in the project log. To set this switch TRUE, specify any value other than 0.

This parameter is optional; if no value is specified, the default value is 0 (FALSE).

optStrConfirmation

A numeric switch that will cause a confirmation message to be displayed after the user enters the value. The user must acknowledge the message in order to continue. To set this switch TRUE, specify any value other than 0.

Note: Confirmation cannot be automated or bypassed; only an actual key press, mouse click, or on-screen tap (depending on the client station) will acknowledge the message.

This parameter is optional; if no value is specified, the default value is 0 (FALSE).

optRealFmtSpecifier

The format used to display a real value in the dialog box (for example, "%.2f"). Only the f, e, E, g, and G types are accepted. This parameter is optional; if it is not specified, the value is displayed with all its decimal places.

Example: display the Enhanced Keypad, accept values from 0 to 100, and show the current value of TankLevel with two decimal places:

KeyPad("TankLevel", "EnhKeypad", 0, "", 0, 100, 0, 0, "%.2f")

Modifiers

You can control the width and precision using modifiers within the format specifier. Use the following the structure:

[flags][width][.precision]type

.precision: For real numbers, this specifies the number of digits to appear after the decimal point (fo example, %.2f for two decimal places).

width: The minimum total number of characters to use for the output.

flags: You can use the following flags:

• To always display the positive or negative sign, use + (plus sign).

• To set left-justification, use - (minus sign).

• To add padding with leading zeros, use 0

Returned value

This function will return one of the following possible values:

Notes

The Virtual Keyboard / Data Input dialog box is a standard interface for getting data input (that is, numeric values and text) from the user on a client station that is equipped with a touchscreen instead of a physical keyboard. It can be invoked by several different screen objects and program features, in addition to this function. For more information, including examples of the dialog box itself, see Data Input.

Examples

Display the default keyboard for the user to enter a value, and then write the entered value to tagA:

KeyPad("tagA")

Display the Enhanced Keypad for the user to enter a value, and then write the entered value to tagA:

KeyPad("tagA","EnhKeypad")

Display the Enhanced Keypad for the user to enter a value, obfuscate the characters typed by the user, and then write the entered value to tagA:

KeyPad("tagA","EnhKeypad",1)

Display the Enhanced Keypad for the user to enter a value, obfuscate the characters typed by the user, display "My Input" as a hint, with a Min of 0 and a Max of 100, and then write the entered value to tagA:

KeyPad("tagA","EnhKeypad",1,"My Input",0,100)