GUIslice  0.16.0
Embedded GUI in C
XKeyPad.h File Reference
#include "GUIslice.h"
Include dependency graph for XKeyPad.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  gslc_tsXKeyPadResult
 Return status for XKeyPad. More...
 
struct  gslc_tsKey
 Key information. Defines everything we need to know about a particular key. More...
 
struct  gslc_tsXKeyPadCfg
 Configuration for the KeyPad. More...
 
struct  gslc_tsXKeyPadData
 Input callback data structure. More...
 
struct  gslc_tsXKeyPad
 Extended data for KeyPad element. More...
 

Macros

#define XKEYPAD_BUF_MAX
 
#define XKEYPAD_KEY_LEN
 
#define XKEYPAD_CURSOR_ENHANCED
 
#define XKEYPAD_CURSOR_CH
 
#define GSLC_TYPEX_KEYPAD
 
#define XKEYPAD_CB_STATE_DONE
 
#define XKEYPAD_CB_STATE_CANCEL
 
#define XKEYPAD_CB_STATE_UPDATE
 
#define XKEYPAD_REDRAW_NONE
 
#define XKEYPAD_REDRAW_TXT
 
#define XKEYPAD_REDRAW_KEY
 
#define XKEYPAD_REDRAW_ALL
 
#define XKEYPAD_REDRAW_FULL
 
#define DEBUG_XKEYPAD
 Debug message for XKeyPad (1=enabled, 0=disabled) More...
 

Typedefs

typedef struct gslc_tsKey gslc_tsKey
 Key information. Defines everything we need to know about a particular key. More...
 
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)
 

Enumerations

enum  {
  KEYPAD_ID_BACKSPACE, KEYPAD_ID_SPACE, KEYPAD_ID_ESC, KEYPAD_ID_ENTER,
  KEYPAD_ID_SWAP_PAD, KEYPAD_ID_SCROLL_LEFT, KEYPAD_ID_SCROLL_RIGHT, KEYPAD_ID_BASIC_START,
  KEYPAD_ID_TXT, KEYPAD_ID__END
}
 
enum  {
  E_XKEYPAD_TYPE_BASIC, E_XKEYPAD_TYPE_SPECIAL, E_XKEYPAD_TYPE_TXT, E_XKEYPAD_TYPE_UNUSED,
  E_XKEYPAD_TYPE_END
}
 

Functions

void gslc_ElemXKeyPadCfgInit (gslc_tsXKeyPadCfg *pConfig)
 Provide default initialization for the base XKeyPad. More...
 
int16_t gslc_XKeyPadLookupId (gslc_tsKey *pKeys, uint8_t nKeyId)
 Find a key ID within a KeyPad label array and return it's index into the array. More...
 
bool gslc_XKeyPadTxtAddCh (gslc_tsXKeyPad *pKeyPad, char ch, uint8_t nPos)
 Add a character to the KeyPad text field at the specified offset (nPos). More...
 
bool gslc_XKeyPadTxtAddStr (gslc_tsXKeyPad *pKeyPad, const char *pStr, uint8_t nPos)
 Add a string to the KeyPad text field at the specified offset (nPos). More...
 
bool gslc_XKeyPadTxtDelCh (gslc_tsXKeyPad *pKeyPad, uint8_t nPos)
 Remove a character from the KeyPad text field at the specified offset (nPos). More...
 
bool gslc_XKeyPadLayoutSet (gslc_tsXKeyPadCfg *pConfig, int8_t eLayoutSel)
 Select a new KeyPad layout. More...
 
void gslc_XKeyPadSizeAllGet (gslc_tsKey **pLayouts, uint8_t nNumLayouts, uint8_t *pnRows, uint8_t *pnCols)
 Calculate the overall dimensions of the KeyPad control encompassing all available layouts for the KeyPad, leveraging the computation in gslc_XKeyPadSizeGet(). More...
 
void gslc_XKeyPadSizeGet (gslc_tsKey *pLayout, uint8_t *pnRows, uint8_t *pnCols)
 Calculate the overall dimensions of the KeyPad control encompassing the text field and key buttons. More...
 
void gslc_XKeyPadDrawKey (gslc_tsGui *pGui, gslc_tsXKeyPad *pXData, gslc_tsKey *pKey)
 Draw a key to the screen. More...
 
gslc_tsElemRefgslc_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)
 Create a KeyPad Element. More...
 
void gslc_ElemXKeyPadValSet (gslc_tsGui *pGui, gslc_tsElemRef *pElemRef, const char *pStrBuf)
 Set the current value for the editable text field. More...
 
void gslc_ElemXKeyPadTargetRefSet (gslc_tsGui *pGui, gslc_tsElemRef *pElemRef, gslc_tsElemRef *pTargetRef)
 Set target element reference for KeyPad return value. More...
 
bool gslc_ElemXKeyPadValGet (gslc_tsGui *pGui, gslc_tsElemRef *pElemRef, char *pStrBuf, uint8_t nStrBufMax)
 Fetch the current value string associated with KeyPad element. More...
 
char * gslc_ElemXKeyPadDataValGet (gslc_tsGui *pGui, void *pvData)
 Fetch the final value string of the KeyPad from a callback. More...
 
int16_t gslc_ElemXKeyPadDataTargetIdGet (gslc_tsGui *pGui, void *pvData)
 Fetch the element target ID associated with this KeyPad. More...
 
bool gslc_XKeyPadDraw (void *pvGui, void *pvElemRef, gslc_teRedrawType eRedraw)
 Draw a KeyPad element on the screen. More...
 
bool gslc_XKeyPadTouch (void *pvGui, void *pvElemRef, gslc_teTouch eTouch, int16_t nRelX, int16_t nRelY)
 Handle touch (up,down,move) events to KeyPad element. More...
 
void gslc_ElemXKeyPadValSetCb (gslc_tsGui *pGui, gslc_tsElemRef *pElemRef, GSLC_CB_INPUT pfuncCb)
 Set the callback function associated with the KeyPad. More...
 
void gslc_ElemXKeyPadCfgSetRoundEn (gslc_tsXKeyPadCfg *pConfig, bool bEn)
 Update the KeyPad configuration to enable rounded button corners. More...
 
void gslc_ElemXKeyPadCfgSetButtonSz (gslc_tsXKeyPadCfg *pConfig, int8_t nButtonSzW, int8_t nButtonSzH)
 Update the KeyPad configuration to define the KeyPad button sizing. More...
 
void gslc_ElemXKeyPadCfgSetButtonSpace (gslc_tsXKeyPadCfg *pConfig, int8_t nSpaceX, int8_t nSpaceY)
 Update the KeyPad configuration to define the KeyPad button spacing. More...
 
void gslc_XKeyPadDrawVirtualTxt (gslc_tsGui *pGui, gslc_tsRect rElem, gslc_tsXKeyPad *pKeyPad, gslc_tsColor cColFrame, gslc_tsColor cColFill, gslc_tsColor cColTxt)
 Draw a virtual Text Element. More...
 
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)
 Draw a virtual textual Button Element. More...
 
void gslc_ElemXKeyPadInputAsk (gslc_tsGui *pGui, gslc_tsElemRef *pKeyPadRef, int16_t nPgPopup, gslc_tsElemRef *pTxtRef)
 Trigger a KeyPad popup and associate it with a text element. More...
 
char * gslc_ElemXKeyPadInputGet (gslc_tsGui *pGui, gslc_tsElemRef *pTxtRef, void *pvCbData)
 Complete a KeyPad popup by retrieving the input data and storing it in the text element. More...
 

Variables

static const int RBIT_TXT
 
static const int RBIT_KEYONE
 
static const int RBIT_KEYALL
 
static const int RBIT_CTRL
 

Macro Definition Documentation

#define DEBUG_XKEYPAD

Debug message for XKeyPad (1=enabled, 0=disabled)

#define GSLC_TYPEX_KEYPAD
#define XKEYPAD_BUF_MAX
#define XKEYPAD_CB_STATE_CANCEL
#define XKEYPAD_CB_STATE_DONE
#define XKEYPAD_CB_STATE_UPDATE
#define XKEYPAD_CURSOR_CH
#define XKEYPAD_CURSOR_ENHANCED
#define XKEYPAD_KEY_LEN
#define XKEYPAD_REDRAW_ALL
#define XKEYPAD_REDRAW_FULL
#define XKEYPAD_REDRAW_KEY
#define XKEYPAD_REDRAW_NONE
#define XKEYPAD_REDRAW_TXT

Typedef Documentation

typedef void(* GSLC_CB_XKEYPAD_BTN_EVT) (void *pvKeyPad, uint8_t nId, gslc_tsXKeyPadResult *psResult)
typedef void(* GSLC_CB_XKEYPAD_LABEL_GET) (void *pvKeyPad, uint8_t nId, uint8_t nStrMax, char *pStr)
typedef void(* GSLC_CB_XKEYPAD_RESET) (void *pvKeyPadConfig)
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_TXT_INIT) (void *pvKeyPad)
typedef struct gslc_tsKey gslc_tsKey

Key information. Defines everything we need to know about a particular key.

Enumeration Type Documentation

anonymous enum
Enumerator
KEYPAD_ID_BACKSPACE 
KEYPAD_ID_SPACE 
KEYPAD_ID_ESC 
KEYPAD_ID_ENTER 
KEYPAD_ID_SWAP_PAD 
KEYPAD_ID_SCROLL_LEFT 
KEYPAD_ID_SCROLL_RIGHT 
KEYPAD_ID_BASIC_START 
KEYPAD_ID_TXT 
KEYPAD_ID__END 
anonymous enum
Enumerator
E_XKEYPAD_TYPE_BASIC 
E_XKEYPAD_TYPE_SPECIAL 
E_XKEYPAD_TYPE_TXT 
E_XKEYPAD_TYPE_UNUSED 
E_XKEYPAD_TYPE_END 

Function Documentation

void gslc_ElemXKeyPadCfgInit ( gslc_tsXKeyPadCfg pConfig)

Provide default initialization for the base XKeyPad.

  • These defaults will be overwritten by variant-specific initialization or through user configuration APIs.
Parameters
[in]pConfigPtr to the KeyPad base config structure
Returns
none
void gslc_ElemXKeyPadCfgSetButtonSpace ( gslc_tsXKeyPadCfg pConfig,
int8_t  nSpaceX,
int8_t  nSpaceY 
)

Update the KeyPad configuration to define the KeyPad button spacing.

  • This defines the inset amount (X and Y) from the Button Size
  • A spacing of (1,1) will mean that the button is drawn with a 1 pixel margin around the grid defined by the Button Size
Parameters
[in,out]pConfigPointer to the XKeyPad base config structure
[in]nSpaceXAmount to inset button in horizontal direction (pixels)
[in]nSpaceYAmount to inset button in vertical direction (pixels)
Returns
none
void gslc_ElemXKeyPadCfgSetButtonSz ( gslc_tsXKeyPadCfg pConfig,
int8_t  nButtonSzW,
int8_t  nButtonSzH 
)

Update the KeyPad configuration to define the KeyPad button sizing.

Parameters
[in,out]pConfigPointer to the XKeyPad base config structure
[in]nButtonSzWWidth of buttons in pixels
[in]nButtonSzHHeight of buttons in pixels
Returns
none
void gslc_ElemXKeyPadCfgSetRoundEn ( gslc_tsXKeyPadCfg pConfig,
bool  bEn 
)

Update the KeyPad configuration to enable rounded button corners.

Parameters
[in,out]pConfigPointer to the XKeyPad base config structure
[in]bEnEnable rounded corners
Returns
none
int16_t gslc_ElemXKeyPadDataTargetIdGet ( gslc_tsGui pGui,
void *  pvData 
)

Fetch the element target ID associated with this KeyPad.

Parameters
[in]pGuiPointer to GUI
[in]pvData: Void ptr to callback data structure
Returns
Target Element ID or GSLC_ID_NONE if unspecified
char* gslc_ElemXKeyPadDataValGet ( gslc_tsGui pGui,
void *  pvData 
)

Fetch the final value string of the KeyPad from a callback.

Parameters
[in]pGuiPointer to GUI
[out]pvData: Void ptr to callback data structure
Returns
Pointer to edited character string
void gslc_ElemXKeyPadInputAsk ( gslc_tsGui pGui,
gslc_tsElemRef pKeyPadRef,
int16_t  nPgPopup,
gslc_tsElemRef pTxtRef 
)

Trigger a KeyPad popup and associate it with a text element.

  • This function also updates the maximum KeyPad buffer length to match that of the target text element, up to the maximum XKEYPAD_BUF_MAX.
Parameters
[in]pGuiPointer to GUI
[in]pKeyPadRefPointer to KeyPad element reference
[in]nPgPopupPage enum that contains the popup to show
[in]pTxtRefPointer to associated text field element reference
Returns
none
char* gslc_ElemXKeyPadInputGet ( gslc_tsGui pGui,
gslc_tsElemRef pTxtRef,
void *  pvCbData 
)

Complete a KeyPad popup by retrieving the input data and storing it in the text element.

Parameters
[in]pGuiPointer to GUI
[in]pTxtRefPointer to associated text field element reference
[in]pvCbDataVoid pointer to callback function's pvData
Returns
The text string that was fetched from the KeyPad (NULL terminated)
void gslc_ElemXKeyPadTargetRefSet ( gslc_tsGui pGui,
gslc_tsElemRef pElemRef,
gslc_tsElemRef pTargetRef 
)

Set target element reference for KeyPad return value.

  • The Target Reference is used in the GSLC_CB_INPUT callback so that the user has the context needed to determine which field should be edited with the contents of the KeyPad edit field
  • It is expected that the user will call this function when showing the KeyPad popup dialog
Parameters
[in]pGuiPointer to GUI
[in]pElemRefPtr to KeyPad Element reference
[in]pTargetRefElement reference for target of KeyPad value
Returns
none
bool gslc_ElemXKeyPadValGet ( gslc_tsGui pGui,
gslc_tsElemRef pElemRef,
char *  pStrBuf,
uint8_t  nStrBufMax 
)

Fetch the current value string associated with KeyPad element.

Parameters
[in]pGuiPointer to GUI
[in]pElemRefPtr to KeyPad Element reference
[out]pStrBufString buffer
[in]nStrBufMaxMaximum length of string buffer (pStrBuf) including terminator
Returns
true if success, false otherwise
void gslc_ElemXKeyPadValSet ( gslc_tsGui pGui,
gslc_tsElemRef pElemRef,
const char *  pStrBuf 
)

Set the current value for the editable text field.

Parameters
[in]pGuiPointer to GUI
[in]pElemRefPtr to KeyPad Element reference
[in]pStrBufString to copy into keypad
Returns
none
void gslc_ElemXKeyPadValSetCb ( gslc_tsGui pGui,
gslc_tsElemRef pElemRef,
GSLC_CB_INPUT  pfuncCb 
)

Set the callback function associated with the KeyPad.

  • This function will be called during updates and OK / Cancel
Parameters
[in]pGuiPointer to GUI
[in]pElemRefPointer to Element Reference for KeyPad
[in]pfuncCbCallback function pointer
Returns
none
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 
)

Create a KeyPad Element.

Parameters
[in]pGuiPointer to GUI
[in]nElemIdElement ID to assign (0..16383 or GSLC_ID_AUTO to autogen)
[in]nPagePage ID to attach element to
[in]pXDataPtr to extended element data structure
[in]nX0X KeyPad Starting Coordinate
[in]nY0Y KeyPad Starting Coordinate
[in]nFontIdFont ID to use for drawing the element
[in]pConfigPointer to base Config options
Returns
Pointer to Element or NULL if failure
bool gslc_XKeyPadDraw ( void *  pvGui,
void *  pvElemRef,
gslc_teRedrawType  eRedraw 
)

Draw a KeyPad element on the screen.

  • Called during redraw
Parameters
[in]pvGuiVoid ptr to GUI (typecast to gslc_tsGui*)
[in]pvElemRefVoid ptr to Element reference (typecast to gslc_tsElemRef*)
[in]eRedrawRedraw mode
Returns
true if success, false otherwise
void gslc_XKeyPadDrawKey ( gslc_tsGui pGui,
gslc_tsXKeyPad pXData,
gslc_tsKey pKey 
)

Draw a key to the screen.

Parameters
[in]pGuiPointer to GUI
[in]pXDataPtr to extended element data structure
[in]pKeyPtr to key being drawn
Returns
none
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 
)

Draw a virtual textual Button Element.

Parameters
[in]pGuiPointer to GUI
[in]rElemRectangle coordinates defining element size
[in]pStrBufString to copy into element
[in]nStrBufMaxMaximum length of string buffer (pStrBuf).
[in]nFontIdFont ID to use for text display
[in]cColFrameFrame color for element
[in]cColFillFill color for element
[in]cColTxtText color for element
[in]bRoundedEnUse Rounded Corners?
Returns
none
void gslc_XKeyPadDrawVirtualTxt ( gslc_tsGui pGui,
gslc_tsRect  rElem,
gslc_tsXKeyPad pKeyPad,
gslc_tsColor  cColFrame,
gslc_tsColor  cColFill,
gslc_tsColor  cColTxt 
)

Draw a virtual Text Element.

  • Creates a text string with filled background
Parameters
[in]pGuiPointer to GUI
[in]rElemRectangle coordinates defining element size
[in]pKeyPadPointer to KeyPad struct
[in]cColFrameFrame color for element
[in]cColFillFill color for element
[in]cColTxtText color for element
Returns
none
bool gslc_XKeyPadLayoutSet ( gslc_tsXKeyPadCfg pConfig,
int8_t  eLayoutSel 
)

Select a new KeyPad layout.

  • Multiple KeyPad layouts can share the same key key definition array (eg. KEYPAD_LAYOUT)
  • This function returns an indication of whether a full KeyPad control redraw is required, ie. the KeyPad layout definition has changed. With changes in the KeyPad definition, there may be a different number of visible keys or arrangements, necessitating a background redraw.
Parameters
[in]pConfigPtr to the KeyPad configuration
[in]eLayoutSelLayout index to select
Returns
true if a full redraw should be performed
int16_t gslc_XKeyPadLookupId ( gslc_tsKey pKeys,
uint8_t  nKeyId 
)

Find a key ID within a KeyPad label array and return it's index into the array.

  • It is expected that the KeyPad label array is terminated with KEYPAD_ID__END
Parameters
[in]pKeysPtr to the Keypad label array
[in]nKeyIdKey ID to look for
Returns
the index into the array if the ID was found or -1 if the key ID was not found
void gslc_XKeyPadSizeAllGet ( gslc_tsKey **  pLayouts,
uint8_t  nNumLayouts,
uint8_t *  pnRows,
uint8_t *  pnCols 
)

Calculate the overall dimensions of the KeyPad control encompassing all available layouts for the KeyPad, leveraging the computation in gslc_XKeyPadSizeGet().

Parameters
[in]pLayoutsPtr to the array of KeyPad layouts
[in]nNumLayoutsNumber of layouts in pLayouts
[out]pnRowsPtr for the number of rows
[out]pnColsPtr for the number of columns
Returns
none
void gslc_XKeyPadSizeGet ( gslc_tsKey pLayout,
uint8_t *  pnRows,
uint8_t *  pnCols 
)

Calculate the overall dimensions of the KeyPad control encompassing the text field and key buttons.

The dimension is calculated in units of the configured key size (width and height), and accounts for any column spans.

Parameters
[in]pLayoutPtr to the KeyPad layout
[out]pnRowsPtr for the number of rows
[out]pnColsPtr for the number of columns
Returns
none
bool gslc_XKeyPadTouch ( void *  pvGui,
void *  pvElemRef,
gslc_teTouch  eTouch,
int16_t  nRelX,
int16_t  nRelY 
)

Handle touch (up,down,move) events to KeyPad element.

Parameters
[in]pvGuiVoid ptr to GUI (typecast to gslc_tsGui*)
[in]pvElemRefVoid ptr to Element reference (typecast to gslc_tsElemRef*)
[in]eTouchTouch event type
[in]nRelXTouch X coord relative to element
[in]nRelYTouch Y coord relative to element
Returns
true if success, false otherwise
bool gslc_XKeyPadTxtAddCh ( gslc_tsXKeyPad pKeyPad,
char  ch,
uint8_t  nPos 
)

Add a character to the KeyPad text field at the specified offset (nPos).

Providing an offset equal to the end of the existing buffer length will cause the addition to the end, whereas an offset within the buffer will cause an insert.

  • An addition that causes the buffer length to exceed the maximum allowed will result in the end of the resulting buffer to be truncated.
  • Typically the addition will be done at the current cursor position.
  • If the insertion is ahead of the cursor, then the cursor position may be increased.
Parameters
[in]pKeyPadPtr to the KeyPad
[in]chCharacter to add
[in]nPosBuffer position for the insertion
Returns
true if the text field should be redrawn, false if no redraw is needed (ie. no change)
bool gslc_XKeyPadTxtAddStr ( gslc_tsXKeyPad pKeyPad,
const char *  pStr,
uint8_t  nPos 
)

Add a string to the KeyPad text field at the specified offset (nPos).

Providing an offset equal to the end of the existing buffer length will cause the addition to the end, whereas an offset within the buffer will cause an insert.

  • An addition that causes the buffer length to exceed the maximum allowed will result in the end of the resulting buffer to be truncated.
  • Typically the addition will be done at the current cursor position.
  • If the insertion is ahead of the cursor, then the cursor position may be increased.
  • This routine may be useful when adding multi-byte characters for future support of foreign characters.
Parameters
[in]pKeyPadPtr to the KeyPad
[in]pStrString to add
[in]nPosBuffer position for the insertion
Returns
true if the text field should be redrawn, false if no redraw is needed (ie. no change)
bool gslc_XKeyPadTxtDelCh ( gslc_tsXKeyPad pKeyPad,
uint8_t  nPos 
)

Remove a character from the KeyPad text field at the specified offset (nPos).

  • Typically the addition will be done at the current cursor position.
  • If the removal is ahead of the cursor, then the cursor position may be decreased.
Parameters
[in]pKeyPadPtr to the KeyPad
[in]nPosBuffer position for the removal
Returns
true if the text field should be redrawn, false if no redraw is needed (ie. no change)

Variable Documentation

const int RBIT_CTRL
static
const int RBIT_KEYALL
static
const int RBIT_KEYONE
static
const int RBIT_TXT
static