From 86aef5990a702cc10c99d41c8aa7cc15b3338cae Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Tue, 3 Nov 2015 20:39:16 +0100 Subject: [PATCH] Doxygen (documenting each built-in rendering function for widgets) --- src/gwin/gwin_button.h | 124 +++++++++++++++++---- src/gwin/gwin_checkbox.h | 41 +++++-- src/gwin/gwin_container.h | 208 +++++++++++++++++++++--------------- src/gwin/gwin_frame.h | 124 +++++++++++++-------- src/gwin/gwin_keyboard.c | 1 - src/gwin/gwin_keyboard.h | 26 +++++ src/gwin/gwin_label.c | 4 +- src/gwin/gwin_label.h | 28 +++++ src/gwin/gwin_list.c | 4 +- src/gwin/gwin_list.h | 27 +++++ src/gwin/gwin_progressbar.h | 48 ++++++--- src/gwin/gwin_radio.h | 50 +++++++-- src/gwin/gwin_slider.h | 47 +++++--- src/gwin/gwin_textedit.c | 4 +- src/gwin/gwin_textedit.h | 27 +++++ 15 files changed, 555 insertions(+), 208 deletions(-) diff --git a/src/gwin/gwin_button.h b/src/gwin/gwin_button.h index 282ed828..90a7d106 100644 --- a/src/gwin/gwin_button.h +++ b/src/gwin/gwin_button.h @@ -86,43 +86,129 @@ GHandle gwinGButtonCreate(GDisplay *g, GButtonObject *gb, const GWidgetInit *pIn bool_t gwinButtonIsPressed(GHandle gh); /** - * @brief Some custom button drawing routines - * @details These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles + * @defgroup Renderings_Button Button rendering functions * - * @param[in] gw The widget object (in this case a button) - * @param[in] param A parameter passed in from the user + * @brief Built-in rendering functions for the button widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles. * * @note In your custom button drawing function you may optionally call these * standard functions and then draw your extra details on top. * @note The standard functions below ignore the param parameter except for @p gwinButtonDraw_Image(). * @note The image custom draw function @p gwinButtonDraw_Image() uses param to pass in the gdispImage pointer. - * The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3 - * times the height of the button. The button image is repeated 3 times vertically, the first (top) for - * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If - * the disabled state is never going to be used then the image can be just 2 times the button height. - * No checking is done to compare the size of the button to the size of the image. - * Note text is drawn on top of the image. * @note These custom drawing routines don't have to worry about setting clipping as the framework * sets clipping to the object window prior to calling these routines. * - * @api * @{ */ -void gwinButtonDraw_Normal(GWidgetObject *gw, void *param); // @< A standard button + +/** + * @brief The default rendering function for the button widget + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinButtonDraw_Normal(GWidgetObject *gw, void *param); + #if GDISP_NEED_ARC || defined(__DOXYGEN__) - void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param); // @< A rounded rectangle button + /** + * @brief Renders a rectangular button with rounded corners + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @pre GDISP_NEED_ARC must be set to TRUE + * + * @api + */ + void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param); #endif + #if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__) - void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param); // @< A circular button + /** + * @brief Renders a button with an elliptical shape + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @pre GDISP_NEED_ELLIPSE must be set to TRUE + * + * @api + */ + void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param); #endif + #if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__) - void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param); // @< An up arrow button - void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param); // @< A down arrow button - void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param); // @< A left arrow button - void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param); // @< A right arrow button + /** + * @brief Renders a button in a shape of an arrow pointing up. + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE + * + * @api + */ + void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param); + + /** + * @brief Renders a button in a shape of an arrow pointing down. + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE + * + * @api + */ + void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param); + + /** + * @brief Renders a button in a shape of an arrow pointing left. + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE + * + * @api + */ + void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param); + + /** + * @brief Renders a button in a shape of an arrow pointing right. + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE + * + * @api + */ + void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param); #endif + #if GDISP_NEED_IMAGE || defined(__DOXYGEN__) - void gwinButtonDraw_Image(GWidgetObject *gw, void *param); // @< An image button - see the notes above on the param. + /** + * @brief Renders a button using individual images for each button state. + * + * @param[in] gw The widget object (must be a button object) + * @param[in] param A parameter passed in from the user. Must be an image handle. See note below. + * + * @note The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3 + * times the height of the button. The button image is repeated 3 times vertically, the first (top) for + * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If + * the disabled state is never going to be used then the image can be just 2 times the button height. + * No checking is done to compare the size of the button to the size of the image. + * Note text is drawn on top of the image. + * + * @pre GDISP_NEED_IMAGE must be set to TRUE + * + * @api + */ + void gwinButtonDraw_Image(GWidgetObject *gw, void *param); #endif /** @} */ diff --git a/src/gwin/gwin_checkbox.h b/src/gwin/gwin_checkbox.h index f0a8e9f0..d2d2c42c 100644 --- a/src/gwin/gwin_checkbox.h +++ b/src/gwin/gwin_checkbox.h @@ -99,23 +99,50 @@ void gwinCheckboxCheck(GHandle gh, bool_t isChecked); bool_t gwinCheckboxIsChecked(GHandle gh); /** - * @brief Some custom checkbox drawing routines - * @details These function may be passed to @p gwinSetCustomDraw() to get different checkbox drawing styles + * @defgroup Renderings_Checkbox Checkbox rendering functions * - * @param[in] gw The widget (which must be a checkbox) - * @param[in] param A parameter passed in from the user + * @brief Built-in rendering functions for the checkbox widget. * - * @note In your custom checkbox drawing function you may optionally call this + * @details These function may be passed to @p gwinSetCustomDraw() to get different checkbox drawing styles. + * + * @note In your custom checkbox drawing function you may optionally call these * standard functions and then draw your extra details on top. - * @note The standard functions below ignore the param parameter. * @note These custom drawing routines don't have to worry about setting clipping as the framework * sets clipping to the object window prior to calling these routines. * - * @api * @{ */ + +/** + * @brief Renders a square checkbox where the text is on the right side of the checkbox. + * + * @param[in] gw The widget (must be a checkbox) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ void gwinCheckboxDraw_CheckOnLeft(GWidgetObject *gw, void *param); + +/** + * @brief Renders a square checkbox where the text is on the left side of the checkbox. + * + * @param[in] gw The widget (must be a checkbox) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ void gwinCheckboxDraw_CheckOnRight(GWidgetObject *gw, void *param); + +/** + * @brief Renders a checkbox in form of a rectangular button with the text inside of it. + * + * @details This behaves like a button that can be toggled. + * + * @param[in] gw The widget (must be a checkbox) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ void gwinCheckboxDraw_Button(GWidgetObject *gw, void *param); /** @} */ diff --git a/src/gwin/gwin_container.h b/src/gwin/gwin_container.h index 0e75cfb9..5ae23cea 100644 --- a/src/gwin/gwin_container.h +++ b/src/gwin/gwin_container.h @@ -48,102 +48,132 @@ typedef GWidgetObject GContainerObject; extern "C" { #endif - /** - * @brief Get the first child window - * - * @return The first child or NULL if are no children windows - * - * @param[in] gh The parent container or NULL to get the first top level window - * - * @api - */ - GHandle gwinGetFirstChild(GHandle gh); +/** + * @brief Get the first child window + * + * @return The first child or NULL if are no children windows + * + * @param[in] gh The parent container or NULL to get the first top level window + * + * @api + */ +GHandle gwinGetFirstChild(GHandle gh); - /** - * @brief Get the next child window in the z-order - * - * @return The next window or NULL if no more children - * - * @param[in] gh The window to obtain the next sibling of. - * - * @note This returns the next window under the current parent window. - * Unlike @p gwinGetNextWindow() it will only return windows that - * have the same parent as the supplied window. - * - * @api - */ - GHandle gwinGetSibling(GHandle gh); +/** + * @brief Get the next child window in the z-order + * + * @return The next window or NULL if no more children + * + * @param[in] gh The window to obtain the next sibling of. + * + * @note This returns the next window under the current parent window. + * Unlike @p gwinGetNextWindow() it will only return windows that + * have the same parent as the supplied window. + * + * @api + */ +GHandle gwinGetSibling(GHandle gh); - /** - * @brief Get the inner width of a container window - * - * @return The inner width of a container window or zero if this is not a container - * - * @param[in] gh The window - * - * @api - */ - coord_t gwinGetInnerWidth(GHandle gh); +/** + * @brief Get the inner width of a container window + * + * @return The inner width of a container window or zero if this is not a container + * + * @param[in] gh The window + * + * @api + */ +coord_t gwinGetInnerWidth(GHandle gh); - /** - * @brief Get the inner height of a container window - * - * @return The inner height of a container window or zero if this is not a container - * - * @param[in] gh The window - * - * @api - */ - coord_t gwinGetInnerHeight(GHandle gh); +/** + * @brief Get the inner height of a container window + * + * @return The inner height of a container window or zero if this is not a container + * + * @param[in] gh The window + * + * @api + */ +coord_t gwinGetInnerHeight(GHandle gh); - /** - * @brief Flags for gwinContainerCreate() - * @{ - */ - #define GWIN_CONTAINER_BORDER 0x00000001 - /** @} */ +/** + * @brief Flags for gwinContainerCreate() + * @{ + */ +#define GWIN_CONTAINER_BORDER 0x00000001 +/** @} */ - /** - * @brief Create a simple container. - * @return NULL if there is no resultant drawing area, otherwise a window handle. - * - * @param[in] g The GDisplay to display this window on - * @param[in] gw The GContainerObject structure to initialise. If this is NULL the structure is dynamically allocated. - * @param[in] pInit The initialisation parameters - * @param[in] flags Some flags, see notes - * - * @api - */ - GHandle gwinGContainerCreate(GDisplay *g, GContainerObject *gw, const GWidgetInit *pInit, uint32_t flags); - #define gwinContainerCreate(gc, pInit, flags) gwinGContainerCreate(GDISP, gc, pInit, flags) +/** + * @brief Create a simple container. + * @return NULL if there is no resultant drawing area, otherwise a window handle. + * + * @param[in] g The GDisplay to display this window on + * @param[in] gw The GContainerObject structure to initialise. If this is NULL the structure is dynamically allocated. + * @param[in] pInit The initialisation parameters + * @param[in] flags Some flags, see notes + * + * @api + */ +GHandle gwinGContainerCreate(GDisplay *g, GContainerObject *gw, const GWidgetInit *pInit, uint32_t flags); +#define gwinContainerCreate(gc, pInit, flags) gwinGContainerCreate(GDISP, gc, pInit, flags) - /** - * @brief The custom draw routines for a simple container - * @details These function may be passed to @p gwinSetCustomDraw() to get different frame drawing styles - * - * @param[in] gw The widget object (in this case a frame) - * @param[in] param A parameter passed in from the user - * - * @note In your own custom drawing function you may optionally call these - * standard functions and then draw your extra details on top. - * - * @note gwinContainerDraw_Std() will fill the client area with the background color.
- * gwinContainerDraw_Transparent() will not fill the client area at all.
- * gwinContainerDraw_Image() will tile the image throughout the client area.
- * All these drawing functions draw the frame itself the same way. - * - * @note The standard functions below ignore the param parameter except for @p gwinContainerDraw_Image(). - * @note The image custom draw function @p gwinContainerDraw_Image() uses param to pass in the gdispImage pointer. - * The image must be already opened before calling @p gwinSetCustomDraw(). - * - * @api - * @{ - */ - void gwinContainerDraw_Std(GWidgetObject *gw, void *param); - void gwinContainerDraw_Transparent(GWidgetObject *gw, void *param); - void gwinContainerDraw_Image(GWidgetObject *gw, void *param); - /** @} */ + +/** + * @defgroup Renderings_Container Container rendering functions + * + * @brief Built-in rendering functions for the container widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different container drawing styles. + * + * @note In your custom container drawing function you may optionally call these + * standard functions and then draw your extra details on top. + * @note These custom drawing routines don't have to worry about setting clipping as the framework + * sets clipping to the object window prior to calling these routines. + * + * @{ + */ + +/** + * @brief The default rendering function for the container widget. + * + * @details Fills the client area with the background color. + * + * @param[in] gw The widget object (must be a container object). + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinContainerDraw_Std(GWidgetObject *gw, void *param); + +/** + * @brief Renders the container but leaves the client area transparent. + * + * @details Will not fill the client area at all. + * + * @param[in] gw The widget object (must be a container object). + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinContainerDraw_Transparent(GWidgetObject *gw, void *param); + +/** + * @brief Renders the container and uses the specified image for the client area. + * + * @details The image will be tiled throghout the client area. Therefore, to archive the best looking result the + * supplied image needs to be of the same size as the client area size of the container widget (inner size). + * + * @param[in] gw The widget object (must be a container object). + * @param[in] param A parameter passed in from the user. Must be an image handle. See note below. + * + * @note The image must be already opened before calling @p gwinSetCustomDraw(). The handle is passed as the parameter + * to this function. + * + * @api + */ +void gwinContainerDraw_Image(GWidgetObject *gw, void *param); +/** @} */ #ifdef __cplusplus } diff --git a/src/gwin/gwin_frame.h b/src/gwin/gwin_frame.h index f71a88a5..2e0cc1b2 100644 --- a/src/gwin/gwin_frame.h +++ b/src/gwin/gwin_frame.h @@ -40,53 +40,85 @@ typedef GContainerObject GFrameObject; extern "C" { #endif - /** - * @brief Create a frame widget - * - * @details This widget provides a window like we know it from desktop systems. - * - * @param[in] g The GDisplay to display this window on - * @param[in] fo The GFrameObject structure to initialize. If this is NULL the structure is dynamically allocated. - * @param[in] pInit The initialization parameters - * @param[in] flags Some flags, see notes. - * - * @note Possible flags are: GWIN_FRAME_CLOSE_BTN, GWIN_FRAME_MINMAX_BTN. - * @note These frame buttons are processed internally. The close button will invoke a gwinDestroy() which will - * destroy the window itself and EVERY child it contains (also children of children). - * - * @return NULL if there is no resulting widget. A valid GHandle otherwise. - * - * @api - */ - GHandle gwinGFrameCreate(GDisplay *g, GFrameObject *fo, GWidgetInit *pInit, uint32_t flags); - #define gwinFrameCreate(fo, pInit, flags) gwinGFrameCreate(GDISP, fo, pInit, flags); +/** + * @brief Create a frame widget + * + * @details This widget provides a window like we know it from desktop systems. + * + * @param[in] g The GDisplay to display this window on + * @param[in] fo The GFrameObject structure to initialize. If this is NULL the structure is dynamically allocated. + * @param[in] pInit The initialization parameters + * @param[in] flags Some flags, see notes. + * + * @note Possible flags are: GWIN_FRAME_CLOSE_BTN, GWIN_FRAME_MINMAX_BTN. + * @note These frame buttons are processed internally. The close button will invoke a gwinDestroy() which will + * destroy the window itself and EVERY child it contains (also children of children). + * + * @return NULL if there is no resulting widget. A valid GHandle otherwise. + * + * @api + */ +GHandle gwinGFrameCreate(GDisplay *g, GFrameObject *fo, GWidgetInit *pInit, uint32_t flags); +#define gwinFrameCreate(fo, pInit, flags) gwinGFrameCreate(GDISP, fo, pInit, flags); - /** - * @brief The custom draw routines for a frame window - * @details These function may be passed to @p gwinSetCustomDraw() to get different frame drawing styles - * - * @param[in] gw The widget object (in this case a frame) - * @param[in] param A parameter passed in from the user - * - * @note In your own custom drawing function you may optionally call these - * standard functions and then draw your extra details on top. - * - * @note gwinFrameDraw_Std() will fill the client area with the background color.
- * gwinFrameDraw_Transparent() will not fill the client area at all.
- * gwinFrameDraw_Image() will tile the image throughout the client area.
- * All these drawing functions draw the frame itself the same way. - * - * @note The standard functions below ignore the param parameter except for @p gwinFrameDraw_Image(). - * @note The image custom draw function @p gwinFrameDraw_Image() uses param to pass in the gdispImage pointer. - * The image must be already opened before calling @p gwinSetCustomDraw(). - * - * @api - * @{ - */ - void gwinFrameDraw_Std(GWidgetObject *gw, void *param); - void gwinFrameDraw_Transparent(GWidgetObject *gw, void *param); - void gwinFrameDraw_Image(GWidgetObject *gw, void *param); - /** @} */ +/** + * @defgroup Renderings_Frame Frame rendering functions + * + * @brief Built-in rendering functions for the frame widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different frame drawing styles. + * + * @note In your custom frame drawing function you may optionally call these + * standard functions and then draw your extra details on top. + * @note These custom drawing routines don't have to worry about setting clipping as the framework + * sets clipping to the object window prior to calling these routines. + * + * @{ + */ + +/** + * @brief The default rendering function for the frame widget. + * + * @details Fills the client area with the background color. + * + * @param[in] gw The widget object (must be a frame widget). + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinFrameDraw_Std(GWidgetObject *gw, void *param); + +/** + * @brief Renders the frame widget with a transparent client area. + * + * @details Will not fill the client area at all. + * + * @param[in] gw The widget object (must be a frame object). + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @note The image custom draw function @p gwinFrameDraw_Image() uses param to pass in the gdispImage pointer. + * The image must be already opened before calling @p gwinSetCustomDraw(). + * + * @api + */ +void gwinFrameDraw_Transparent(GWidgetObject *gw, void *param); + +/** + * @brief Renders the frame widget and uses the specified image for the client area. + * + * @details The image will be tiled throghout the client area. Therefore, to archive the best looking result the + * supplied image needs to be of the same size as the client area size of the frame widget (inner size). + * + * @param[in] gw The widget object (must be a frame object). + * @param[in] param A parameter passed in from the user. Must be an image handle. See note below. + * + * @note The image must be already opened before calling @p gwinSetCustomDraw(). The handle is passed as the parameter + * to this function. + * + * @api + */ +void gwinFrameDraw_Image(GWidgetObject *gw, void *param); +/** @} */ #ifdef __cplusplus } diff --git a/src/gwin/gwin_keyboard.c b/src/gwin/gwin_keyboard.c index 70771d9b..75e06e64 100644 --- a/src/gwin/gwin_keyboard.c +++ b/src/gwin/gwin_keyboard.c @@ -301,7 +301,6 @@ static void SendKeyboardEvent(GKeyboardObject *gk) { #endif extern GVKeyTable GWIN_KEYBOARD_DEFAULT_LAYOUT; -void gwinKeyboardDraw_Normal(GWidgetObject *gw, void *param); // The button VMT table static const gwidgetVMT keyboardVMT = { diff --git a/src/gwin/gwin_keyboard.h b/src/gwin/gwin_keyboard.h index 66271265..39f09c88 100644 --- a/src/gwin/gwin_keyboard.h +++ b/src/gwin/gwin_keyboard.h @@ -101,6 +101,32 @@ GSourceHandle gwinKeyboardGetEventSource(GHandle gh); */ void gwinKeyboardSetLayout(GHandle gh, struct GVKeyTable *layout); +/** + * @defgroup Renderings_Keyboard Keyboard rendering functions + * + * @brief Built-in rendering functions for the keyboard widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different keyboard drawing styles. + * + * @note In your custom keyboard drawing function you may optionally call these + * standard functions and then draw your extra details on top. + * @note The built-in functions below ignore the param parameter. + * @note These custom drawing routines don't have to worry about setting clipping as the framework + * sets clipping to the object window prior to calling these routines. + * + * @{ + */ + +/** + * @brief The default rendering function for the keyboard widget + * + * @param[in] gw The widget object (must be a keyboard object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinKeyboardDraw_Normal(GWidgetObject *gw, void *param); + /** @} */ #ifdef __cplusplus diff --git a/src/gwin/gwin_label.c b/src/gwin/gwin_label.c index b78e4b3b..9b62679f 100644 --- a/src/gwin/gwin_label.c +++ b/src/gwin/gwin_label.c @@ -40,8 +40,6 @@ static coord_t getheight(const char *text, font_t font, coord_t maxwidth) { return gdispGetFontMetric(font, fontHeight); } -static void gwinLabelDefaultDraw(GWidgetObject *gw, void *param); - static const gwidgetVMT labelVMT = { { "Label", // The class name @@ -136,7 +134,7 @@ void gwinLabelSetBorder(GHandle gh, bool_t border) { } #endif // GWIN_LABEL_ATTRIBUTE -static void gwinLabelDefaultDraw(GWidgetObject *gw, void *param) { +void gwinLabelDefaultDraw(GWidgetObject *gw, void *param) { coord_t w, h; color_t c; (void) param; diff --git a/src/gwin/gwin_label.h b/src/gwin/gwin_label.h index 4c7cab9c..0123842b 100644 --- a/src/gwin/gwin_label.h +++ b/src/gwin/gwin_label.h @@ -100,6 +100,34 @@ void gwinLabelSetBorder(GHandle gh, bool_t border); void gwinLabelSetAttribute(GHandle gh, coord_t tab, const char* attr); #endif +/** + * @defgroup Renderings_Label Label rendering functions + * + * @brief Built-in rendering functions for the label widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different label drawing styles. + * + * @note In your custom label drawing function you may optionally call these + * standard functions and then draw your extra details on top. + * @note The built-in functions below ignore the param parameter. + * @note These custom drawing routines don't have to worry about setting clipping as the framework + * sets clipping to the object window prior to calling these routines. + * + * @{ + */ + +/** + * @brief The default rendering function for the label widget + * + * @param[in] gw The widget object (must be a label object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinLabelDefaultDraw(GWidgetObject *gw, void *param) + +/** @} */ + #ifdef __cplusplus } #endif diff --git a/src/gwin/gwin_list.c b/src/gwin/gwin_list.c index 88d3028a..a2ca8395 100644 --- a/src/gwin/gwin_list.c +++ b/src/gwin/gwin_list.c @@ -74,8 +74,6 @@ static void sendListEvent(GWidgetObject *gw, int item) { } } -static void gwinListDefaultDraw(GWidgetObject* gw, void* param); - #if GINPUT_NEED_MOUSE static void ListMouseSelect(GWidgetObject* gw, coord_t x, coord_t y) { const gfxQueueASyncItem* qi; @@ -657,7 +655,7 @@ void gwinListViewItem(GHandle gh, int item) { } #endif -static void gwinListDefaultDraw(GWidgetObject* gw, void* param) { +void gwinListDefaultDraw(GWidgetObject* gw, void* param) { (void)param; #if GDISP_NEED_CONVEX_POLYGON diff --git a/src/gwin/gwin_list.h b/src/gwin/gwin_list.h index 28506778..8e69aa5d 100644 --- a/src/gwin/gwin_list.h +++ b/src/gwin/gwin_list.h @@ -326,6 +326,33 @@ void gwinListViewItem(GHandle gh, int item); void gwinListItemSetImage(GHandle gh, int item, gdispImage *pimg); #endif +/** + * @defgroup Renderings_List List rendering functions + * + * @brief Built-in rendering functions for the list widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different list drawing styles. + * + * @note In your custom list drawing function you may optionally call these + * standard functions and then draw your extra details on top. + * @note These custom drawing routines don't have to worry about setting clipping as the framework + * sets clipping to the object window prior to calling these routines. + * + * @{ + */ + +/** + * @brief The default rendering function for the list widget + * + * @param[in] gw The widget object (must be a list object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinListDefaultDraw(GWidgetObject* gw, void* param); + +/** @} */ + #ifdef __cplusplus } #endif diff --git a/src/gwin/gwin_progressbar.h b/src/gwin/gwin_progressbar.h index 74890be3..7c28523c 100644 --- a/src/gwin/gwin_progressbar.h +++ b/src/gwin/gwin_progressbar.h @@ -176,29 +176,49 @@ void gwinProgressbarDecrement(GHandle gh); #endif /* GWIN_PROGRESSBAR_AUTO */ /** - * @brief Some custom progressbar drawing routines - * @details These function may be passed to @p gwinSetCustomDraw() to get different progressbar drawing styles + * @defgroup Renderings_Progressbar Progressbar rendering functions * - * @param[in] gw The widget (which must be a progressbar) - * @param[in] param A parameter passed in from the user + * @brief Built-in rendering functions for the progressbar widget. * - * @note In your custom progressbar drawing function you may optionally call this + * @details These function may be passed to @p gwinSetCustomDraw() to get different progressbar drawing styles. + * + * @note In your custom progressbar drawing function you may optionally call these * standard functions and then draw your extra details on top. - * @note The standard functions below ignore the param parameter except for @p gwinProgressbarDraw_Image(). - * @note The image custom draw function @p gwinProgressbarDraw_Image() uses param to pass in the gdispImage pointer. - * The image must be already opened before calling @p gwinSetCustomDraw(). The image is tiled to fill - * the active area of the progressbar. The normal colors apply to the border and inactive area and the dividing line - * between the active and inactive areas. - * No checking is done to compare the dimensions of the progressbar to the size of the image. - * Note text is drawn on top of the image. * @note These custom drawing routines don't have to worry about setting clipping as the framework * sets clipping to the object window prior to calling these routines. * - * @api * @{ */ + +/** + * @brief The default rendering function for the progressbar widget + * + * @param[in] gw The widget object (must be a progressbar object) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ void gwinProgressbarDraw_Std(GWidgetObject *gw, void *param); -void gwinProgressbarDraw_Image(GWidgetObject *gw, void *param); + +#if GDISP_NEED_IMAGE || defined(__DOXYGEN__) + /** + * @brief Renders a progressbar using an image. + * + * @param[in] gw The widget object (must be a progressbar handle) + * @param[in] param A parameter passed in from the user. Must be an image handle. See note below. + * + * @note The image must be already opened before calling @p gwinSetCustomDraw(). + * @note The image is tiled to fill the active area of the progressbar. The normal colors + * apply to the border and inactive area and the dividing line between the active + * and inactive areas. No checking is done to compare the dimensions of the progressbar + * to the size of the image. Note text is drawn on top of the image. + * + * @pre GDISP_NEED_IMAGE must be set to TRUE + * + * @api + */ + void gwinProgressbarDraw_Image(GWidgetObject *gw, void *param); +#endif /* GDISP_NEED_IMAGE */ /** @} */ #ifdef __cplusplus diff --git a/src/gwin/gwin_radio.h b/src/gwin/gwin_radio.h index d5c9c21a..41a565f0 100644 --- a/src/gwin/gwin_radio.h +++ b/src/gwin/gwin_radio.h @@ -116,24 +116,54 @@ bool_t gwinRadioIsPressed(GHandle gh); GHandle gwinRadioGetActive(uint16_t group); /** - * @brief Some custom radio button drawing routines - * @details These function may be passed to @p gwinSetCustomDraw() to get different radio button drawing styles + * @defgroup Renderings_Radiobutton RadioButton rendering functions * - * @param[in] gw The widget object (in this case a radio button) - * @param[in] param A parameter passed in from the user + * @brief Built-in rendering functions for the radiobutton widget. * - * @note In your custom radio drawing function you may optionally call these + * @details These function may be passed to @p gwinSetCustomDraw() to get different radiobutton drawing styles. + * + * @note In your custom radiobutton drawing function you may optionally call these * standard functions and then draw your extra details on top. - * @note The standard functions below ignore the param parameter. * @note These custom drawing routines don't have to worry about setting clipping as the framework * sets clipping to the object window prior to calling these routines. * - * @api * @{ */ -void gwinRadioDraw_Radio(GWidgetObject *gw, void *param); // @< A standard radio button -void gwinRadioDraw_Button(GWidgetObject *gw, void *param); // @< Draw as a button -void gwinRadioDraw_Tab(GWidgetObject *gw, void *param); // @< Draw as a tab + +/** + * @brief The default rendering function for the radiobutton widget + * + * @param[in] gw The widget object (must be a button radioobject) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinRadioDraw_Radio(GWidgetObject *gw, void *param); + +/** + * @brief Renders the radiobutton in form of a regular rectangular button + * + * @param[in] gw The widget object (must be a button radioobject) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinRadioDraw_Button(GWidgetObject *gw, void *param); + +/** + * @brief Used to render tabbed menus. + * + * @details Multiple radiobutton widgets can be placed right next to each other and be used to implement + * a tabbed menu using this rendering function. + * + * @note This exists for legacy reasons. Have a look at the @p Tabset widget instead. + * + * @param[in] gw The widget object (must be a button radioobject) + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinRadioDraw_Tab(GWidgetObject *gw, void *param); /** @} */ #ifdef __cplusplus diff --git a/src/gwin/gwin_slider.h b/src/gwin/gwin_slider.h index 91a381a5..969990b7 100644 --- a/src/gwin/gwin_slider.h +++ b/src/gwin/gwin_slider.h @@ -143,29 +143,50 @@ void gwinSliderSetPosition(GHandle gh, int pos); void gwinSliderSendExtendedEvents(GHandle gh, bool_t enabled); /** - * @brief Some custom slider drawing routines - * @details These function may be passed to @p gwinSetCustomDraw() to get different slider drawing styles + * @defgroup Renderings_Slider Slider rendering functions * - * @param[in] gw The widget (which must be a slider) - * @param[in] param A parameter passed in from the user + * @brief Built-in rendering functions for the slider widget. * - * @note In your custom slider drawing function you may optionally call this + * @details These function may be passed to @p gwinSetCustomDraw() to get different slider drawing styles. + * + * @note In your custom slider drawing function you may optionally call these * standard functions and then draw your extra details on top. - * @note The standard functions below ignore the param parameter except for @p gwinSliderDraw_Image(). - * @note The image custom draw function @p gwinSliderDraw_Image() uses param to pass in the gdispImage pointer. - * The image must be already opened before calling @p gwinSetCustomDraw(). The image is tiled to fill - * the active area of the slider. The normal colors apply to the border and inactive area and the dividing line - * between the active and inactive areas. - * No checking is done to compare the dimensions of the slider to the size of the image. - * Note text is drawn on top of the image. * @note These custom drawing routines don't have to worry about setting clipping as the framework * sets clipping to the object window prior to calling these routines. * - * @api * @{ */ + +/** + * @brief The default rendering function for the slider widget. + * + * @param[in] gw The widget object (must be a slider object). + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ void gwinSliderDraw_Std(GWidgetObject *gw, void *param); + +#if GDISP_NEED_IMAGE || defined(__DOXYGEN__) + /** + * @brief The default rendering function + * + * @param[in] gw The widget object (must be a slider object). + * @param[in] param A parameter passed in from the user. Must be an image handle. See note below. + * + * @note The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3 + * times the height of the button. The button image is repeated 3 times vertically, the first (top) for + * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If + * the disabled state is never going to be used then the image can be just 2 times the button height. + * No checking is done to compare the size of the button to the size of the image. + * No text is drawn on top of the image. + * + * @pre GDISP_NEED_IMAGE must be set to TRUE + * + * @api + */ void gwinSliderDraw_Image(GWidgetObject *gw, void *param); +#endif /* GDISP_NEED_IMAGE */ /** @} */ #ifdef __cplusplus diff --git a/src/gwin/gwin_textedit.c b/src/gwin/gwin_textedit.c index d3dafe83..e0470350 100644 --- a/src/gwin/gwin_textedit.c +++ b/src/gwin/gwin_textedit.c @@ -127,8 +127,6 @@ static bool_t resizeText(GWidgetObject* gw, size_t pos, int32_t diff) { } #endif -static void gwinTexteditDefaultDraw(GWidgetObject* gw, void* param); - static const gwidgetVMT texteditVMT = { { "TextEdit", // The class name @@ -196,7 +194,7 @@ GHandle gwinGTexteditCreate(GDisplay* g, GTexteditObject* wt, GWidgetInit* pInit return (GHandle)wt; } -static void gwinTexteditDefaultDraw(GWidgetObject* gw, void* param) +void gwinTexteditDefaultDraw(GWidgetObject* gw, void* param) { const char *p; coord_t cpos, tpos; diff --git a/src/gwin/gwin_textedit.h b/src/gwin/gwin_textedit.h index f39f0c2a..8b3336e2 100644 --- a/src/gwin/gwin_textedit.h +++ b/src/gwin/gwin_textedit.h @@ -60,6 +60,33 @@ extern "C" { GHandle gwinGTexteditCreate(GDisplay* g, GTexteditObject* wt, GWidgetInit* pInit, size_t maxSize); #define gwinTexteditCreate(wt, pInit, maxSize) gwinGTexteditCreate(GDISP, wt, pInit, maxSize) +/** + * @defgroup Renderings_Textedit Textedit rendering functions + * + * @brief Built-in rendering functions for the textedit widget. + * + * @details These function may be passed to @p gwinSetCustomDraw() to get different textedit drawing styles. + * + * @note In your custom textedit drawing function you may optionally call these + * standard functions and then draw your extra details on top. + * @note These custom drawing routines don't have to worry about setting clipping as the framework + * sets clipping to the object window prior to calling these routines. + * + * @{ + */ + +/** + * @brief The default rendering function for the textedit widget. + * + * @param[in] gw The widget object (must be a button textedit). + * @param[in] param A parameter passed in from the user. Ignored by this function. + * + * @api + */ +void gwinTexteditDefaultDraw(GWidgetObject* gw, void* param); + +/** @} */ + #ifdef __cplusplus } #endif