Doc AN03002_Custom_Widget_Type

A product of SEGGER Microcontroller GmbH hWin WM CreateWindowAsChild x0 y0 xSize ySize hWinParent Style pfCallback NumExtraBytes return hWin The parameters of the function MYWIDGET Create are passed to the function WM CreateWindowAsChild without any changes A detailed description of the func tion can be found in chapter 15 7 The Window Manager WM API in the emWin user manual 2 3Widget handle To allow the end user to easily distinguish between widget types a specific type of handle can be defined typedef WM HMEM MYWIDGET Handle The prototype of the create function changes accordingly MYWIDGET Handle MYWIDGET Create int x0 int y0 int xSize int ySize WM HWIN hWinParent U32 Style WM CALLBACK pfCallback int NumExtraBytes AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH GUI COLOR aBkColor 3 GUI COLOR aTextColor 3 GUI COLOR FocusColor const char pText int NumExtraBytes MYWIDGET Obj The background and text colors were declared as arrays so the state of the widget can be distinguished by its visual appearance In later sections the following defines are used to access the color arrays according to the current state of the widget define MYWIDGET CI UNPRESSED 0 define MYWIDGET CI PRESSED 1 define MYWIDGET CI DISABLED 2 The included variables of the MYWIDGET Obj structure can be defined as it is required by the actual type of widget to implement The only variable which is required in every case is a variable to store the number of bytes which is defined by the end user at creation In this case it is called NumExtraBytes For the type of button widget which is implemented in this guide the contained variables are used to store the state the state specific colors and a pointer to a string This structure is going to be stored as user data Nevertheless the opportunity for the end user to attach data to the widget has to be preserved The function MYWIDGET Create changes as follows MYWIDGET Handle MYWIDGET Create int x0 int y0 int xSize int ySize WM HWIN hWinParent U32 Style WM CALLBACK pfCallback int NumExtraBytes MYWIDGET Handle hWin hWin WM CreateWindowAsChild x0 y0 xSize ySize hWinParent Style pfCallback sizeof MYWIDGET Obj NumExtraBytes return hWin Warning The end user must not use the function WM GetUserData or WM SetUserData with a widget of a custom type as it is imple mented using this guide since he would either overwrite widget spe cific data or not retrieve the data he actually expects Therefor custom functions for these purposes have to be implemented as shown in the following 14CHAPTER 2Creating a custom widget type AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH int NumBytes U8 pExtraBytes if SizeOfBuffer MyWidget NumExtraBytes NumBytes MyWidget NumExtraBytes else NumBytes SizeOfBuffer GUI MEMCPY pDest pExtraBytes sizeof MYWIDGET Obj NumBytes free pExtraBytes return NumBytes return 0 Return value Number of copied bytes ParameterDescription hWinHandle to the Widget pDestPointer to the destination buffer SizeOfBufferSize of the destination buffer Table 2 1 MYWIDGET GetUserData parameter list AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH int NumBytes U8 pExtraBytes if SizeOfBuffer MyWidget NumExtraBytes NumBytes MyWidget NumExtraBytes else NumBytes SizeOfBuffer GUI MEMCPY pExtraBytes sizeof MYWIDGET Obj pSrc NumBytes WM SetUserData hWin pExtraBytes sizeof MYWIDGET Obj MyWidget NumExtraBytes free pExtraBytes return 0 return 1 Return value 0 on success 1 on error ParameterDescription hWinHandle to the Widget pSrcPointer to the source buffer SizeOfBufferSize of the source buffer Table 2 2 MYWIDGET SetUserData parameter list 16CHAPTER 2Creating a custom widget type AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH GUI DARKBLUE GUI LIGHTBLUE GUI GRAY GUI COLOR aBkColor 3 GUI WHITE GUI DARKGRAY GUI LIGHTGRAY GUI COLOR aTextColor 3 GUI ORANGE GUI COLOR FocusColor NULL const char pText 0 int NumExtraBytes These values are used when the widget is created The function MYWIDGET Create changes as follows MYWIDGET Handle MYWIDGET Create int x0 int y0 int xSize int ySize WM HWIN hWinParent U32 Style WM CALLBACK pfCallback int NumExtraBytes MYWIDGET Handle hWin MYWIDGET Obj MyWidget hWin WM CreateWindowAsChild x0 y0 xSize ySize hWinParent Style pfCallback sizeof MYWIDGET Obj NumExtraBytes MyWidget MYWIDGET Default MyWidget NumExtraBytes NumExtraBytes WM SetUserData hWin return hWin AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH MYWIDGET Obj MyWidget hWin WM CreateWindowAsChild x0 y0 xSize ySize hWinParent Style pfCallback sizeof MYWIDGET Obj NumExtraBytes MyWidget MYWIDGET Default MyWidget NumExtraBytes NumExtraBytes if pText MyWidget pText pText WM SetUserData hWin return hWin MyWidget pText is set to pText after the default values were applied 2 7Setting the callback function The last and most important part of implementing the Create function is setting the window to use the widget specific callback function Since the opportunity for the end user to implement a custom callback function has to be preserved it should be checked if a pointer to a custom callback function was passed MYWIDGET Handle MYWIDGET Create int x0 int y0 int xSize int ySize WM HWIN hWinParent U32 Style const char pText WM CALLBACK pfCallback int NumExtraBytes MYWIDGET Handle hWin MYWIDGET Obj MyWidget WM CALLBACK pfUsed if pfCallback pfUsed pfCallback else pfUsed MYWIDGET Callback hWin WM CreateWindowAsChild x0 y0 xSize ySize hWinParent Style pfUsed sizeof MYWIDGET Obj NumExtraBytes MyWidget MYWIDGET Default MyWidget NumExtraBytes NumExtraBytes if pText MyWidget pText pText WM SetUserData hWin return hWin 18CHAPTER 2Creating a custom widget type AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH In order to have a visual impact on the widget a reaction to the WM PAINT message is implemented Since the colors to use are stored in the user data they have to be fetched first void MYWIDGET Callback WM MESSAGE pMsg MYWIDGET Handle hWin MYWIDGET Obj MyWidget GUI RECT WinRect int ColorIndex hWin pMsg hWin Get the window coordinates and widget specific data WM GetWindowRectEx hWin GUI MoveRect WM GetUserData hWin switch pMsg MsgId case WM PAINT Determine the color according to the current state if WM IsEnabled hWin if MyWidget Pressed ColorIndex MYWIDGET CI PRESSED else ColorIndex MYWIDGET CI UNPRESSED else ColorIndex MYWIDGET CI DISABLED Draw the background GUI SetColor MyWidget aBkColor ColorIndex GUI FillRectEx Draw the focus rectangle if WM HasFocus hWin GUI SetColor MyWidget FocusColor GUI DrawRectEx Display the text GUI SetColor MyWidget aTextColor ColorIndex GUI SetTextMode GUI TM TRANS GUI DispStringInRect MyWidget pText break default WM DefaultProc pMsg AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH GUI PID STATE pState MYWIDGET Obj MyWidget GUI RECT WinRect int ColorIndex hWin pMsg hWin WM GetWindowRectEx hWin GUI MoveRect WM GetUserData hWin switch pMsg MsgId case WM PAINT if WM IsEnabled hWin if MyWidget Pressed ColorIndex MYWIDGET CI PRESSED else ColorIndex MYWIDGET CI UNPRESSED else ColorIndex MYWIDGET CI DISABLED GUI SetColor MyWidget aBkColor ColorIndex GUI FillRectEx if WM HasFocus hWin GUI SetColor MyWidget FocusColor GUI DrawRectEx GUI SetColor MyWidget aTextColor ColorIndex GUI SetTextMode GUI TM TRANS GUI DispStringInRect MyWidget pText break case WM TOUCH if pMsg Data p pState GUI PID STATE pMsg Data p if MyWidget Pressed pState Pressed MyWidget Pressed pState Pressed WM SetUserData hWin if MyWidget Pressed WM SetFocus hWin WM InvalidateWindow hWin else MyWidget Pressed 0 WM SetUserData hWin WM InvalidateWindow hWin break default WM DefaultProc pMsg The additional code retrieves the PID state which is sent along with the WM TOUCH message and sets the user data accordingly After updating the widget specific data the widget is invalidated in order to receive a new WM PAINT message When running this code clicking the widget will cause the color to change Neverthe less the focus rectangle is not drawn although the function WM SetFocus is called when the widget receives a pressed PID state The reason for this behavior is that the widget never accepts the focus To do so the callback function needs to react to the WM SET FOCUS message as shown below 20CHAPTER 2Creating a custom widget type AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH GUI PID STATE pState MYWIDGET Obj MyWidget GUI RECT WinRect int ColorIndex hWin pMsg hWin WM GetWindowRectEx hWin GUI MoveRect WM GetUserData hWin switch pMsg MsgId case WM PAINT if WM IsEnabled hWin if MyWidget Pressed ColorIndex MYWIDGET CI PRESSED else ColorIndex MYWIDGET CI UNPRESSED else ColorIndex MYWIDGET CI DISABLED GUI SetColor MyWidget aBkColor ColorIndex GUI FillRectEx if WM HasFocus hWin GUI SetColor MyWidget FocusColor GUI DrawRectEx GUI SetColor MyWidget aTextColor ColorIndex GUI SetTextMode GUI TM TRANS GUI DispStringInRect MyWidget pText break case WM TOUCH pState GUI PID STATE pMsg Data p if MyWidget Pressed pState Pressed MyWidget Pressed pState Pressed WM SetUserData hWin if MyWidget Pressed WM SetFocus hWin WM InvalidateWindow hWin break case WM SET FOCUS if pMsg Data v pMsg Data v 0 WM InvalidateWindow hWin break default WM DefaultProc pMsg pMsg Data v 1 means that the widget receives the focus In order to let the Win dow Manager know that the focus was accepted the value has to be set to 0 Oth erwise the focus is not received Once the widget gains or loses the focus it should be invalidated so the appearance changes accordingly if it is intended to do so AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH MYWIDGET Obj typedef struct U8 Pressed GUI COLOR aBkColor 3 GUI COLOR aTextColor 3 GUI COLOR FocusColor const char pText int NumExtraBytes MYWIDGET Obj MYWIDGET Default const MYWIDGET Obj MYWIDGET Default 0 GUI DARKBLUE GUI LIGHTBLUE GUI GRAY GUI WHITE GUI DARKGRAY GUI LIGHTGRAY GUI ORANGE NULL 0 AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH GUI PID STATE pState MYWIDGET Obj MyWidget GUI RECT WinRect int ColorIndex hWin pMsg hWin WM GetWindowRectEx hWin GUI MoveRect WM GetUserData hWin switch pMsg MsgId case WM PAINT if WM IsEnabled hWin if MyWidget Pressed ColorIndex MYWIDGET CI PRESSED else ColorIndex MYWIDGET CI UNPRESSED else ColorIndex MYWIDGET CI DISABLED GUI SetColor MyWidget aBkColor ColorIndex GUI FillRectEx if WM HasFocus hWin GUI SetColor MyWidget FocusColor GUI DrawRectEx GUI SetColor MyWidget aTextColor ColorIndex GUI SetTextMode GUI TM TRANS GUI DispStringInRect MyWidget pText break case WM TOUCH if pMsg Data p pState GUI PID STATE pMsg Data p if MyWidget Pressed pState Pressed MyWidget Pressed pState Pressed WM SetUserData hWin if MyWidget Pressed WM SetFocus hWin WM InvalidateWindow hWin else MyWidget Pressed 0 WM SetUserData hWin WM InvalidateWindow hWin break case WM SET FOCUS if pMsg Data v pMsg Data v 0 WM InvalidateWindow hWin break default WM DefaultProc pMsg 24CHAPTER 3Example implementation AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH int NumBytes U8 pExtraBytes if SizeOfBuffer MyWidget NumExtraBytes NumBytes MyWidget NumExtraBytes else NumBytes SizeOfBuffer GUI MEMCPY pDest pExtraBytes sizeof MYWIDGET Obj NumBytes free pExtraBytes return NumBytes return 0 MYWIDGET SetUserData int MYWIDGET SetUserData MYWIDGET Handle hWin void pSrc int SizeOfBuffer MYWIDGET Obj MyWidget int NumBytes U8 pExtraBytes if SizeOfBuffer MyWidget NumExtraBytes NumBytes MyWidget NumExtraBytes else NumBytes SizeOfBuffer GUI MEMCPY pExtraBytes sizeof MYWIDGET Obj pSrc NumBytes WM SetUserData hWin pExtraBytes sizeof MYWIDGET Obj MyWidget NumExtraBytes free pExtraBytes return 0 return 1 AN03002 Custom Widget Type Creation Guide 2013 SEGGER Microcontroller GmbH MYWIDGET Obj MyWidget WM CALLBACK pfUsed if pfCallback pfUsed pfCallback else pfUsed MYWIDGET Callback MyWidget MYWIDGET Default MyWidget NumExtraBytes NumExtraBytes if pText MyWidget pText pText hWin WM CreateWindowAsChild x0 y0 xSize ySize hWinParent Style pfUsed sizeof MYWIDGET Obj NumExtraBytes WM SetUserData hWin return hWin 3 3End user application cbMyWidget void cbMyWidget WM MESSAGE pMsg GUI RECT WinRect char acText 20 0 switch pMsg MsgId case WM PAINT MYWIDGET Callback pMsg MYWIDGET GetUserData pMsg hWin acText sizeof acText GUI SetColor GUI WHITE GUI SetTextMode GUI TM TRANS WM GetWindowRectEx pMsg hWin GUI MoveRect GUI DispStringInRect acText break default MYWIDGET Callback pMsg MainTask void MainTask void MYWIDGET Handle hMyWidget char acExtraBytes Extrabytes GUI Init hMyWidget