Skip to main content

Keypad

What is the Form Keypad?​

The keypad form type generates a customizable grid of buttons with different input behaviors. The buttons, their layout, and per-button behavior are all defined from the Values setting.

keypad.png

Options​

General​

Specifies the number of rows to be generated. The possible value is in the range: 1 - 40. The default is 4.

Button Modifiers​

The keypad supports various button modifiers, defined using square brackets. The modifier tags are stripped from the rendered label and only change the button's behavior or appearance. Multiple modifiers can be combined on the same button.

  • [!] - Disabled button (cannot be pressed).
  • [-] - Empty cell (renders a blank, inactive space; no button is generated).
  • [*] - Pressed by default.
  • [c] - Clear button. In Input mode it removes the last character of the output (acts as a backspace). In Check, Radio, and Simple modes it clears all pressed buttons and the output.
  • [ce] - Clear entry button. Clears all pressed buttons and the output in every mode.
  • [enter] - Fires the current output as a -enter-pressed sensor event. In Check mode the enter button's own value is not added to the output text.
  • [space] - Inserts a white space (only works in Input mode).
  • [number] - Defines the button colspan (how many columns it spans). Overflow at the end of a row is clamped to the remaining columns.
  • [msg:message] - Fires the given message as a -button-message sensor event when the button is pressed.
  • [icon:icon name] - Displays a Material Font icon before the label.
  • [value:value] - Specifies a custom button value (the exported value, which can differ from the visible label).
  • [background:color] - Specifies a custom button background; accepts any HTML color value.

Modifier Precedence Table​

When several behavioral modifiers are present on one button, the highest-priority one decides what the press does:

OrderInputCheckRadioSimple
1ClearClear / Clear EntryClear / Clear EntryClear / Clear Entry
2Clear EntryEnter / ValueEnter / ValueEnter
3Enter--Value
4Space---
5Value---

Styling Options​

Defines the button corner radius. The possible value is in the range: 0 - 50. The default is 5.

Setting Mock Field and Own Value​

The keypad stores an object containing:

  • text: The accumulated output text.

  • pressed: The array of the pressed buttons' indexes.

  • The own value is set to the text string, while the mock field receives the full object (text and pressed).

  • The keypad writes to the Mock field and own value:

    • initially, on load
    • after each button press
    • when an external message changes its state.

Output examples​

Input:

"ExampleKeypad": {
  "text": "output text",
  "pressed": []
}

Check:

"ExampleKeypad": {
  "text": "a, b, c",
  "pressed": [0, 12, 10]
}

Radio:

"ExampleKeypad": {
  "text": "value",
  "pressed": [5]
}

Simple:

"ExampleKeypad": {
  "text": "another value",
  "pressed": []
}

Validation​

The keypad does not perform validation. It has no correct/incorrect concept, does not emit a -valid event, and does not draw a validation border.

Sensor Events​

The keypad generates sensor events upon interaction. All events are prefixed with the form's name (FORM-NAME) and are only fired on the displayer.

FORM-NAME

  • Triggered when the keypad writes to the Mock DataSource.
  • Value is the output object. For example:
{
"text": "1, 2, 3",
"pressed": [0, 1, 2]
}

FORM-NAME-text-value

  • Value is the output object's text value.
  • Triggered whenever the keypad writes to the Mock field (initially and after every button press).

FORM-NAME-button-pressed

  • Value is the pressed button's value. Note that the value is not necessarily the same as the label.
  • Triggered after every button press (regardless of modifiers).

FORM-NAME-changed

  • Value is the new output object's text value.
  • Triggered when the output text changes.

FORM-NAME-button-message

  • Value is the button's message.
  • Triggered when a button with the [msg:...] modifier is pressed.

FORM-NAME-enter-pressed

  • Value is the output object's text value.
  • Triggered when a button with the [enter] modifier is pressed.

FORM-NAME-max-entry-reached

  • Value is the configured Max Entry value.
  • Triggered when the max entry limit is reached.

External Messages​

The keypad listens to three external messages:

  • Set Form: Takes the value from the message, parses it exactly like the Values setting (splitting on new lines / semicolons and applying the same modifiers), and rebuilds the keypad with the new buttons. Updates both the Mock and Own values.
  • Clear Form: Clears the output text, un-presses all buttons, and writes the cleared value to the Mock and Own values.
  • Reset Form: Clears the output and re-parses the configured Values, restoring the keypad to its initial state.

Value from Datasource​

The keypad does not bind to an external datasource to generate its buttons; the buttons come only from the Values setting (or a Set Form message). On load it restores its previously exported value (text and pressed indexes) from the form output store, if one is present.

Last updated on