diff options
Diffstat (limited to 'include/gwin/button.h')
-rw-r--r-- | include/gwin/button.h | 240 |
1 files changed, 65 insertions, 175 deletions
diff --git a/include/gwin/button.h b/include/gwin/button.h index ed74a80d..1b0ff36b 100644 --- a/include/gwin/button.h +++ b/include/gwin/button.h @@ -24,240 +24,132 @@ #ifndef _GWIN_BUTTON_H #define _GWIN_BUTTON_H -#if GWIN_NEED_BUTTON || defined(__DOXYGEN__) +/* This file is included within "gwin/gwidget.h" */ -/*===========================================================================*/ -/* Driver constants. */ -/*===========================================================================*/ - -#define GW_BUTTON 0x0002 +/** + * @brief The Event Type for a Button Event + */ #define GEVENT_GWIN_BUTTON (GEVENT_GWIN_FIRST+0) -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ - -typedef struct GEventGWinButton_t { +/** + * @brief A Button Event + * @note There are currently no GEventGWinButton listening flags - use 0 as the flags to @p gwinAttachListener() + */ +typedef struct GEventGWinButton { GEventType type; // The type of this event (GEVENT_GWIN_BUTTON) GHandle button; // The button that has been depressed (actually triggered on release) } GEventGWinButton; -// There are currently no GEventGWinButton listening flags - use 0 - -typedef enum GButtonShape_e { - GBTN_3D, GBTN_SQUARE, GBTN_ROUNDED, GBTN_ELLIPSE, GBTN_CUSTOM, - GBTN_ARROW_UP, GBTN_ARROW_DOWN, GBTN_ARROW_LEFT, GBTN_ARROW_RIGHT, -} GButtonShape; - -typedef struct GButtonDrawStyle_t { +/** + * @brief Button colors + */ +typedef struct GButtonColors { color_t color_edge; color_t color_fill; color_t color_txt; -} GButtonDrawStyle; - -typedef enum GButtonType_e { - GBTN_NORMAL, GBTN_TOGGLE -} GButtonType; - -typedef enum GButtonState_e { - GBTN_UP, GBTN_DOWN -} GButtonState; +} GButtonColors; -typedef void (*GButtonDrawFunction)(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); - -// A button window +/** + * @brief The button widget structure + * @note Do not use the members directly - treat it as a black-box. + */ typedef struct GButtonObject_t { - GWindowObject gwin; - - GButtonDrawStyle up; - GButtonDrawStyle dn; - GButtonState state; - GButtonType type; - const char *txt; - GButtonDrawFunction fn; - void *param; - GListener listener; + GWidgetObject w; + GButtonColors c_up; + GButtonColors c_dn; + GButtonColors c_dis; } GButtonObject; -/*===========================================================================*/ -/* External declarations. */ -/*===========================================================================*/ - #ifdef __cplusplus extern "C" { #endif /** - * @brief Create a button window. + * @brief Create a button widget. * @return NULL if there is no resultant drawing area, otherwise a window handle. * * @param[in] gb The GButtonObject structure to initialise. If this is NULL the structure is dynamically allocated. - * @param[in] x,y The screen co-ordinates for the bottom left corner of the window + * @param[in] x,y The screen co-ordinates for the top left corner of the window * @param[in] width The width of the window * @param[in] height The height of the window - * @param[in] font The font to use - * @param[in] type The type of button + * * @note The drawing color gets set to White and the background drawing color to Black. + * @note Don't forget to set the font using @p gwinSetFont() or @p gwinSetDefaultFont() * @note The dimensions and position may be changed to fit on the real screen. - * @note The button is not automatically drawn. Call gwinButtonDraw() after changing the button style or setting the text. + * @note The button is not automatically drawn. Call gwinDraw() to draw it. * * @api */ -GHandle gwinCreateButton(GButtonObject *gb, coord_t x, coord_t y, coord_t width, coord_t height, font_t font, GButtonType type); +GHandle gwinCreateButton(GButtonObject *gb, coord_t x, coord_t y, coord_t width, coord_t height); /** - * @brief Set the style of a button. - * @details The button style is defined by its shape and colours. + * @brief Set the colors of a button. * - * @param[in] gh The window handle (must be a button window) - * @param[in] shape The shape of the button. - * @param[in] pUp The styling for the button when in the up state. - * @param[in] pDown The styling for the button when in the down state. + * @param[in] gh The window handle (must be a button widget) + * @param[in] pUp The colors for the button when in the up state. + * @param[in] pDown The colors for the button when in the down state. + * @param[in] pDisabled The colors for the button when it is disabled. * * @note The button is not automatically redrawn. Call gwinButtonDraw() after changing the button style * @note The button style is copied into the internal button structure - there is no need to - * maintain a static style structures. - * @note The pUp and pDown parameters can be NULL. If they are then the existing color styles + * maintain static style structures (they can be temporary structures on the stack). + * @note The pUp, pDown and pDisabled parameters can be NULL. If they are then the existing color styles * are not changed for that button state. + * @note Some custom drawn buttons will ignore he specified colors * * @api */ -void gwinSetButtonStyle(GHandle gh, GButtonShape shape, const GButtonDrawStyle *pUp, const GButtonDrawStyle *pDown); - -/** - * @brief Set the text of a button. - * - * @param[in] gh The window handle (must be a button window) - * @param[in] txt The button text to set. This must be a constant string unless useAlloc is set. - * @param[in] useAlloc If TRUE the string specified will be copied into dynamically allocated memory. - * @note The button is not automatically redrawn. Call gwinButtonDraw() after changing the button text. - * - * @api - */ -void gwinSetButtonText(GHandle gh, const char *txt, bool_t useAlloc); - -/** - * @brief Redraw the button. - * - * @param[in] gh The window handle (must be a button window) - * - * @api - */ -void gwinButtonDraw(GHandle gh); - -/** - * @brief Enable or disable a button - * - * @param[in] gh The window handle (must be a button window) - * @param[in] enabled Enable or disable the button - * - * @api - */ -void gwinButtonSetEnabled(GHandle gh, bool_t enabled); - -/** - * @brief Set the callback routine to perform a custom button drawing. - * - * @param[in] gh The window handle (must be a button window) - * @param[in] fn The function to use to draw the button - * @param[in] param A parameter to pass to the button drawing function - * - * @api - */ -void gwinSetButtonCustom(GHandle gh, GButtonDrawFunction fn, void *param); - -/** - * @brief Enable a button - * - * @api - */ -#define gwinEnableButton(gh) gwinButtonSetEnabled( ((GButtonObject *)(gh)), TRUE) - -/** - * @brief Disable a button - * - * @api - */ -#define gwinDisableButton(gh) gwinButtonSetEnabled( ((GButtonObject *)(gh)), FALSE) - -/** - * @brief Get the state of a button - * - * @param[in] gh The window handle (must be a button window) - * - * @api - */ -#define gwinGetButtonState(gh) (((GButtonObject *)(gh))->state) +void gwinSetButtonColors(GHandle gh, const GButtonColors *pUp, const GButtonColors *pDown, const GButtonColors *pDisabled); /** - * @brief Get the source handle of a button - * @details Get the source handle of a button so the application can listen for events + * @brief Is the button current pressed + * @return TRUE if the button is depressed * - * @param[in] gh The window handle + * @param[in] gh The window handle (must be a button widget) * * @api */ -#define gwinGetButtonSource(gh) ((GSourceHandle)(gh)) - -#if GFX_USE_GINPUT && GINPUT_NEED_MOUSE - /** - * @brief Attach a mouse to a button - * - * @param[in] gh The button handle - * @param[in] instance The mouse instance - * - * @api - */ - bool_t gwinAttachButtonMouse(GHandle gh, uint16_t instance); -#endif - -#if GFX_USE_GINPUT && GINPUT_NEED_TOGGLE - /** - * @brief Attach a toggle to a button - * - * @param[in] gh The button handle - * @param[in] instance The toggle instance - * - * @api - */ - bool_t gwinAttachButtonToggle(GHandle gh, uint16_t instance); -#endif +bool_t gwinIsButtonPressed(GHandle gh); /** - * @brief Standard button drawing routines - * @details These routines are called to draw the standard button styles. + * @brief Some custom button drawing routines + * @details These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles * - * @param[in] gh The button handle - * @param[in] enabled Is the button currently enabled or disabled - * @param[in] isdown Is the button currently down (depressed) - * @param[in] txt The text to be display inside the button - * @param[in] pstyle The current drawing style for the state we are in + * @param[in] gw The widget object (in this case a button) * @param[in] param A parameter passed in from the user * * @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. It is there - * only to ensure the functions match the GButtonDrawFunction type. - * @note When called by a button press/release the framework ensure that it is - * a button object and sets up clipping to the button object window. These - * drawing routines then don't have to worry about explicitly doing that. + * @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_3D(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); -void gwinButtonDraw_Square(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); +void gwinButtonDraw_3D(GWidgetObject *gw, void *param); // @< A standard 3D button +void gwinButtonDraw_Box(GWidgetObject *gw, void *param); // @< A very simple box style button #if GDISP_NEED_ARC || defined(__DOXYGEN__) - void gwinButtonDraw_Rounded(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); + void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param); // @< A rounded rectangle button #endif #if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__) - void gwinButtonDraw_Ellipse(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); + void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param); // @< A circular button #endif #if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__) - void gwinButtonDraw_ArrowUp(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); - void gwinButtonDraw_ArrowDown(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); - void gwinButtonDraw_ArrowLeft(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); - void gwinButtonDraw_ArrowRight(GHandle gh, bool_t enabled, bool_t isdown, const char *txt, const GButtonDrawStyle *pstyle, void *param); + 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 +#endif +#if GDISP_NEED_IMAGE || defined(__DOXYGEN__) + void gwinButtonDraw_Image(GWidgetObject *gw, void *param); // @< An image button - see the notes above on the param. #endif /** @} */ @@ -265,8 +157,6 @@ void gwinButtonDraw_Square(GHandle gh, bool_t enabled, bool_t isdown, const char } #endif -#endif /* GWIN_NEED_BUTTON */ - #endif /* _GWIN_BUTTON_H */ /** @} */ |