XKeyPad.h

Go to the documentation of this file.

#ifndef _GUISLICE_EX_XKEYPAD_H_
#define _GUISLICE_EX_XKEYPAD_H_

#include "GUIslice.h"


// =======================================================================
// GUIslice library extension: XKeyPad control
// - Paul Conti, Calvin Hass
// - https://www.impulseadventure.com/elec/guislice-gui.html
// - https://github.com/ImpulseAdventure/GUIslice
// =======================================================================
//
// The MIT License
//
// Copyright 2016-2020 Calvin Hass
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//
// =======================================================================

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus


// ============================================================================
// Extended Element: KeyPad (Number Selector)
// - Demonstration of a compound element consisting of
//   a counter text field along with an increment and
//   decrement button.
// ============================================================================

// ============================================================================
// User-configurable options
// - The following options can be adjusted by the user if needed

#define XKEYPAD_BUF_MAX  20  // Maximum buffer length for input string
#define XKEYPAD_KEY_LEN  6   // Maximum buffer length for a single key


// Select cursor appearance:
// - 1 : Colorized cursor, intended for monospaced fonts
// - 0 : Normal cursor, can use proportional fonts
#define XKEYPAD_CURSOR_ENHANCED   1    // Cursor appearance
#define XKEYPAD_CURSOR_CH         '^'  // Character to use for embedded cursor


// ============================================================================

// Define unique identifier for extended element type
// - Select any number above GSLC_TYPE_BASE_EXTEND
#define GSLC_TYPEX_KEYPAD GSLC_TYPE_BASE_EXTEND + 20

// Define the status for GSLC_CB_INPUT callback
#define XKEYPAD_CB_STATE_DONE   1
#define XKEYPAD_CB_STATE_CANCEL 2
#define XKEYPAD_CB_STATE_UPDATE 3

// Bit mask to define what needs to be redrawn
static const int RBIT_TXT     = 1;    // Redraw the text field
static const int RBIT_KEYONE  = 2;    // Redraw a single key (defined by nXKeyPadRedrawId)
static const int RBIT_KEYALL  = 4;    // Redraw all keys
static const int RBIT_CTRL    = 128;  // Redraw the entire control

// Definitions for XKeyPad redraw state (eRedrawState)
#define XKEYPAD_REDRAW_NONE   0                               // No need for a redraw
#define XKEYPAD_REDRAW_TXT    RBIT_TXT                        // Redraw the text field
#define XKEYPAD_REDRAW_KEY    RBIT_KEYONE                     // Redraw a single key (defined by nXKeyPadRedrawId)
#define XKEYPAD_REDRAW_ALL    RBIT_KEYALL+RBIT_TXT            // Redraw all keys and text field
#define XKEYPAD_REDRAW_FULL   RBIT_KEYALL+RBIT_TXT+RBIT_CTRL  // Redraw entire control (frame, all keys and text)

#define DEBUG_XKEYPAD         0 

typedef struct {
  int16_t eRedrawState;         
  int16_t nRedrawKeyId;         
} gslc_tsXKeyPadResult;


// Define global list of common button ID types
// - A given keypad may not use all of these
enum {
  // --- Special Buttons (0..15)
  KEYPAD_ID_BACKSPACE = 0,
  KEYPAD_ID_SPACE,
  KEYPAD_ID_ESC,
  KEYPAD_ID_ENTER,
  KEYPAD_ID_SWAP_PAD,
  KEYPAD_ID_SCROLL_LEFT,
  KEYPAD_ID_SCROLL_RIGHT,  

  // --- Variant-specific special buttons
  //     These are defined within the variant's "-setup.c"
  //     And are reserved the ID range 16..31

  // --- Basic Buttons
  KEYPAD_ID_BASIC_START = 32,
  // --- Text field
  KEYPAD_ID_TXT = 240,
  // --- Terminators
  KEYPAD_ID__END = 255
};

enum {
  E_XKEYPAD_TYPE_BASIC,       // Basic button (single character)
  E_XKEYPAD_TYPE_SPECIAL,     // Special button, static content
  E_XKEYPAD_TYPE_TXT,         // Text field
  E_XKEYPAD_TYPE_UNUSED,      // Unused key
  E_XKEYPAD_TYPE_END,         // Terminator indicator (end of key list)
};

// Extended element data structures
// - These data structures are maintained in the gslc_tsElem
//   structure via the pXData pointer

  typedef struct gslc_tsKey {
    uint8_t             nId;       
    uint8_t             nRow;      
    uint8_t             nCol;      
    uint8_t             nRowSpan;  
    uint8_t             nColSpan;  
    uint8_t             nType;     
  } gslc_tsKey;


  // Internal callback functions for KeyPad
  typedef void (*GSLC_CB_XKEYPAD_RESET)(void* pvKeyPadConfig);
  typedef void (*GSLC_CB_XKEYPAD_TXT_INIT)(void* pvKeyPad);
  typedef void (*GSLC_CB_XKEYPAD_LABEL_GET)(void* pvKeyPad,uint8_t nId,uint8_t nStrMax,char* pStr);
  typedef void (*GSLC_CB_XKEYPAD_SYTLE_GET)(void* pvKeyPad,uint8_t nId, bool* bVisible, gslc_tsColor* pcolTxt, gslc_tsColor *pcolFrame, gslc_tsColor *pcolFill, gslc_tsColor *pcolGlow);
  typedef void (*GSLC_CB_XKEYPAD_BTN_EVT)(void* pvKeyPad,uint8_t nId,gslc_tsXKeyPadResult* psResult);

  typedef struct {
    uint8_t             nDispMax;         

    bool                bRoundEn;         
    int8_t              nButtonSzW;       
    int8_t              nButtonSzH;       
    int8_t              nButtonSpaceX;    
    int8_t              nButtonSpaceY;    
    gslc_tsKey*         pLayout;          
    gslc_tsKey**        pLayouts;         
    int8_t              eLayoutDef;       
    int8_t              eLayoutSel;       
    
    // From constructor
    int16_t             nFontId;          
    int16_t             nOffsetX;         
    int16_t             nOffsetY;         

    int8_t              nFrameMargin;     
    uint8_t             nMaxCols;         
    uint8_t             nMaxRows;         

    GSLC_CB_XKEYPAD_RESET       pfuncReset;     
    GSLC_CB_XKEYPAD_TXT_INIT    pfuncTxtInit;   
    GSLC_CB_XKEYPAD_LABEL_GET   pfuncLabelGet;  
    GSLC_CB_XKEYPAD_SYTLE_GET   pfuncStyleGet;  
    GSLC_CB_XKEYPAD_BTN_EVT     pfuncBtnEvt;    

  } gslc_tsXKeyPadCfg;

  typedef struct {
    char*               pStr;             
    gslc_tsElemRef*     pTargetRef;       
  } gslc_tsXKeyPadData;

  typedef struct {

    // State
    uint8_t             nBufferMax;                 
    uint8_t             nBufferLen;                 
    char                acBuffer[XKEYPAD_BUF_MAX];  
    uint8_t             nCursorPos;                 
    uint8_t             nScrollPos;                 

    gslc_tsXKeyPadResult  sRedraw;        

    // Config
    gslc_tsXKeyPadCfg*  pConfig;          

    GSLC_CB_INPUT       pfuncCb;          
    gslc_tsElemRef*     pTargetRef;       
    
  } gslc_tsXKeyPad;

  void gslc_ElemXKeyPadCfgInit(gslc_tsXKeyPadCfg* pConfig);

  int16_t gslc_XKeyPadLookupId(gslc_tsKey* pKeys, uint8_t nKeyId);

  bool gslc_XKeyPadTxtAddCh(gslc_tsXKeyPad* pKeyPad,char ch,uint8_t nPos);

  bool gslc_XKeyPadTxtAddStr(gslc_tsXKeyPad* pKeyPad,const char* pStr,uint8_t nPos);

  bool gslc_XKeyPadTxtDelCh(gslc_tsXKeyPad* pKeyPad,uint8_t nPos);

  bool gslc_XKeyPadLayoutSet(gslc_tsXKeyPadCfg* pConfig,int8_t eLayoutSel);


  void gslc_XKeyPadSizeAllGet(gslc_tsKey** pLayouts, uint8_t nNumLayouts, uint8_t* pnRows, uint8_t* pnCols);


  void gslc_XKeyPadSizeGet(gslc_tsKey* pLayout, uint8_t* pnRows, uint8_t* pnCols);

  void gslc_XKeyPadDrawKey(gslc_tsGui* pGui, gslc_tsXKeyPad* pXData, gslc_tsKey* pKey);

  gslc_tsElemRef* gslc_XKeyPadCreateBase(gslc_tsGui* pGui, int16_t nElemId, int16_t nPage,
    gslc_tsXKeyPad* pXData, int16_t nX0, int16_t nY0, int8_t nFontId, gslc_tsXKeyPadCfg* pConfig);


  void gslc_ElemXKeyPadValSet(gslc_tsGui* pGui, gslc_tsElemRef* pElemRef, const char* pStrBuf);


  void gslc_ElemXKeyPadTargetRefSet(gslc_tsGui* pGui, gslc_tsElemRef* pElemRef, gslc_tsElemRef* pTargetRef);


  bool gslc_ElemXKeyPadValGet(gslc_tsGui* pGui, gslc_tsElemRef* pElemRef, char* pStrBuf, uint8_t nStrBufMax);

  char* gslc_ElemXKeyPadDataValGet(gslc_tsGui* pGui, void* pvData);


  int16_t gslc_ElemXKeyPadDataTargetIdGet(gslc_tsGui* pGui, void* pvData);

  bool gslc_XKeyPadDraw(void* pvGui, void* pvElemRef, gslc_teRedrawType eRedraw);

  bool gslc_XKeyPadTouch(void* pvGui, void* pvElemRef, gslc_teTouch eTouch, int16_t nRelX, int16_t nRelY);

  void gslc_ElemXKeyPadValSetCb(gslc_tsGui* pGui, gslc_tsElemRef* pElemRef, GSLC_CB_INPUT pfuncCb);

  void gslc_ElemXKeyPadCfgSetRoundEn(gslc_tsXKeyPadCfg* pConfig,bool bEn);

  void gslc_ElemXKeyPadCfgSetButtonSz(gslc_tsXKeyPadCfg* pConfig, int8_t nButtonSzW, int8_t nButtonSzH);

  void gslc_ElemXKeyPadCfgSetButtonSpace(gslc_tsXKeyPadCfg* pConfig, int8_t nSpaceX, int8_t nSpaceY);


  void gslc_XKeyPadDrawVirtualTxt(gslc_tsGui* pGui,gslc_tsRect rElem,gslc_tsXKeyPad* pKeyPad,
    gslc_tsColor cColFrame, gslc_tsColor cColFill, gslc_tsColor cColTxt);

  void gslc_XKeyPadDrawVirtualBtn(gslc_tsGui* pGui, gslc_tsRect rElem,
    char* pStrBuf,uint8_t nStrBufMax,int16_t nFontId, gslc_tsColor cColFrame,
    gslc_tsColor cColFill, gslc_tsColor cColTxt, bool bRoundedEn);


  void gslc_ElemXKeyPadInputAsk(gslc_tsGui* pGui, gslc_tsElemRef* pKeyPadRef, int16_t nPgPopup, gslc_tsElemRef* pTxtRef);

  char* gslc_ElemXKeyPadInputGet(gslc_tsGui* pGui, gslc_tsElemRef* pTxtRef, void* pvCbData);

// ============================================================================

// ------------------------------------------------------------------------
// Read-only element macros
// ------------------------------------------------------------------------

// Macro initializers for Read-Only Elements in Flash/PROGMEM
//
#ifdef __cplusplus
}
#endif // __cplusplus
#endif // _GUISLICE_EX_XKEYPAD_H_