Custom KeyPads

This page describes the XKeyPad widgets that come with GUIslice and how a user can customize their own.

Overview

The XKeyPad widget presents the user with an on-screen keyboard. The XKeyPad is typically implemented as a popup dialog, with the user input being directed towards a target text field within the GUI. The widget offers extensive flexibility and was written to provide flexibility in enabling multiple keyboard variants for different purposes. Each variant can offer multiple keypad layouts, enabling a large number of keys to select from.

The implementation of the KeyPad is comprised of a base XKeyPad module, which is then extended by a variant-specific module (eg. XKeyPad_Alpha, XKeyPad_Num, etc.). The user can easily customize a KeyPad variant or create new one.

Basic KeyPad functionality:

• Cursor to navigate insertion/deletion point (behavior can be modified by CURSOR_ENHANCED)
• Scrolling (if target text field is larger than the keypad display)
• Multiple keypad layouts
• Support for rectangular or rounded buttons
• Minimized RAM consumption (no compound elements needed)
• Key layouts can be arbitrarily specified with colspan / rowspan, enabling staggered positioning
• Customization possible via variant-specific XKeyPad_variant-setup.c files

Included KeyPad variants:

• XKeyPad_Num (Numeric KeyPad)
  • Single layout
  • Optional support for negation and decimal point
• XKeyPad_Alpha (Alphanumeric KeyPad)
  • Three layouts: Upper case, Lower case, Symbols & numbers

Example image: (photo of TFT with XKeyPad_Alpha)

Basic Operations

Showing the KeyPad

Once the KeyPad has been instantiated and configured, a KeyPad popup can be shown on the screen with the following single API:

gslc_ElemXKeyPadInputAsk(&m_gui, m_pElemKeyPad, E_POP_KEYPAD, m_pElemVal1);

In the above, the KeyPad (with element instance name m_pElemKeyPad) will use the popup page named E_POP_KEYPAD. When the keypad has been closed with the Enter button, the contents of the KeyPad buffer will be stored in the element instance named m_pElemVal1. In this scenario, the KeyPad has been associated with a target editable text field.

Association with Target element

If the KeyPad is displayed as a popup window via the ElemXKeyPadInputAsk() API, then the successful closure of the keypad will result in the target element's text field being updated. The other implication of associating a target element with the KeyPad is that the user input will be constrained to the buffer size of the target text field. In other words, if the KeyPad were associated with a text element with "external storage" of 15 bytes, then the KeyPad won't allow the user to enter more than 15 characters.

If a KeyPad is shown without being associated with a target element, then the maximum buffer length of the KeyPad can be used (XKEYPAD_BUF_MAX).

Default Button labels

By default, the KeyPads generally use the following key labels:

• ENT (Enter): Accepts current input and hides the popup keypad
• ESC (Escape): Discards the current input and hides the popup keypad
• BS (Backspace): Deletes the character to the left of the cursor
• < (Cursor Left): Advance the cursor to the left, scrolling as needed
• > (Cursor Right): Advance the cursor to the right, scrolling as needed
• abc (Key Layout swap): Change to the next keypad layout

Customizing KeyPads

To be updated later

Basic customization of a XKeyPad variant is possible through its associated setup file. For example, the XKeyPad_Alpha widget provides customization within the /src/elem/XKeyPad_Alpha-setup.c file. Other general settings are also available at the top of the /src/elem/XKeyPad.h file.

Settings in XKeyPad.h

• XKEYPAD_BUF_MAX: Defines the absolute maximum length of the keypad edit buffer. If a target field has been associated with the keypad, then the lesser of the two sizes define the usable length of the keypad edit buffer.
• XKEYPAD_CURSOR_ENHANCED: Defines the appearance of the cursor. 1 = multi-color cursor more suitable for monospaced fonts, 0 = single-color cursor.
• XKEYPAD_CURSOR_CH: Defines the character used to represent the cursor position

Settings in XKeyPad_*-setup.h

• XKEYPAD_DISP_MAX: Defines the maximum number of characters to show within the edit box. It should be sized to match the dimensions of the text keypad's text region. This value should be less than the maximum buffer (XKEYPAD_BUF_MAX). If KEYPAD_DISP_MAX is less than the smaller of the target field length and XKEYPAD_BUF_MAX, then the text input will be scrolled as needed to be visible within the display.
• XKEYPAD_KEY_W: Defines the default width (in pixels) of the horizontal key unit grid. Note that a given key is defined to occupy one or more horizontal key units.
• XKEYPAD_KEY_H: Defines the default height (in pixels) of the vertical key unit grid. Note that a given key is defined to occupy one or more vertical key units.
• XKEYPAD_SPACING_X: Defines the horizontal margin to leave around the inside of a key's placement on the grid. This setting can be used to leave more margin when rounded corners are used.
• XKEYPAD_SPACING_Y: Defines the vertical margin to leave around the inside of a key's placement on the grid. This setting can be used to leave more margin when rounded corners are used.

The set of keypads (different "pages" of keys) are defined by the gslc_teXKeyPadSel enumeration. If three keypad pages are desired, then the enumeration should have 3 entries, followed by E_XKEYPAD_SET__MAX (which marks the end of the list).

typedef enum {
  // List of keypads
  E_XKEYPAD_SET_UPPER,
  E_XKEYPAD_SET_LOWER,
  E_XKEYPAD_SET_NUM,
  // Terminator
  E_XKEYPAD_SET__MAX,
} gslc_teXKeyPadSel;

The default startup keypad to use is defined by XKEYPAD_LAYOUT_DEFAULT.

The labels for the special buttons (eg. Enter, Escape, etc.) can be specified in the KEYPAD_SPECIAL_LABEL array.

The labels for the basic buttons (all buttons other than the special buttons) are specified in the KEYPAD_SET_LABEL array, with one set for each KeyPad layout.

The labels for the keypad page selection (eg. "abc", "123", etc.) can be specified in the KEYPAD_SPECIAL_SELECT array.

KeyPad Layouts

TBD The KeyPad layout (KEYPAD_LAYOUT) specifies the arrangement of key buttons, their placement, their size (in terms of horizontal and vertical key units) and their appearance (eg. color).

A KeyPad layout can be reused between multiple KeyPad pages. A new layout is only required if a different placement (or number of keys) is required between keypad pages. The mapping of keypad pages to keypad layouts is specified by the KEYPAD_LAYOUTS array.

Color definitions

A set of defines (XKEYPAD_COL_*) are provided to enable customization of the default colors for the various KeyPad special and basic buttons. It is possible for the variant to override these defaults in the gslc_ElemXKeyPadStyleGet_*() function.

KeyPad Layouts

TBD

• Key labels
• Basic vs Special buttons
• colspan, rowspan
• Colors
• Visibility

Field Width and Scrolling

By default, the KeyPad allows the user to input characters to a maximum of the XKEYPAD_BUF_MAX or the target text field size ("External storage" parameter in the Builder)

Creating your own KeyPad

To be updated later

Upgrading from v0.15 to v0.16

• Please refer to XKeyPad Migration Notes