Migration Notes (XKeyPad)

The XKeyPad widget underwent a major update between v0.15 and v0.16, enabling many new features:

• Greatly reduced RAM consumption (no need for compound element)
• Support for multiple pages within the alphanumeric keypad (e.g uppercase, lowercase, symbols)
• User-customization of the keypads (key labels, layout, colors, etc.) via *-setup.h files
• Cursor navigation within the keypad, to allow insert/delete anywhere
• Dynamic button styling (color, visibility, content, etc.)
• Text input scrolling
• Staggered key layouts

Example image: (photo of TFT)

Migration Notes

Builder Users

Due to a change in APIs, it is important that both the GUIslice library and the GUIslice Builder are in sync (ie. v0.16+).

With new sketches created with Builder v0.16, no steps are necessary.

For users with sketches created prior to v0.16 that contained an earlier version of the KeyPad:

• In most cases, the Builder v0.16 will be able to upgrade your user sketch (eg. sketch.ino and sketch_GSLC.h) to use the new keypads without any additional corrections.
• As a number of enumerations were changed in the process, it is possible that some manual search & replace update could be required.

GUIslice API Users

As there were some API changes between the v0.15 and v0.16 XKeyPad, the following section details the changes necessary in user code:

1. User config: it is no longer necessary to enable GSLC_FEATURE_COMPOUND
2. The main KeyPad instance (eg. m_sKeyPadAlpha) is now of type gslc_tsXKeyPad instead of the keypad variant (eg. gslc_tsXKeyPad_Alpha or gslc_tsXKeyPad_Num).
3. The method to trigger a keypad popup is now much simpler.

Old code:

  gslc_ElemXKeyPadTargetIdSet(&m_gui, m_pElemKeyPad, E_TXT_VAL1);
  gslc_PopupShow(&m_gui, E_POP_KEYPAD, true);
  gslc_ElemXKeyPadValSet(&m_gui, m_pElemKeyPad, gslc_ElemGetTxtStr(&m_gui, m_pElemVal1));

New code:

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

4. Some changes were made to the configuration of the KeyPad in the sketch:

Old code:

  gslc_tsXKeyPadCfg sCfg = gslc_ElemXKeyPadCfgInit_Alpha();
  gslc_ElemXKeyPadCfgSetButtonSz(&sCfg, 25, 25);
  m_pElemKeyPad = gslc_ElemXKeyPadCreate_Alpha(&m_gui, E_ELEM_KEYPAD, E_POP_KEYPAD,
    &m_sKeyPadAlpha, 65, 80, E_FONT_TXT1, &sCfg);
  gslc_ElemXKeyPadValSetCb(&m_gui, m_pElemKeyPad, &CbInputCommon);

New code:

  static gslc_tsXKeyPadCfg_Alpha sCfg = gslc_ElemXKeyPadCfgInit_Alpha();
  gslc_ElemXKeyPadCfgSetButtonSz((gslc_tsXKeyPadCfg*)&sCfg, 12, 25);
  m_pElemKeyPad = gslc_ElemXKeyPadCreate_Alpha(&m_gui, E_ELEM_KEYPAD, E_POP_KEYPAD,
    &m_sKeyPadAlpha, 50, 80, E_FONT_TXT1, &sCfg);
  gslc_ElemXKeyPadValSetCb(&m_gui, m_pElemKeyPad, &CbInputCommon);

A few things to note in the above: The main config variable (eg. sCfg) uses the KeyPad variant type (eg. _Alpha/_Num) and is declared static. The configuration APIs that take sCfg now require one to insert the typecast: (gslc_tsXKeyPadCfg*)

5. The default KeyPad button width for the Alphanumeric was changed from 25 pixels to 12 pixels. This is because the keypad layout was mostly defined using "colspan=2", meaning that each button typically occupied 2 units in the horizontal direction (each unit being KeyPad size X, or 12 pixels). This minor adjustment enabled a staggered layout.