From 86aef5990a702cc10c99d41c8aa7cc15b3338cae Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Tue, 3 Nov 2015 20:39:16 +0100 Subject: Doxygen (documenting each built-in rendering function for widgets) --- src/gwin/gwin_button.h | 124 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 105 insertions(+), 19 deletions(-) (limited to 'src/gwin/gwin_button.h') 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 /** @} */ -- cgit v1.2.3