diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/gfx_rules.h | 41 | ||||
| -rw-r--r-- | include/ginput/dial.h | 1 | ||||
| -rw-r--r-- | include/gqueue/gqueue.h | 44 | ||||
| -rw-r--r-- | include/gwin/button.h | 252 | ||||
| -rw-r--r-- | include/gwin/checkbox.h | 135 | ||||
| -rw-r--r-- | include/gwin/class_gwin.h | 191 | ||||
| -rw-r--r-- | include/gwin/console.h | 46 | ||||
| -rw-r--r-- | include/gwin/graph.h | 34 | ||||
| -rw-r--r-- | include/gwin/gwidget.h | 213 | ||||
| -rw-r--r-- | include/gwin/gwin.h | 969 | ||||
| -rw-r--r-- | include/gwin/internal.h | 41 | ||||
| -rw-r--r-- | include/gwin/options.h | 38 | ||||
| -rw-r--r-- | include/gwin/slider.h | 171 |
13 files changed, 1282 insertions, 894 deletions
diff --git a/include/gfx_rules.h b/include/gfx_rules.h index 95874736..dfabe728 100644 --- a/include/gfx_rules.h +++ b/include/gfx_rules.h @@ -46,31 +46,50 @@ #warning "GWIN: Drawing can occur outside the defined windows as GDISP_NEED_CLIP is FALSE" #endif #endif - #if GWIN_NEED_BUTTON - #if !GDISP_NEED_TEXT - #error "GWIN: GDISP_NEED_TEXT is required if GWIN_NEED_BUTTON is TRUE." - #endif - #if !GFX_USE_GEVENT + #if GWIN_NEED_BUTTON || GWIN_NEED_SLIDER || GWIN_NEED_CHECKBOX + #if !GWIN_NEED_WIDGET #if GFX_DISPLAY_RULE_WARNINGS - #warning "GWIN: GFX_USE_GEVENT is required if GWIN_NEED_BUTTON is TRUE. It has been turned on for you." + #warning "GWIN: GWIN_NEED_WIDGET is required when a Widget is used. It has been turned on for you." #endif - #undef GFX_USE_GEVENT - #define GFX_USE_GEVENT TRUE + #undef GWIN_NEED_WIDGET + #define GWIN_NEED_WIDGET TRUE + #endif + #endif + #if GWIN_NEED_WIDGET + #if !GDISP_NEED_TEXT + #error "GWIN: GDISP_NEED_TEXT is required if GWIN_NEED_WIDGET is TRUE." #endif - #if !GFX_USE_GINPUT || !(GINPUT_NEED_MOUSE || GINPUT_NEED_TOGGLE) + #if !GFX_USE_GINPUT + // This test also ensures that GFX_USE_GEVENT is set + #error "GWIN: GFX_USE_GINPUT (and one or more input sources) is required if GWIN_NEED_WIDGET is TRUE" + #endif + #if !GWIN_NEED_WINDOWMANAGER #if GFX_DISPLAY_RULE_WARNINGS - #warning "GWIN: You have set GWIN_NEED_BUTTON to TRUE but no supported GINPUT (mouse/toggle) devices have been included" + #warning "GWIN: GWIN_NEED_WINDOWMANAGER is required if GWIN_NEED_WIDGET is TRUE. It has been turned on for you." #endif + #undef GWIN_NEED_WINDOWMANAGER + #define GWIN_NEED_WINDOWMANAGER TRUE #endif #if !GDISP_NEED_MULTITHREAD && !GDISP_NEED_ASYNC #if GFX_DISPLAY_RULE_WARNINGS - #warning "GWIN: Either GDISP_NEED_MULTITHREAD or GDISP_NEED_ASYNC is required if GWIN_NEED_BUTTON is TRUE." + #warning "GWIN: Either GDISP_NEED_MULTITHREAD or GDISP_NEED_ASYNC is required if GWIN_NEED_WIDGET is TRUE." #warning "GWIN: GDISP_NEED_MULTITHREAD has been turned on for you." #endif #undef GDISP_NEED_MULTITHREAD #define GDISP_NEED_MULTITHREAD TRUE #endif #endif + #if GWIN_NEED_WINDOWMANAGER + #if !GFX_USE_GQUEUE || !GQUEUE_NEED_ASYNC + #if GFX_DISPLAY_RULE_WARNINGS + #warning "GWIN: GFX_USE_GQUEUE and GQUEUE_NEED_ASYNC is required if GWIN_NEED_WINDOWMANAGER is TRUE. It has been turned on for you." + #endif + #undef GFX_USE_GQUEUE + #undef GQUEUE_NEED_ASYNC + #define GFX_USE_GQUEUE TRUE + #define GQUEUE_NEED_ASYNC TRUE + #endif + #endif #if GWIN_NEED_CONSOLE #if !GDISP_NEED_TEXT #error "GWIN: GDISP_NEED_TEXT is required if GWIN_NEED_CONSOLE is TRUE." diff --git a/include/ginput/dial.h b/include/ginput/dial.h index 19395789..38568994 100644 --- a/include/ginput/dial.h +++ b/include/ginput/dial.h @@ -36,6 +36,7 @@ typedef struct GEventDial_t { GEventType type; // The type of this event (GEVENT_DIAL) uint16_t instance; // The dial instance uint16_t value; // The dial value + uint16_t maxvalue; // The maximum dial value } GEventDial; /*===========================================================================*/ diff --git a/include/gqueue/gqueue.h b/include/gqueue/gqueue.h index 0f8f83ea..8ec3c9b9 100644 --- a/include/gqueue/gqueue.h +++ b/include/gqueue/gqueue.h @@ -91,7 +91,7 @@ void gfxQueueFSyncInit(gfxQueueFSync *pqueue); /* @} */ /** - * @brief Get an item from the head of the queue. + * @brief Get an item from the head of the queue (and remove it from the queue). * @return NULL if the timeout expires before an item is available * * @param[in] pqueue A pointer to the queue @@ -127,7 +127,7 @@ bool_t gfxQueueFSyncPut(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delayti /* @} */ /** - * @brief Pop an item from the head of the queue. + * @brief Pop an item from the head of the queue (and remove it from the queue). * @detail This is exactly the same as the Get operation above. * * @api @@ -208,6 +208,46 @@ bool_t gfxQueueGSyncIsIn(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem); bool_t gfxQueueFSyncIsIn(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem); /* @} */ +/** + * @brief Get the first item from the head of the queue but do not remove it from the queue. + * @return NULL if no item is available. + * + * @param[in] pqueue A pointer to the queue + * + * @note This call does not block. + * @note This can be used as the first call to iterate all the elements in the queue. + * @note As that item is still on the queue, it should be treated as read-only. It could + * also be removed from the queue at any time by another thread (thereby altering the + * queue item). + * + * @api + * @{ + */ +#define gfxQueueASyncPeek(pqueue) ((const gfxQueueASyncItem *)((pqueue)->head)) +#define gfxQueueGSyncPeek(pqueue) ((const gfxQueueGSyncItem *)((pqueue)->head)) +#define gfxQueueFSyncPeek(pqueue) ((const gfxQueueFSyncItem *)((pqueue)->head)) +/* @} */ + +/** + * @brief Get the next item in the queue (but do not remove it from the queue). + * @return NULL if no item is available. + * + * @param[in] pitem The previous item in the queue + * + * @note This call does not block. + * @note This can be used as subsequent calls to iterate all the elements in the queue. + * @note As that item is still on the queue, it should be treated as read-only. It could + * also be removed from the queue at any time by another thread (thereby altering the + * queue item). + * + * @api + * @{ + */ +#define gfxQueueASyncNext(pitem) ((const gfxQueueASyncItem *)((pitem)->next)) +#define gfxQueueGSyncNext(pitem) ((const gfxQueueGSyncItem *)((pitem)->next)) +#define gfxQueueFSyncNext(pitem) ((const gfxQueueFSyncItem *)((pitem)->next)) +/* @} */ + #ifdef __cplusplus } #endif diff --git a/include/gwin/button.h b/include/gwin/button.h index 84994dc4..a6b19333 100644 --- a/include/gwin/button.h +++ b/include/gwin/button.h @@ -24,240 +24,136 @@ #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; + uint16_t toggle; + 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] 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 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. + * @param[in] pInit The initialisation parameters + * + * @note The drawing color and the background color get set to the current defaults. If you haven't called + * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively. + * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there + * is no default font and text drawing operations will no nothing. + * @note A button remembers its normal drawing state. If there is a window manager then it is automatically + * redrawn if the window is moved or its visibility state is changed. + * @note A button supports mouse and a toggle input. + * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will + * forget the previous toggle. When assigning a toggle the role parameter must be 0. * * @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, GWidgetInit *pInit); /** - * @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); +void gwinSetButtonColors(GHandle gh, const GButtonColors *pUp, const GButtonColors *pDown, const GButtonColors *pDisabled); /** - * @brief Enable or disable a button + * @brief Is the button current pressed + * @return TRUE if the button is depressed * - * @param[in] gh The window handle (must be a button window) - * @param[in] enabled Enable or disable the button + * @param[in] gh The window handle (must be a button widget) * * @api */ -void gwinButtonSetEnabled(GHandle gh, bool_t enabled); +bool_t gwinIsButtonPressed(GHandle gh); /** - * @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 + * @brief Some custom button drawing routines + * @details These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles * - * @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) - -/** - * @brief Get the source handle of a button - * @details Get the source handle of a button so the application can listen for events - * - * @param[in] gh The window handle - * - * @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 - -/** - * @brief Standard button drawing routines - * @details These routines are called to draw the standard button 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 +161,6 @@ void gwinButtonDraw_Square(GHandle gh, bool_t enabled, bool_t isdown, const char } #endif -#endif /* GWIN_NEED_BUTTON */ - #endif /* _GWIN_BUTTON_H */ /** @} */ diff --git a/include/gwin/checkbox.h b/include/gwin/checkbox.h index a17fb1ed..9a19a2e1 100644 --- a/include/gwin/checkbox.h +++ b/include/gwin/checkbox.h @@ -12,7 +12,7 @@ * @defgroup Checkbox Checkbox * @ingroup GWIN * - * @details GWIN allows it to easily create checkboxes. + * @details GWIN allows it to easily create a group of checkbox buttons. * * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h * @pre GWIN_NEED_CHECKBOX must be set to TRUE in your gfxconf.h @@ -22,13 +22,12 @@ #ifndef _GWIN_CHECKBOX_H #define _GWIN_CHECKBOX_H -#if GWIN_NEED_CHECKBOX || defined(__DOXYGEN__) +/* This file is included within "gwin/gwidget.h" */ /*===========================================================================*/ /* Driver constants. */ /*===========================================================================*/ -#define GW_CHECKBOX 0x0005 #define GEVENT_GWIN_CHECKBOX (GEVENT_GWIN_FIRST+2) /*===========================================================================*/ @@ -41,124 +40,80 @@ typedef struct GEventGWinCheckbox_t { bool_t isChecked; // Is the checkbox currently checked or unchecked? } GEventGWinCheckbox; -typedef enum GCheckboxState_e { - GCHBX_UNCHECKED, GCHBX_CHECKED -} GCheckboxState; - -typedef struct GCheckboxColor_t { - color_t border; - color_t checked; - color_t bg; -} GCheckboxColor; - -/* custom rendering interface */ -typedef void (*GCheckboxDrawFunction)(GHandle gh, bool_t enabled, bool_t state, void* param); +typedef struct GCheckboxColors { + color_t color_border; + color_t color_checked; + color_t color_bg; + color_t color_txt; +} GCheckboxColors; /* A Checkbox window */ typedef struct GCheckboxObject_t { - GWindowObject gwin; - GListener listener; - - GCheckboxDrawFunction fn; - GCheckboxColor *colors; - bool_t isChecked; - void *param; + GWidgetObject w; + uint16_t toggle; + GCheckboxColors c; } GCheckboxObject; /** - * @brief Create a checkbox window. - * - * @param[in] gb The GCheckboxObject 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] width The width of the window - * @param[in] height The height of the window - * - * @note The checkbox is not automatically drawn. Call gwinCheckboxDraw() after changing the checkbox style. - * + * @brief Create a checkbox window. * @return NULL if there is no resultant drawing area, otherwise a window handle. * - * @api - */ -GHandle gwinCheckboxCreate(GCheckboxObject *gb, coord_t x, coord_t y, coord_t width, coord_t height); - -/** - * @brief Redraw a checkbox - * - * @param[in] gh The window handle (must be a checkbox window) + * @param[in] gb The GCheckboxObject structure to initialise. If this is NULL, the structure is dynamically allocated. + * @param[in] pInit The initialization parameters to use + * + * @note The drawing color and the background color get set to the current defaults. If you haven't called + * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively. + * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there + * is no default font and text drawing operations will no nothing. + * @note A checkbox remembers its normal drawing state. If there is a window manager then it is automatically + * redrawn if the window is moved or its visibility state is changed. + * @note A checkbox supports mouse and a toggle input. + * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will + * forget the previous toggle. When assigning a toggle the role parameter must be 0. * * @api */ -void gwinCheckboxDraw(GHandle gh); +GHandle gwinCreateCheckbox(GCheckboxObject *gb, GWidgetInit *pInit); /** - * @brief Enable or disable a button + * @brief Get the state of a checkbox + * @return TRUE if the checkbox is currently checked * - * @param[in] gh The window handle (must be a checkbox window) - * @param[in] enabled Enable or disable the button + * @param[in] gh The window handle (must be a checkbox window) * * @api */ -void gwinCheckboxSetEnabled(GHandle gh, bool_t enabled); +bool_t gwinIsCheckboxChecked(GHandle gh); /** - * @brief Set the callback routine to perform a custom drawing. + * @brief Set the colors used to draw the checkbox * * @param[in] gh The window handle (must be a checkbox window) - * @param[in] fn The function to use to draw the checkbox - * @param[in] param A parameter to pass to the checkbox drawing function - * - * @api - */ -void gwinCheckboxSetCustom(GHandle gh, GCheckboxDrawFunction fn, void *param); - -/** - * @brief Enable a checkbox + * @param[in] pColors The colors to use * * @api */ -#define gwinCheckboxEnable(gh) gwinCheckboxSetEnabled( ((GCheckboxObject *)(gh)), TRUE) - -/** - * @brief Disable a checkbox - * - * @api -*/ -#define gwinCheckboxDisable(gh) gwinCheckboxSetEnabled( ((GCheckboxObject *)(gh)), FALSE) +void gwinCheckboxSetColors(GHandle gh, GCheckboxColors *pColors); /** - * @brief Get the state of a checkbox + * @brief Some custom checkbox drawing routines + * @details These function may be passed to @p gwinSetCustomDraw() to get different checkbox drawing styles * - * @param[in] gh The window handle (must be a checkbox window) + * @param[in] gw The widget (which must be a checkbox) + * @param[in] param A parameter passed in from the user * - * @return The state of the checkbox (GCHBX_CHECKED or GCHBX_UNCHECKED) - * - * @api - */ -#define gwinCheckboxGetState(gh) (((GCheckboxObject *)(gh))->isChecked) - -/** - * @brief Get the source handle of a checkbox - * @details Get the source handle of a checkbox so the application can listen for events - * - * @param[in] gh The window handle (must be a checkbox window) + * @note In your custom checkbox drawing function you may optionally call this + * 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 + * @{ */ -#define gwinCheckboxGetSource(gh) ((GSourceHandle)(gh)) - -#if GFX_USE_GINPUT && GINPUT_NEED_MOUSE - /** - * @brief Attach a mouse to a checkbox - * - * @param[in] gh The checkbox handle - * @param[in] instance The mouse instance - * - * @api - */ - bool_t gwinCheckboxAttachMouse(GHandle gh, uint16_t instance); -#endif /* GFX_USE_GINPUT && GINPUT_NEED_MOUSE */ - -#endif /* _GWIN_NEED_CHECKBOX */ +void gwinCheckboxDraw_CheckOnLeft(GWidgetObject *gw, void *param); +void gwinCheckboxDraw_CheckOnRight(GWidgetObject *gw, void *param); +/* @} */ #endif /* _GWIN_CHECKBOX_H */ /** @} */ diff --git a/include/gwin/class_gwin.h b/include/gwin/class_gwin.h new file mode 100644 index 00000000..c3d2ee36 --- /dev/null +++ b/include/gwin/class_gwin.h @@ -0,0 +1,191 @@ +/* + * This file is subject to the terms of the GFX License. If a copy of + * the license was not distributed with this file, you can obtain one at: + * + * http://chibios-gfx.com/license.html + */ + +/** + * @file include/gwin/class_gwin.h + * @brief GWIN Graphic window subsystem header file. + * + * @defgroup Internal Internal + * @ingroup GWIN + * + * @note These definitions are normally not used by an application program. They are useful + * only if you want to create your own custom GWIN window or widget. + * @note To access these definitions you must include "gwin/class_gwin.h" in your source file. + * + * @{ + */ +#ifndef _CLASS_GWIN_H +#define _CLASS_GWIN_H + +#if GFX_USE_GWIN || defined(__DOXYGEN__) + +/** + * @brief The predefined flags for a Window + * @{ + */ +#define GWIN_FLG_DYNAMIC 0x0001 // @< The GWIN structure is allocated +#define GWIN_FLG_VISIBLE 0x0002 // @< The window is visible +#define GWIN_FLG_MINIMIZED 0x0004 // @< The window is minimized +#define GWIN_FLG_MAXIMIZED 0x0008 // @< The window is maximized +#define GWIN_FLG_WIDGET 0x0010 // @< This is a widget +#define GWIN_FLG_ENABLED 0x0020 // @< The widget is enabled +#define GWIN_FLG_ALLOCTXT 0x0040 // @< The widget text is allocated +#define GWIN_FLG_MOUSECAPTURE 0x0080 // @< The widget has captured the mouse +#define GWIN_FIRST_WM_FLAG 0x0100 // @< 4 bits free for the window manager to use +#define GWIN_FIRST_CONTROL_FLAG 0x1000 // @< 4 bits free for Windows and Widgets to use +/* @} */ + +/** + * @brief The Virtual Method Table for a GWIN window + * @{ + */ +typedef struct gwinVMT { + const char * classname; // @< The GWIN classname (mandatory) + size_t size; // @< The size of the class object + void (*Destroy) (GWindowObject *gh); // @< The GWIN destroy function (optional) + void (*Redraw) (GWindowObject *gh); // @< The GWIN redraw routine (optional) + void (*AfterClear) (GWindowObject *gh); // @< The GWIN after-clear function (optional) +} gwinVMT; +/* @} */ + +#if GWIN_NEED_WIDGET || defined(__DOXYGEN__) + + /** + * @brief An toggle/dial instance is not being used + */ + #define GWIDGET_NO_INSTANCE ((uint16_t)-1) + + /** + * @brief The source handle that widgets use when sending events + */ + #define GWIDGET_SOURCE ((GSourceHandle)(void *)_gwidgetCreate) + + /** + * @brief The Virtual Method Table for a widget + * @note A widget must have a destroy function. Either use @p _gwidgetDestroy() or use your own function + * which internally calls @p _gwidgetDestroy(). + * @note A widget must have a redraw function. Use @p _gwidgetRedraw(). + * @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified. + * @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified. + * @{ + */ + typedef struct gwidgetVMT { + struct gwinVMT g; // @< This is still a GWIN + void (*DefaultDraw) (GWidgetObject *gw, void *param); // @< The default drawing routine (mandatory) + struct { + void (*MouseDown) (GWidgetObject *gw, coord_t x, coord_t y); // @< Process mouse down events (optional) + void (*MouseUp) (GWidgetObject *gw, coord_t x, coord_t y); // @< Process mouse up events (optional) + void (*MouseMove) (GWidgetObject *gw, coord_t x, coord_t y); // @< Process mouse move events (optional) + }; + struct { + uint16_t toggleroles; // @< The roles supported for toggles (0->toggleroles-1) + void (*ToggleAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); // @< Assign a toggle to a role (optional) + uint16_t (*ToggleGet) (GWidgetObject *gw, uint16_t role); // @< Return the instance for a particular role (optional) + void (*ToggleOff) (GWidgetObject *gw, uint16_t role); // @< Process toggle off events (optional) + void (*ToggleOn) (GWidgetObject *gw, uint16_t role); // @< Process toggle on events (optional) + }; + struct { + uint16_t dialroles; // @< The roles supported for dials (0->dialroles-1) + void (*DialAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); // @< Test the role and save the dial instance handle (optional) + uint16_t (*DialGet) (GWidgetObject *gw, uint16_t role); // @< Return the instance for a particular role (optional) + void (*DialMove) (GWidgetObject *gw, uint16_t role, uint16_t value, uint16_t max); // @< Process dial move events (optional) + }; + } gwidgetVMT; + /* @} */ +#endif + +#if GWIN_NEED_WINDOWMANAGER || defined(__DOXYGEN__) + #if 1 // When we know that wmq is the first element of the GWindowObject structure + #define QItem2GWindow(qi) ((GHandle)qi) + #else + #define QItem2GWindow(qi) ((GHandle)(((char *)(qi)) - (size_t)(&(((GWindowObject *)0)->wmq)))) + #endif + + // @note There is only ever one instance of each GWindowManager type + typedef struct GWindowManager { + const struct gwmVMT *vmt; + } GWindowManager; + + /** + * @brief The Virtual Method Table for a window manager + * @{ + */ + typedef struct gwmVMT { + void (*Init) (void); // @< The window manager has just been set as the current window manager + void (*DeInit) (void); // @< The window manager has just been removed as the current window manager + bool_t (*Add) (GHandle gh, GWindowInit *pInit); // @< A window has been added + void (*Delete) (GHandle gh); // @< A window has been deleted + void (*Visible) (GHandle gh); // @< A window has changed its visibility state + void (*Redim) (GHandle gh, coord_t x, coord_t y, coord_t w, coord_t h); // @< A window wants to be moved or resized + void (*Raise) (GHandle gh); // @< A window wants to be on top + void (*MinMax) (GHandle gh, GWindowMinMax minmax); // @< A window wants to be minimized/maximised + } gwmVMT; + /* @} */ + + /** + * @brief The list of all windows in the system + */ + extern gfxQueueASync _GWINList; +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Initialise (and allocate if necessary) the base GWIN object + * + * @param[in] pgw The GWindowObject structure. If NULL one is allocated from the heap + * @param[in] pInit The user initialization parameters + * @param[in] vmt The virtual method table for the GWIN object + * @param[in] flags The default flags to use + * + * @notapi + */ +GHandle _gwindowCreate(GWindowObject *pgw, GWindowInit *pInit, const gwinVMT *vmt, uint16_t flags); + +#if GWIN_NEED_WIDGET || defined(__DOXYGEN__) + /** + * @brief Initialise (and allocate if necessary) the base Widget object + * + * @param[in] pgw The GWidgetObject structure. If NULL one is allocated from the heap + * @param[in] x, y The top left corner of the Widget relative to the screen + * @param[in] w, h The width and height of the Widget window + * @param[in] size The size of the Widget object to allocate + * @param[in] vmt The virtual method table for the Widget object + * + * @notapi + */ + GHandle _gwidgetCreate(GWidgetObject *pgw, GWidgetInit *pInit, const gwidgetVMT *vmt); + + /** + * @brief Destroy the Widget object + * + * @param[in] gh The widget to destroy + * + * @notapi + */ + void _gwidgetDestroy(GHandle gh); + + /** + * @brief Redraw the Widget object + * + * @param[in] gh The widget to redraw + * + * @notapi + */ + void _gwidgetRedraw(GHandle gh); +#endif + +#ifdef __cplusplus +} +#endif + +#endif /* GFX_USE_GWIN */ + +#endif /* _CLASS_GWIN_H */ +/** @} */ diff --git a/include/gwin/console.h b/include/gwin/console.h index 9ea3eed6..38c88f63 100644 --- a/include/gwin/console.h +++ b/include/gwin/console.h @@ -24,22 +24,13 @@ #ifndef _GWIN_CONSOLE_H #define _GWIN_CONSOLE_H -#if GWIN_NEED_CONSOLE || defined(__DOXYGEN__) - -/*===========================================================================*/ -/* Driver constants. */ -/*===========================================================================*/ - -#define GW_CONSOLE 0x0001 - -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ +/* This file is included within "gwin/gwin.h" */ // A console window. Supports wrapped text writing and a cursor. typedef struct GConsoleObject_t { - GWindowObject gwin; - + GWindowObject g; + coord_t cx, cy; // Cursor position + #if GFX_USE_OS_CHIBIOS && GWIN_CONSOLE_USE_BASESTREAM struct GConsoleWindowStream_t { const struct GConsoleWindowVMT_t *vmt; @@ -47,15 +38,8 @@ typedef struct GConsoleObject_t { } stream; #endif - coord_t cx,cy; // Cursor position - uint8_t fy; // Current font height - uint8_t fp; // Current font inter-character spacing } GConsoleObject; -/*===========================================================================*/ -/* External declarations. */ -/*===========================================================================*/ - #ifdef __cplusplus extern "C" { #endif @@ -67,18 +51,20 @@ extern "C" { * @return NULL if there is no resultant drawing area, otherwise a window handle. * * @param[in] gc The GConsoleObject 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] width The width of the window - * @param[in] height The height of the window - * @param[in] font The font to use - * @note The console is not automatically cleared on creation. You must do that by calling gwinClear() (possibly after changing your background color) - * @note If the dispay does not support scrolling, the window will be cleared when the bottom line is reached. - * @note The default drawing color gets set to White and the background drawing color to Black. - * @note The dimensions and position may be changed to fit on the real screen. + * @param[in] pInit The initialization parameters to use + * + * @note The drawing color and the background color get set to the current defaults. If you haven't called + * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively. + * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there + * is no default font and text drawing operations will no nothing. + * @note On creation even if the window is visible it is not automatically cleared. + * You may do that by calling @p gwinClear() (possibly after changing your background color) + * @note A console does not save the drawing state. It is not automatically redrawn if the window is moved or + * its visibility state is changed. * * @api */ -GHandle gwinCreateConsole(GConsoleObject *gc, coord_t x, coord_t y, coord_t width, coord_t height, font_t font); +GHandle gwinCreateConsole(GConsoleObject *gc, GWindowInit *pInit); #if GFX_USE_OS_CHIBIOS && GWIN_CONSOLE_USE_BASESTREAM /** @@ -157,7 +143,5 @@ void gwinPrintf(GHandle gh, const char *fmt, ...); } #endif -#endif /* GWIN_NEED_CONSOLE */ - #endif /* _GWIN_CONSOLE_H */ /** @} */ diff --git a/include/gwin/graph.h b/include/gwin/graph.h index e307187c..5e6abee1 100644 --- a/include/gwin/graph.h +++ b/include/gwin/graph.h @@ -22,20 +22,7 @@ #ifndef _GWIN_GRAPH_H #define _GWIN_GRAPH_H -#if GWIN_NEED_GRAPH || defined(__DOXYGEN__) - -/*===========================================================================*/ -/* Driver constants. */ -/*===========================================================================*/ - -#define GW_GRAPH 0x0003 - -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ - -// GDISP now has its own point structure -#define GGraphPoint point +/* This file is included within "gwin/gwin.h" */ typedef enum GGraphPointType_e { GGRAPH_POINT_NONE, GGRAPH_POINT_DOT, GGRAPH_POINT_SQUARE, GGRAPH_POINT_CIRCLE @@ -85,7 +72,7 @@ typedef struct GGraphStyle_t { // A graph window typedef struct GGraphObject_t { - GWindowObject gwin; + GWindowObject g; GGraphStyle style; coord_t xorigin, yorigin; coord_t lastx, lasty; @@ -104,10 +91,15 @@ extern "C" { * @return NULL if there is no resultant drawing area, otherwise a window handle. * * @param[in] gg The GGraphObject 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] width The width of the window - * @param[in] height The height of the window - * @note The console is not automatically cleared on creation. You must do that by calling gwinClear() (possibly after changing your background color) + * @param[in] pInit The initialization parameters to use + * + * @note The drawing color and the background color get set to the current defaults. If you haven't called + * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively. + * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there + * is no default font and text drawing operations will no nothing. + * @note The dimensions and position may be changed to fit on the real screen. + * @note A graph does not save the drawing state. It is not automatically redrawn if the window is moved or + * its visibility state is changed. * @note The coordinate system within the window for graphing operations (but not for any other drawing * operation) is relative to the bottom left corner and then shifted right and up by the specified * graphing x and y origin. Note that this system is inverted in the y direction relative to the display. @@ -115,7 +107,7 @@ extern "C" { * * @api */ -GHandle gwinCreateGraph(GGraphObject *gg, coord_t x, coord_t y, coord_t width, coord_t height); +GHandle gwinCreateGraph(GGraphObject *gg, GWindowInit *pInit); /** * @brief Set the style of the graphing operations. @@ -187,8 +179,6 @@ void gwinGraphDrawPoints(GHandle gh, const point *points, unsigned count); } #endif -#endif /* GWIN_NEED_GRAPH */ - #endif /* _GWIN_GRAPH_H */ /** @} */ diff --git a/include/gwin/gwidget.h b/include/gwin/gwidget.h new file mode 100644 index 00000000..50f19193 --- /dev/null +++ b/include/gwin/gwidget.h @@ -0,0 +1,213 @@ +/* + * This file is subject to the terms of the GFX License. If a copy of + * the license was not distributed with this file, you can obtain one at: + * + * http://chibios-gfx.com/license.html + */ + +/** + * @file include/gwin/gwidget.h + * @brief GWIN Widgets header file. + */ + +#ifndef _GWIDGET_H +#define _GWIDGET_H + +/* This file is included within "gwin/gwin.h" */ + +/** + * @defgroup Widget Widget + * @ingroup GWIN + * + * @details A Widget is a GWindow that supports interacting with the user + * via an input device such as a mouse or toggle buttons. It is the + * base class for widgets such as buttons and sliders. + * + * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h + * @{ + */ + +// Forward definition +struct GWidgetObject; + +/** + * @brief Defines a custom drawing function for a widget + */ +typedef void (*CustomWidgetDrawFunction)(struct GWidgetObject *gw, void *param); + +/** + * @brief The GWIN Widget structure + * @note A widget is a GWIN window that accepts user input. + * It also has a number of other properties such as its ability + * to redraw itself (a widget maintains drawing state). + * @note Do you access the members directly. Treat it as a black-box and use the method functions. + * + * @{ + */ +typedef struct GWidgetObject { + GWindowObject g; // @< This is still a GWIN + const char * txt; // @< The widget text + CustomWidgetDrawFunction fnDraw; // @< The current draw function + void * fnParam; // @< A parameter for the current draw function +} GWidgetObject; +/* @} */ + +/** + * @brief The structure to initialise a widget. + * + * @note Some widgets may have extra parameters. + * @note The text element must be static string (not stack allocated). If you want to use + * a dynamic string (eg a stack allocated string) use NULL for this member and then call + * @p gwinSetText() with useAlloc set to TRUE. + * + * @{ + */ +typedef struct GWidgetInit { + GWindowInit g; // @< The GWIN initializer + const char * text; // @< The initial text +} GWidgetInit; +/* @} */ + +/** + * A comment/rant on the above structure: + * We would really like the GWindowObject member to be anonymous. While this is + * allowed under the C11, C99, GNU and various other standards which have been + * around forever - compiler support often requires special flags e.g + * gcc requires the -fms-extensions flag (no wonder the language and compilers have + * not really progressed in 30 years). As portability is a key requirement + * we unfortunately won't use this useful feature in case we get a compiler that + * won't support it even with special flags. + */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Enable or disable a widget + * + * @param[in] gh The widget handle + * @param[in] enabled Enable or disable the widget + * + * @note The widget is automatically redrawn. + * @note Non-widgets will ignore this call. + * + * @api + */ +void gwinSetEnabled(GHandle gh, bool_t enabled); + +/** + * @brief Set the text of a widget. + * + * @param[in] gh The widget handle + * @param[in] txt The 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 widget is automatically redrawn + * @note Non-widgets will ignore this call. + * + * @api + */ +void gwinSetText(GHandle gh, const char *txt, bool_t useAlloc); + +/** + * @brief Get the text of a widget. + * @return The widget text or NULL if it isn't a widget + * + * @param[in] gh The widget handle + * + * @api + */ +const char *gwinGetText(GHandle gh); + +/** + * @brief Set the routine to perform a custom widget drawing. + * + * @param[in] gh The widget handle + * @param[in] fn The function to use to draw the widget + * @param[in] param A parameter to pass to the widget drawing function + * + * @note The widget is not automatically redrawn. Call @p gwinDraw() to redraw the widget. + * @note Non-widgets will ignore this call. + * + * @api + */ +void gwinSetCustomDraw(GHandle gh, CustomWidgetDrawFunction fn, void *param); + +/** + * @brief Attach a Listener to listen for widget events + * @return TRUE on success + * + * @param[in] pl The listener + * + * @api + */ +bool_t gwinAttachListener(GListener *pl); + +#if GFX_USE_GINPUT && GINPUT_NEED_MOUSE + /** + * @brief Set the mouse to be used to control the widgets + * @return TRUE on success + * + * @param[in] instance The mouse instance + * + * @note Every widget uses the same mouse. + * + * @api + */ + bool_t gwinAttachMouse(uint16_t instance); +#endif + +#if GFX_USE_GINPUT && GINPUT_NEED_TOGGLE + /** + * @brief Attach a toggle to a widget + * @return TRUE on success + * + * @param[in] gh The widget handle + * @param[in] role The function the toggle will perform for the widget + * @param[in] instance The toggle instance + * + * @note See the documentation on the specific widget to see the possible + * values for the role parameter. If it is out of range, this function + * will return FALSE + * + * @api + */ + bool_t gwinAttachToggle(GHandle gh, uint16_t role, uint16_t instance); +#endif + +#if GFX_USE_GINPUT && GINPUT_NEED_DIAL + /** + * @brief Attach a toggle to a widget + * @return TRUE on success + * + * @param[in] gh The widget handle + * @param[in] role The function the dial will perform for the widget + * @param[in] instance The dial instance + * + * @note See the documentation on the specific widget to see the possible + * values for the role parameter. If it is out of range, this function + * will return FALSE + * + * @api + */ + bool_t gwinAttachDial(GHandle gh, uint16_t role, uint16_t instance); +#endif + +#ifdef __cplusplus +} +#endif + +/* Include extra widget types */ +#if GWIN_NEED_BUTTON || defined(__DOXYGEN__) + #include "gwin/button.h" +#endif +#if GWIN_NEED_SLIDER || defined(__DOXYGEN__) + #include "gwin/slider.h" +#endif +#if GWIN_NEED_CHECKBOX || defined(__DOXYGEN__) + #include "gwin/checkbox.h" +#endif + +#endif /* _GWIDGET_H */ +/** @} */ diff --git a/include/gwin/gwin.h b/include/gwin/gwin.h index 277dfab1..2a03c125 100644 --- a/include/gwin/gwin.h +++ b/include/gwin/gwin.h @@ -12,14 +12,12 @@ * @defgroup Window Window * @ingroup GWIN * - * @details GWIN provides a basic window manager which allows it to easily - * create and destroy different windows on runtime. Each window - * will have it's own properties such as colors, brushes as well as - * it's own drawing origin. - * Moving the windows around is not supported yet. + * @details GWIN provides a basic window manager which allows it to easily + * create and destroy different windows at runtime. Each window + * will have it's own properties such as colors as well as + * it's own drawing origin. * * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h - * * @{ */ @@ -30,520 +28,727 @@ #if GFX_USE_GWIN || defined(__DOXYGEN__) -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ - -typedef uint16_t GWindowType; -#define GW_WINDOW 0x0000 -#define GW_FIRST_USER_WINDOW 0x8000 - -// A basic window -typedef struct GWindowObject_t { - GWindowType type; // What type of window is this - uint16_t flags; // Internal flags - coord_t x, y; // Screen relative position - coord_t width, height; // Dimensions of this window - color_t color, bgcolor; // Current drawing colors - bool_t enabled; // Enabled/Disabled state -#if GDISP_NEED_TEXT - font_t font; // Current font -#endif -} GWindowObject, * GHandle; - -/*===========================================================================*/ -/* External declarations. */ -/*===========================================================================*/ - -#ifdef __cplusplus -extern "C" { -#endif - -/* Base Functions */ - -/** - * @brief Create a basic window. - * @return NULL if there is no resultant drawing area, otherwise a window handle. - * - * @param[in] gw The window structure to initialize. If this is NULL the structure is dynamically allocated. - * @param[in] x,y The screen coordinates for the bottom left corner of the window - * @param[in] width The width of the window - * @param[in] height The height of the window - * @note The default drawing color gets set to White and the background drawing color to Black. - * @note No default font is set so make sure to set one before drawing any text. - * @note The dimensions and position may be changed to fit on the real screen. - * @note The window is not automatically cleared on creation. You must do that by calling gwinClear() (possibly after changing your background color) - * - * @api - */ -GHandle gwinCreateWindow(GWindowObject *gw, coord_t x, coord_t y, coord_t width, coord_t height); - /** - * @brief Destroy a window (of any type). Releases any dynamically allocated memory. - * - * @param[in] gh The window handle - * - * @api - */ -void gwinDestroyWindow(GHandle gh); - -/** - * @brief Enable or disable a widget (of any type). - * - * @param[in] gh The window handle - * @param[in] enabled Enable or disable the widget - * - * @api - */ -void gwinSetEnabled(GHandle gh, bool_t enabled); - -/** - * @brief Get the X coordinate of the window - * @details Returns the X coordinate of the origin of the window. - * The coordinate is relative to the physical screen zero point. - * - * @param[in] gh The window - */ -#define gwinGetScreenX(gh) ((gh)->x) - -/** - * @brief Get the Y coordinate of the window - * @details Returns the Y coordinate of the origin of the window. - * The coordinate is relative to the physical screen zero point. - * - * @param[in] gh The window - */ -#define gwinGetScreenY(gh) ((gh)->y) - -/** - * @brief Get the width of the window - * - * @param[in] gh The window + * @brief A window object structure + * @note Do not access the members directly. Treat it as a black-box and use the method functions. + * @{ */ -#define gwinGetWidth(gh) ((gh)->width) +typedef struct GWindowObject { + #if GWIN_NEED_WINDOWMANAGER + // This MUST be the first member of the struct + gfxQueueASyncItem wmq; // @< The next window (for the window manager) + #endif + const struct gwinVMT *vmt; // @< The VMT for this GWIN + coord_t x, y; // @< Screen relative position + coord_t width, height; // @< Dimensions of this window + color_t color, bgcolor; // @< The current drawing colors + uint16_t flags; // @< Window flags (the meaning is private to the GWIN class) + #if GDISP_NEED_TEXT + font_t font; // @< The current font + #endif +} GWindowObject, * GHandle; +/* @} */ /** - * @brief Get the height of the window + * @brief The structure to initialise a GWIN. * - * @param[in] gh The window - */ -#define gwinGetHeight(gh) ((gh)->height) - -/** - * @brief Set foreground color - * @details Set the color which will be used to draw + * @note Some gwin's will need extra parameters. + * @note The dimensions and position may be changed to fit on the real screen. * - * @param[in] gh The window - * @param[in] clr The color to be set + * @{ */ -#define gwinSetColor(gh, clr) (gh)->color = (clr) +typedef struct GWindowInit { + coord_t x, y; // @< The initial screen position + coord_t width, height; // @< The initial dimension + bool_t show; // @< Should the window be visible initially +} GWindowInit; +/* @} */ /** - * @brief Set background color - * @details Set the color which will be used as background - * @note gwinClear() must be called to set the background color - * - * @param[in] gh The window - * @param[in] bgclr The background color + * @brief A window's minimized, maximized or normal size */ -#define gwinSetBgColor(gh, bgclr) (gh)->bgcolor = (bgclr) +typedef enum { GWIN_NORMAL, GWIN_MAXIMIZE, GWIN_MINIMIZE } GWindowMinMax; -/** - * @brief Enable a window of any type - * - * @param[in] gh The window handle - */ -#define gwinEnable(gh) gwinSetEnabled(gh, TRUE) +#ifdef __cplusplus +extern "C" { +#endif -/** - * @brief Disable a window of any type - * - * @param[in] gh The window handle - */ -#define gwinDisable(gh) gwinSetEnabled(gh, FALSE) +/*------------------------------------------------- + * Window Manager functions + *-------------------------------------------------*/ -/* Set up for text */ +#if GWIN_NEED_WINDOWMANAGER + // Forward definition + struct GWindowManager; -#if GDISP_NEED_TEXT || defined(__DOXYGEN__) /** - * @brief Set the current font for this window. + * @brief Set the window manager for the GWIN system. * - * @param[in] gh The window handle - * @param[in] font The font to use for text functions + * @param[in] gwm The window manager to use. Can be NULL to turn off the existing window manager. + * + * @note A window manager is responsible for handling when window visibility is changed or + * a window is resized for moved. Note that only saved window states will be redrawn. Each + * window type can save different information (or none at all). See the documentation on each window + * type to see which information it saves (and can therefore be automatically redrawn). + * For window types that do not save any state information, the window manager determines what to do. + * Generally it will just clear the window to its background color. * * @api */ - void gwinSetFont(GHandle gh, font_t font); + void gwinSetWindowManager(struct GWindowManager *gwm); #endif -/* Drawing Functions */ +/*------------------------------------------------- + * Functions that affect all windows + *-------------------------------------------------*/ -/** - * @brief Draw the window - * @note Redraws the Window if the GWIN object has a draw routine - * - * @param[in] gh The window handle - * - * @api - */ -void gwinDraw(GHandle gh); + /** + * @brief Set the default foreground color for all new GWIN windows + * + * @param[in] gh The window + * @param[in] clr The color to be set + * + * @api + */ + void gwinSetDefaultColor(color_t clr); -/** - * @brief Clear the window - * @note Uses the current background color to clear the window - * - * @param[in] gh The window handle - * - * @api - */ -void gwinClear(GHandle gh); + /** + * @brief Set the default background color for all new GWIN windows + * + * @param[in] gh The window + * @param[in] bgclr The background color + * + * @api + */ + void gwinSetDefaultBgColor(color_t bgclr); -/** - * @brief Set a pixel in the window - * @note Uses the current foreground color to set the pixel - * @note May leave GDISP clipping to this window's dimensions - * - * @param[in] gh The window handle - * @param[in] x,y The coordinates of the pixel - * - * @api - */ -void gwinDrawPixel(GHandle gh, coord_t x, coord_t y); + #if GDISP_NEED_TEXT || defined(__DOXYGEN__) + /** + * @brief Set the default font for all new GWIN windows + * + * @param[in] gh The window + * + * @api + */ + void gwinSetDefaultFont(font_t font); + #endif -/** - * @brief Draw a line in the window - * @note Uses the current foreground color to draw the line - * @note May leave GDISP clipping to this window's dimensions - * - * @param[in] gh The window handle - * @param[in] x0,y0 The start position - * @param[in] x1,y1 The end position - * - * @api - */ -void gwinDrawLine(GHandle gh, coord_t x0, coord_t y0, coord_t x1, coord_t y1); -/** - * @brief Draw a box in the window - * @note Uses the current foreground color to draw the box - * @note May leave GDISP clipping to this window's dimensions - * - * @param[in] gh The window handle - * @param[in] x,y The start position - * @param[in] cx,cy The size of the box (outside dimensions) - * - * @api - */ -void gwinDrawBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy); +/*------------------------------------------------- + * Base functions + *-------------------------------------------------*/ -/** - * @brief Fill an rectangular area in the window - * @note Uses the current foreground color to fill the box - * @note May leave GDISP clipping to this window's dimensions - * - * @param[in] gh The window handle - * @param[in] x,y The start position - * @param[in] cx,cy The size of the box (outside dimensions) - * - * @api - */ -void gwinFillArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy); + /** + * @brief Create a basic window. + * @return NULL if there is no resultant drawing area, otherwise a window handle. + * + * @param[in] pgw The window structure to initialize. If this is NULL the structure is dynamically allocated. + * @param[in] pInit How to initialise the window + * + * @note The drawing color and the background color get set to the current defaults. If you haven't called + * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively. + * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there + * is no default font and text drawing operations will no nothing. + * @note A basic window does not save the drawing state. It is not automatically redrawn if the window is moved or + * its visibility state is changed. + * + * @api + */ + GHandle gwinCreateWindow(GWindowObject *pgw, GWindowInit *pInit); -/** - * @brief Fill an area in the window using the supplied bitmap. - * @details The bitmap is in the pixel format specified by the low level driver - * @note If GDISP_NEED_ASYNC is defined then the buffer must be static - * or at least retained until this call has finished the blit. You can - * tell when all graphics drawing is finished by @p gdispIsBusy() going FALSE. - * @note May leave GDISP clipping to this window's dimensions - * - * @param[in] gh The window handle - * @param[in] x, y The start filled area - * @param[in] cx, cy The width and height to be filled - * @param[in] srcx, srcy The bitmap position to start the fill from - * @param[in] srccx The width of a line in the bitmap. - * @param[in] buffer The pixels to use to fill the area. - * - * @api - */ -void gwinBlitArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t srcx, coord_t srcy, coord_t srccx, const pixel_t *buffer); + /** + * @brief Destroy a window (of any type). Releases any dynamically allocated memory. + * + * @param[in] gh The window handle + * + * @api + */ + void gwinDestroy(GHandle gh); -/* Circle Functions */ + /** + * @brief Get the real class name of the GHandle + * @details Returns a string describing the object class. + * + * @param[in] gh The window + * + * @api + */ + const char *gwinGetClassName(GHandle gh); -#if GDISP_NEED_CIRCLE || defined(__DOXYGEN__) /** - * @brief Draw a circle in the window. - * @note Uses the current foreground color to draw the circle - * @note May leave GDISP clipping to this window's dimensions + * @brief Get an ID that uniquely describes the class of the GHandle * - * @param[in] gh The window handle - * @param[in] x, y The center of the circle - * @param[in] radius The radius of the circle + * @param[in] gh The window * * @api */ - void gwinDrawCircle(GHandle gh, coord_t x, coord_t y, coord_t radius); + #define gwinGetClassID(gh) ((void *)((gh)->vmt)) /** - * @brief Draw a filled circle in the window. - * @note Uses the current foreground color to draw the filled circle - * @note May leave GDISP clipping to this window's dimensions + * @brief Get the X coordinate of the window + * @details Returns the X coordinate of the origin of the window. + * The coordinate is relative to the physical screen zero point. * - * @param[in] gh The window handle - * @param[in] x, y The center of the circle - * @param[in] radius The radius of the circle + * @param[in] gh The window * * @api */ - void gwinFillCircle(GHandle gh, coord_t x, coord_t y, coord_t radius); -#endif + #define gwinGetScreenX(gh) ((gh)->x) -/* Ellipse Functions */ + /** + * @brief Get the Y coordinate of the window + * @details Returns the Y coordinate of the origin of the window. + * The coordinate is relative to the physical screen zero point. + * + * @param[in] gh The window + * + * @api + */ + #define gwinGetScreenY(gh) ((gh)->y) -#if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__) /** - * @brief Draw an ellipse. - * @note Uses the current foreground color to draw the ellipse - * @note May leave GDISP clipping to this window's dimensions + * @brief Get the width of the window * - * @param[in] gh The window handle - * @param[in] x,y The center of the ellipse - * @param[in] a,b The dimensions of the ellipse + * @param[in] gh The window * * @api */ - void gwinDrawEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b); + #define gwinGetWidth(gh) ((gh)->width) /** - * @brief Draw an filled ellipse. - * @note Uses the current foreground color to draw the filled ellipse - * @note May leave GDISP clipping to this window's dimensions + * @brief Get the height of the window * - * @param[in] gh The window handle - * @param[in] x,y The center of the ellipse - * @param[in] a,b The dimensions of the ellipse + * @param[in] gh The window * * @api */ - void gwinFillEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b); -#endif + #define gwinGetHeight(gh) ((gh)->height) -/* Arc Functions */ + /** + * @brief Set foreground color + * @details Set the color which will be used to draw + * + * @param[in] gh The window + * @param[in] clr The color to be set + * + * @api + */ + #define gwinSetColor(gh, clr) (gh)->color = (clr) -#if GDISP_NEED_ARC || defined(__DOXYGEN__) - /* - * @brief Draw an arc in the window. - * @note Uses the current foreground color to draw the arc - * @note May leave GDISP clipping to this window's dimensions + /** + * @brief Set background color + * @details Set the color which will be used as background + * @note gwinClear() must be called to set the background color * - * @param[in] gh The window handle - * @param[in] x,y The center point - * @param[in] radius The radius of the arc - * @param[in] start The start angle (0 to 360) - * @param[in] end The end angle (0 to 360) + * @param[in] gh The window + * @param[in] bgclr The background color * * @api */ - void gwinDrawArc(GHandle gh, coord_t x, coord_t y, coord_t radius, coord_t startangle, coord_t endangle); + #define gwinSetBgColor(gh, bgclr) (gh)->bgcolor = (bgclr) - /* - * @brief Draw a filled arc in the window. - * @note Uses the current foreground color to draw the filled arc - * @note May leave GDISP clipping to this window's dimensions + /** + * @brief Sets whether a window is visible or not * - * @param[in] gh The window handle - * @param[in] x,y The center point - * @param[in] radius The radius of the arc - * @param[in] start The start angle (0 to 360) - * @param[in] end The end angle (0 to 360) + * @param[in] gh The window + * @param[in] visible Whether the window should be visible or not + * + * @note When a window is marked as not visible, drawing operations + * on the window do nothing. + * @note When a window is marked as visible, it is not automatically + * redrawn as many window types don't remember their drawing state. + * Widgets such as Buttons, Sliders etc will be redrawn. + * @note If there is no window manager in use, when a window is marked + * as not visible, nothing is done to remove the window from the screen. + * When there is a window manager, it is up to the window manager to + * handle what happens. * * @api */ - void gwinFillArc(GHandle gh, coord_t x, coord_t y, coord_t radius, coord_t startangle, coord_t endangle); -#endif + void gwinSetVisible(GHandle gh, bool_t visible); -/* Read a pixel Function */ + /** + * @brief Gets the visibility of a window + * @return TRUE if visible + * + * @param[in] gh The window + * + * @api + */ + bool_t gwinGetVisible(GHandle gh); -#if GDISP_NEED_PIXELREAD || defined(__DOXYGEN__) /** - * @brief Get the color of a pixel in the window. - * @return The color of the pixel. - * @note May leave GDISP clipping to this window's dimensions + * @brief Move a window * - * @param[in] gh The window handle - * @param[in] x,y The position in the window + * @param[in] gh The window + * @param[in] x, y The new position (screen relative) for this window + * + * @note The final window position may not be the requested position. Windows + * are clipped to the screen area and the window manager may also affect the position. + * @note The window is redrawn if it is visible. See the comments in @p gwinSetVisible() + * with regard to what can be redrawn and what can't. + * @note It is up to the window manager to determine what happens with the screen area + * uncovered by moving the window. When there is no window manager, nothing + * is done with the uncovered area. * * @api */ - color_t gwinGetPixelColor(GHandle gh, coord_t x, coord_t y); -#endif + void gwinMove(GHandle gh, coord_t x, coord_t y); -/* Extra Text Functions */ + /** + * @brief Resize a window + * + * @param[in] gh The window + * @param[in] width, height The new size of the window + * + * @note The final window size may not be the requested size. Windows + * are clipped to the screen area and the window manager may also affect the size. + * @note The window is redrawn if it is visible. See the comments in @p gwinSetVisible() + * with regard to what can be redrawn and what can't. + * @note It is up to the window manager to determine what happens with any screen area + * uncovered by resizing the window. When there is no window manager, nothing + * is done with the uncovered area. + * + * @api + */ + void gwinResize(GHandle gh, coord_t width, coord_t height); -#if GDISP_NEED_TEXT || defined(__DOXYGEN__) /** - * @brief Draw a text character at the specified position in the window. - * @pre The font must have been set. - * @note Uses the current foreground color to draw the character - * @note May leave GDISP clipping to this window's dimensions + * @brief Minimize, Maximize or Restore a window * - * @param[in] gh The window handle - * @param[in] x,y The position for the text - * @param[in] c The character to draw + * @param[in] gh The window + * @param[in] minmax The new minimized/maximized state + * + * @note The final window state may not be the requested state. Window Managers + * do not need to implement changing the minmax state. If there is no + * window manager this call is ignored. + * @note The window is redrawn if it is changed. See the comments in @p gwinSetVisible() + * with regard to what can be redrawn and what can't. + * @note It is up to the window manager to determine what happens with any screen area + * uncovered by resizing the window. + * @note When a window is minimised it may be asked to draw the window or the window + * manager may draw the minimised window. * * @api */ - void gwinDrawChar(GHandle gh, coord_t x, coord_t y, char c); + void gwinSetMinMax(GHandle gh, GWindowMinMax minmax); /** - * @brief Draw a text character with a filled background at the specified position in the window. - * @pre The font must have been set. - * @note Uses the current foreground color to draw the character and fills the background using the background drawing color - * @note May leave GDISP clipping to this window's dimensions + * @brief Get the Minimized/Maximized state of a window * - * @param[in] gh The window handle - * @param[in] x,y The position for the text - * @param[in] c The character to draw + * @param[in] gh The window * * @api */ - void gwinFillChar(GHandle gh, coord_t x, coord_t y, char c); + GWindowMinMax gwinGetMinMax(GHandle gh); /** - * @brief Draw a text string in the window - * @pre The font must have been set. - * @note Uses the current foreground color to draw the character - * @note May leave GDISP clipping to this window's dimensions + * @brief Raise a window to the top of the z-order * - * @param[in] gh The window handle - * @param[in] x,y The position for the text - * @param[in] str The string to draw + * @param[in] gh The window + * + * @note The window z-order is only supported by some window managers. If there is no + * window manager this call simple tries to redraw the window. See the comments + * in @p gwinSetVisible() with regard to what can be redrawn and what can't. * * @api */ - void gwinDrawString(GHandle gh, coord_t x, coord_t y, const char *str); + void gwinRaise(GHandle gh); + + #if GDISP_NEED_TEXT || defined(__DOXYGEN__) + /** + * @brief Set the current font for this window. + * + * @param[in] gh The window handle + * @param[in] font The font to use for text functions + * + * @api + */ + void gwinSetFont(GHandle gh, font_t font); + #endif + +/*------------------------------------------------- + * Drawing functions + *-------------------------------------------------*/ /** - * @brief Draw a text string with a filled background in the window - * @pre The font must have been set. - * @note Uses the current foreground color to draw the character and fills the background using the background drawing color - * @note May leave GDISP clipping to this window's dimensions + * @brief Clear the window + * @note Uses the current background color to clear the window * * @param[in] gh The window handle - * @param[in] x,y The position for the text - * @param[in] str The string to draw * * @api */ - void gwinFillString(GHandle gh, coord_t x, coord_t y, const char *str); + void gwinClear(GHandle gh); /** - * @brief Draw a text string verticly centered within the specified box. - * @pre The font must have been set. - * @note Uses the current foreground color to draw the character. - * @note The specified box does not need to align with the window box + * @brief Set a pixel in the window + * @note Uses the current foreground color to set the pixel * @note May leave GDISP clipping to this window's dimensions * * @param[in] gh The window handle - * @param[in] x,y The position for the text (need to define top-right or base-line - check code) - * @param[in] cx,cy The width and height of the box - * @param[in] str The string to draw - * @param[in] justify Justify the text left, center or right within the box + * @param[in] x,y The coordinates of the pixel * * @api */ - void gwinDrawStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char* str, justify_t justify); + void gwinDrawPixel(GHandle gh, coord_t x, coord_t y); /** - * @brief Draw a text string verticly centered within the specified filled box. - * @pre The font must have been set. - * @note Uses the current foreground color to draw the character and fills the background using the background drawing color - * @note The entire box is filled. Note this box does not need to align with the window box + * @brief Draw a line in the window + * @note Uses the current foreground color to draw the line * @note May leave GDISP clipping to this window's dimensions * * @param[in] gh The window handle - * @param[in] x,y The position for the text (need to define top-right or base-line - check code) - * @param[in] cx,cy The width and height of the box - * @param[in] str The string to draw - * @param[in] justify Justify the text left, center or right within the box + * @param[in] x0,y0 The start position + * @param[in] x1,y1 The end position * * @api */ - void gwinFillStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char* str, justify_t justify); -#endif + void gwinDrawLine(GHandle gh, coord_t x0, coord_t y0, coord_t x1, coord_t y1); -#if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__) /** - * @brief Draw an enclosed polygon (convex, non-convex or complex). - * - * @note Uses the current foreground color. + * @brief Draw a box in the window + * @note Uses the current foreground color to draw the box + * @note May leave GDISP clipping to this window's dimensions * * @param[in] gh The window handle - * @param[in] tx, ty Transform all points in pntarray by tx, ty - * @param[in] pntarray An array of points - * @param[in] cnt The number of points in the array + * @param[in] x,y The start position + * @param[in] cx,cy The size of the box (outside dimensions) * * @api */ - void gwinDrawPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt); + void gwinDrawBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy); /** - * @brief Fill a convex polygon - * @details Doesn't handle non-convex or complex polygons. - * - * @note Uses the current foreground color. + * @brief Fill an rectangular area in the window + * @note Uses the current foreground color to fill the box + * @note May leave GDISP clipping to this window's dimensions * * @param[in] gh The window handle - * @param[in] tx, ty Transform all points in pntarray by tx, ty - * @param[in] pntarray An array of points - * @param[in] cnt The number of points in the array - * - * @note Convex polygons are those that have no internal angles. That is; - * you can draw a line from any point on the polygon to any other point - * on the polygon without it going outside the polygon. In our case we generalise - * this a little by saying that an infinite horizontal line (at any y value) will cross - * no more than two edges on the polygon. Some non-convex polygons do fit this criteria - * and can therefore be drawn. - * @note This routine is designed to be very efficient with even simple display hardware. + * @param[in] x,y The start position + * @param[in] cx,cy The size of the box (outside dimensions) * * @api */ - void gwinFillConvexPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt); -#endif + void gwinFillArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy); -#if GDISP_NEED_IMAGE || defined(__DOXYGEN__) /** - * @brief Draw the image - * @return GDISP_IMAGE_ERR_OK (0) on success or an error code. + * @brief Fill an area in the window using the supplied bitmap. + * @details The bitmap is in the pixel format specified by the low level driver + * @note If GDISP_NEED_ASYNC is defined then the buffer must be static + * or at least retained until this call has finished the blit. You can + * tell when all graphics drawing is finished by @p gdispIsBusy() going FALSE. + * @note May leave GDISP clipping to this window's dimensions * * @param[in] gh The window handle - * @param[in] img The image structure - * @param[in] x,y The window location to draw the image - * @param[in] cx,cy The area on the screen to draw - * @param[in] sx,sy The image position to start drawing at - * - * @pre gdispImageOpen() must have returned successfully. - * - * @note If sx,sy + cx,cy is outside the image boundaries the area outside the image - * is simply not drawn. - * @note If @p gdispImageCache() has been called first for this frame, this routine will draw using a - * fast blit from the cached frame. If not, it reads the input and decodes it as it - * is drawing. This may be significantly slower than if the image has been cached (but - * uses a lot less RAM) + * @param[in] x, y The start filled area + * @param[in] cx, cy The width and height to be filled + * @param[in] srcx, srcy The bitmap position to start the fill from + * @param[in] srccx The width of a line in the bitmap. + * @param[in] buffer The pixels to use to fill the area. + * + * @api */ - gdispImageError gwinImageDraw(GHandle gh, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy); -#endif + void gwinBlitArea(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t srcx, coord_t srcy, coord_t srccx, const pixel_t *buffer); + +/*------------------------------------------------- + * Circle, ellipse and arc functions + *-------------------------------------------------*/ + + #if GDISP_NEED_CIRCLE || defined(__DOXYGEN__) + /** + * @brief Draw a circle in the window. + * @note Uses the current foreground color to draw the circle + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x, y The center of the circle + * @param[in] radius The radius of the circle + * + * @api + */ + void gwinDrawCircle(GHandle gh, coord_t x, coord_t y, coord_t radius); + + /** + * @brief Draw a filled circle in the window. + * @note Uses the current foreground color to draw the filled circle + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x, y The center of the circle + * @param[in] radius The radius of the circle + * + * @api + */ + void gwinFillCircle(GHandle gh, coord_t x, coord_t y, coord_t radius); + #endif + + #if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__) + /** + * @brief Draw an ellipse. + * @note Uses the current foreground color to draw the ellipse + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The center of the ellipse + * @param[in] a,b The dimensions of the ellipse + * + * @api + */ + void gwinDrawEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b); + + /** + * @brief Draw an filled ellipse. + * @note Uses the current foreground color to draw the filled ellipse + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The center of the ellipse + * @param[in] a,b The dimensions of the ellipse + * + * @api + */ + void gwinFillEllipse(GHandle gh, coord_t x, coord_t y, coord_t a, coord_t b); + #endif + + #if GDISP_NEED_ARC || defined(__DOXYGEN__) + /* + * @brief Draw an arc in the window. + * @note Uses the current foreground color to draw the arc + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The center point + * @param[in] radius The radius of the arc + * @param[in] start The start angle (0 to 360) + * @param[in] end The end angle (0 to 360) + * + * @api + */ + void gwinDrawArc(GHandle gh, coord_t x, coord_t y, coord_t radius, coord_t startangle, coord_t endangle); + + /* + * @brief Draw a filled arc in the window. + * @note Uses the current foreground color to draw the filled arc + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The center point + * @param[in] radius The radius of the arc + * @param[in] start The start angle (0 to 360) + * @param[in] end The end angle (0 to 360) + * + * @api + */ + void gwinFillArc(GHandle gh, coord_t x, coord_t y, coord_t radius, coord_t startangle, coord_t endangle); + #endif + +/*------------------------------------------------- + * Pixel read-back functions + *-------------------------------------------------*/ + + #if GDISP_NEED_PIXELREAD || defined(__DOXYGEN__) + /** + * @brief Get the color of a pixel in the window. + * @return The color of the pixel. + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position in the window + * + * @api + */ + color_t gwinGetPixelColor(GHandle gh, coord_t x, coord_t y); + #endif + +/*------------------------------------------------- + * Text functions + *-------------------------------------------------*/ + + #if GDISP_NEED_TEXT || defined(__DOXYGEN__) + /** + * @brief Draw a text character at the specified position in the window. + * @pre The font must have been set. + * @note Uses the current foreground color to draw the character + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position for the text + * @param[in] c The character to draw + * + * @api + */ + void gwinDrawChar(GHandle gh, coord_t x, coord_t y, char c); + + /** + * @brief Draw a text character with a filled background at the specified position in the window. + * @pre The font must have been set. + * @note Uses the current foreground color to draw the character and fills the background using the background drawing color + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position for the text + * @param[in] c The character to draw + * + * @api + */ + void gwinFillChar(GHandle gh, coord_t x, coord_t y, char c); + + /** + * @brief Draw a text string in the window + * @pre The font must have been set. + * @note Uses the current foreground color to draw the character + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position for the text + * @param[in] str The string to draw + * + * @api + */ + void gwinDrawString(GHandle gh, coord_t x, coord_t y, const char *str); + + /** + * @brief Draw a text string with a filled background in the window + * @pre The font must have been set. + * @note Uses the current foreground color to draw the character and fills the background using the background drawing color + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position for the text + * @param[in] str The string to draw + * + * @api + */ + void gwinFillString(GHandle gh, coord_t x, coord_t y, const char *str); + + /** + * @brief Draw a text string verticly centered within the specified box. + * @pre The font must have been set. + * @note Uses the current foreground color to draw the character. + * @note The specified box does not need to align with the window box + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position for the text (need to define top-right or base-line - check code) + * @param[in] cx,cy The width and height of the box + * @param[in] str The string to draw + * @param[in] justify Justify the text left, center or right within the box + * + * @api + */ + void gwinDrawStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char* str, justify_t justify); + + /** + * @brief Draw a text string verticly centered within the specified filled box. + * @pre The font must have been set. + * @note Uses the current foreground color to draw the character and fills the background using the background drawing color + * @note The entire box is filled. Note this box does not need to align with the window box + * @note May leave GDISP clipping to this window's dimensions + * + * @param[in] gh The window handle + * @param[in] x,y The position for the text (need to define top-right or base-line - check code) + * @param[in] cx,cy The width and height of the box + * @param[in] str The string to draw + * @param[in] justify Justify the text left, center or right within the box + * + * @api + */ + void gwinFillStringBox(GHandle gh, coord_t x, coord_t y, coord_t cx, coord_t cy, const char* str, justify_t justify); + #endif + +/*------------------------------------------------- + * Polygon functions + *-------------------------------------------------*/ + + #if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__) + /** + * @brief Draw an enclosed polygon (convex, non-convex or complex). + * + * @note Uses the current foreground color. + * + * @param[in] gh The window handle + * @param[in] tx, ty Transform all points in pntarray by tx, ty + * @param[in] pntarray An array of points + * @param[in] cnt The number of points in the array + * + * @api + */ + void gwinDrawPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt); + + /** + * @brief Fill a convex polygon + * @details Doesn't handle non-convex or complex polygons. + * + * @note Uses the current foreground color. + * + * @param[in] gh The window handle + * @param[in] tx, ty Transform all points in pntarray by tx, ty + * @param[in] pntarray An array of points + * @param[in] cnt The number of points in the array + * + * @note Convex polygons are those that have no internal angles. That is; + * you can draw a line from any point on the polygon to any other point + * on the polygon without it going outside the polygon. In our case we generalise + * this a little by saying that an infinite horizontal line (at any y value) will cross + * no more than two edges on the polygon. Some non-convex polygons do fit this criteria + * and can therefore be drawn. + * @note This routine is designed to be very efficient with even simple display hardware. + * + * @api + */ + void gwinFillConvexPoly(GHandle gh, coord_t tx, coord_t ty, const point *pntarray, unsigned cnt); + #endif + +/*------------------------------------------------- + * Image functions + *-------------------------------------------------*/ + + #if GDISP_NEED_IMAGE || defined(__DOXYGEN__) + /** + * @brief Draw the image + * @return GDISP_IMAGE_ERR_OK (0) on success or an error code. + * + * @param[in] gh The window handle + * @param[in] img The image structure + * @param[in] x,y The window location to draw the image + * @param[in] cx,cy The area on the screen to draw + * @param[in] sx,sy The image position to start drawing at + * + * @pre gdispImageOpen() must have returned successfully. + * + * @note If sx,sy + cx,cy is outside the image boundaries the area outside the image + * is simply not drawn. + * @note If @p gdispImageCache() has been called first for this frame, this routine will draw using a + * fast blit from the cached frame. If not, it reads the input and decodes it as it + * is drawing. This may be significantly slower than if the image has been cached (but + * uses a lot less RAM) + * + * @api + */ + gdispImageError gwinImageDraw(GHandle gh, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy); + #endif #ifdef __cplusplus } #endif -/* Include extra window types */ -#include "gwin/console.h" /* 0x0001 */ -#include "gwin/button.h" /* 0x0002 */ -#include "gwin/graph.h" /* 0x0003 */ -#include "gwin/slider.h" /* 0x0004 */ -#include "gwin/checkbox.h" /* 0x0005 */ +/*------------------------------------------------- + * Additional functionality + *-------------------------------------------------*/ + + /* Include widgets */ + #if GWIN_NEED_WIDGET || defined(__DOXYGEN__) + #include "gwin/gwidget.h" + #endif + + /* Include extra window types */ + #if GWIN_NEED_CONSOLE || defined(__DOXYGEN__) + #include "gwin/console.h" + #endif + #if GWIN_NEED_GRAPH || defined(__DOXYGEN__) + #include "gwin/graph.h" + #endif #endif /* GFX_USE_GWIN */ diff --git a/include/gwin/internal.h b/include/gwin/internal.h deleted file mode 100644 index 0b750b2c..00000000 --- a/include/gwin/internal.h +++ /dev/null @@ -1,41 +0,0 @@ -/* - * This file is subject to the terms of the GFX License. If a copy of - * the license was not distributed with this file, you can obtain one at: - * - * http://chibios-gfx.com/license.html - */ - -/** - * @file include/gwin/internal.h - * @brief GWIN Graphic window subsystem header file. - * - * @addtogroup GWIN - * @{ - */ -#ifndef _GWIN_INTERNAL_H -#define _GWIN_INTERNAL_H - -#if GFX_USE_GWIN || defined(__DOXYGEN__) - -/*===========================================================================*/ -/* Sub-system constants. */ -/*===========================================================================*/ - -#define GWIN_FLG_DYNAMIC 0x0001 -#define GBTN_FLG_ALLOCTXT 0x0002 -#define GWIN_FIRST_CONTROL_FLAG 0x0004 - -#ifdef __cplusplus -extern "C" { -#endif - -GHandle _gwinInit(GWindowObject *gw, coord_t x, coord_t y, coord_t width, coord_t height, size_t size); - -#ifdef __cplusplus -} -#endif - -#endif /* GFX_USE_GWIN */ - -#endif /* _GWIN_INTERNAL_H */ -/** @} */ diff --git a/include/gwin/options.h b/include/gwin/options.h index 1ee9b836..cc164259 100644 --- a/include/gwin/options.h +++ b/include/gwin/options.h @@ -21,20 +21,22 @@ * @{ */ /** - * @brief Should button functions be included. + * @brief Should window manager support be included * @details Defaults to FALSE */ - #ifndef GWIN_NEED_BUTTON - #define GWIN_NEED_BUTTON FALSE + #ifndef GWIN_NEED_WINDOWMANAGER + #define GWIN_NEED_WIDGET FALSE + #endif + /** + * @brief Should widget functions be included. Needed for any widget (eg Buttons, Sliders etc) + * @details Defaults to FALSE + */ + #ifndef GWIN_NEED_WIDGET + #define GWIN_NEED_WIDGET FALSE #endif /** * @brief Should console functions be included. * @details Defaults to FALSE - * @note To use chprintf() for printing in a console window you need to - * include in your application source file... - * \#include "chprintf.h" - * Also in your makefile, as part of your list of C source files, include - * ${CHIBIOS}/os/various/chprintf.c */ #ifndef GWIN_NEED_CONSOLE #define GWIN_NEED_CONSOLE FALSE @@ -47,12 +49,26 @@ #define GWIN_NEED_GRAPH FALSE #endif /** + * @brief Should button functions be included. + * @details Defaults to FALSE + */ + #ifndef GWIN_NEED_BUTTON + #define GWIN_NEED_BUTTON FALSE + #endif + /** * @brief Should slider functions be included. * @details Defaults to FALSE */ #ifndef GWIN_NEED_SLIDER #define GWIN_NEED_SLIDER FALSE #endif + /** + * @brief Should checkbox functions be included. + * @details Defaults to FALSE + */ + #ifndef GWIN_NEED_CHECKBOX + #define GWIN_NEED_CHECKBOX FALSE + #endif /** * @} * @@ -76,6 +92,12 @@ /** * @brief Console Windows need BaseStreamSequential support (ChibiOS only) * @details Defaults to FALSE + * @note To use the ChibiOS basestream functions such as chprintf() + * for printing in a console window you need to set this option to + * TRUE in your gfxconf.h and include in your application source file... + * \#include "chprintf.h" + * In your makefile, as part of your list of C source files, include + * ${CHIBIOS}/os/various/chprintf.c */ #ifndef GWIN_CONSOLE_USE_BASESTREAM #define GWIN_CONSOLE_USE_BASESTREAM FALSE diff --git a/include/gwin/slider.h b/include/gwin/slider.h index 310cb0eb..4479950f 100644 --- a/include/gwin/slider.h +++ b/include/gwin/slider.h @@ -22,19 +22,10 @@ #ifndef _GWIN_SLIDER_H #define _GWIN_SLIDER_H -#if GWIN_NEED_SLIDER || defined(__DOXYGEN__) +/* This file is included within "gwin/gwidget.h" */ -/*===========================================================================*/ -/* Driver constants. */ -/*===========================================================================*/ - -#define GW_SLIDER 0x0004 #define GEVENT_GWIN_SLIDER (GEVENT_GWIN_FIRST+1) -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ - typedef struct GEventGWinSlider_t { GEventType type; // The type of this event (GEVENT_GWIN_BUTTON) GHandle slider; // The slider that is returning results @@ -43,33 +34,27 @@ typedef struct GEventGWinSlider_t { // There are currently no GEventGWinSlider listening flags - use 0 -typedef struct GSliderDrawStyle_t { +typedef struct GSliderColors { color_t color_edge; color_t color_thumb; color_t color_active; color_t color_inactive; -} GSliderDrawStyle; - -typedef void (*GSliderDrawFunction)(GHandle gh, bool_t isVertical, coord_t thumbpos, const GSliderDrawStyle *pstyle, void *param); + color_t color_txt; +} GSliderColors; // A slider window typedef struct GSliderObject_t { - GWindowObject gwin; - - GSliderDrawStyle style; - bool_t tracking; + GWidgetObject w; + uint16_t t_dn; + uint16_t t_up; + uint16_t dial; + coord_t dpos; int min; int max; int pos; - GSliderDrawFunction fn; - void *param; - GListener listener; + GSliderColors c; } GSliderObject; -/*===========================================================================*/ -/* External declarations. */ -/*===========================================================================*/ - #ifdef __cplusplus extern "C" { #endif @@ -79,17 +64,25 @@ extern "C" { * @return NULL if there is no resultant drawing area, otherwise a window handle. * * @param[in] gb The GSliderObject 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] width The width of the window - * @param[in] height The height of the window - * @note The drawing color gets set to White and the background drawing color to Black. - * @note The dimensions and position may be changed to fit on the real screen. - * @note The slider is not automatically drawn. Call gwinSliderDraw() after changing the slider style. - * @note Sets the slider range from 0 to 100 with an initial position of 0 + * @param[in] pInit The initialization parameters to use + * + * @note The drawing color and the background color get set to the current defaults. If you haven't called + * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively. + * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there + * is no default font and text drawing operations will no nothing. + * @note A slider remembers its normal drawing state. If there is a window manager then it is automatically + * redrawn if the window is moved or its visibility state is changed. + * @note The initial slider range is from 0 to 100 with an initial position of 0. + * @note A slider supports mouse, toggle and dial input. + * @note When assigning a toggle, only one toggle is supported per role. If you try to assign more than + * one toggle to a role it will forget the previous toggle. Two roles are supported: + * Role 0 = toggle for down, Role 1 = toggle for up. + * @note When assigning a dial, only one dial is supported. If you try to assign more than one dial + * it will forget the previous dial. Only dial role 0 is supported. * * @api */ -GHandle gwinCreateSlider(GSliderObject *gb, coord_t x, coord_t y, coord_t width, coord_t height); +GHandle gwinCreateSlider(GSliderObject *gb, GWidgetInit *pInit); /** * @brief Set the slider range. @@ -130,51 +123,7 @@ void gwinSetSliderPosition(GHandle gh, int pos); * * @api */ -void gwinSetSliderStyle(GHandle gh, const GSliderDrawStyle *pStyle); - -/** - * @brief Redraw the slider. - * - * @param[in] gh The window handle (must be a slider window) - * - * @api - */ -void gwinSliderDraw(GHandle gh); - -/** - * @brief Enable or disable a button - * - * @param[in] gh The window handle (must be a slider window) - * @param[in] enabled Enable or disable the slider - * - * @api - */ -void gwinSliderSetEnabled(GHandle gh, bool_t enabled); - -/** - * @brief Set the callback routine to perform a custom slider drawing. - * - * @param[in] gh The window handle (must be a slider window) - * @param[in] fn The function to use to draw the slider - * @param[in] param A parameter to pass to the slider drawing function - * - * @api - */ -void gwinSetSliderCustom(GHandle gh, GSliderDrawFunction fn, void *param); - -/** - * @brief Enable a slider - * - * @api - */ -#define gwinEnableSlider(gh) gwinSliderSetEnabled( ((GSliderObject *)(gh)), TRUE) - -/** - * @brief Disable a slider - * - * @api - */ -#define gwinDisableSlider(gh) gwinSliderSetEnabled( ((GSliderObject *)(gh)), FALSE) +void gwinSetSliderColors(GHandle gh, const GSliderColors *pStyle); /** * @brief Get the current slider position. @@ -190,69 +139,35 @@ void gwinSetSliderCustom(GHandle gh, GSliderDrawFunction fn, void *param); #define gwinGetSliderPosition(gh) (((GSliderObject *)(gh))->pos) /** - * @brief Get the source handle of a slider - * @details Get the source handle of a slider so the application can listen for events + * @brief Some custom slider drawing routines + * @details These function may be passed to @p gwinSetCustomDraw() to get different slider drawing styles * - * @param[in] gh The window handle - * - * @api - */ -#define gwinGetSliderSource(gh) ((GSourceHandle)(gh)) - -#if GFX_USE_GINPUT && GINPUT_NEED_MOUSE - /** - * @brief Attach a mouse source - * @details Attach a mouse to a slider - * - * @param[in] gh The slider handle - * @param[in] instance The mouse instance - * - * @api - */ - bool_t gwinAttachSliderMouse(GHandle gh, uint16_t instance); -#endif - -#if GFX_USE_GINPUT && GINPUT_NEED_DIAL - /** - * @brief Attach a dial source - * @details Attach a dial to a slider - * - * @param[in] gh The dial handle - * @param[in] instance The dial instance - * - * @api - */ - bool_t gwinAttachSliderDial(GHandle gh, uint16_t instance); -#endif - -/** - * @brief Standard slider drawing routines - * @details This routine is called to draw the standard slider. - * - * @param[in] gh The slider handle - * @param[in] isVertical The slider is vertically oriented instead of horizontal - * @param[in] thumbpos The position of the slider (0..cx-1 or cy-1..0) - * @param[in] pstyle The current drawing style + * @param[in] gw The widget (which must be a slider) * @param[in] param A parameter passed in from the user * * @note In your custom slider drawing function you may optionally call this * 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 GSliderDrawFunction type. - * @note When called by a slider the framework ensure that it is - * a slider object and sets up clipping to the slider 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 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 + * @{ */ -void gwinSliderDraw_Std(GHandle gh, bool_t isVertical, coord_t thumbpos, const GSliderDrawStyle *pstyle, void *param); +void gwinSliderDraw_Std(GWidgetObject *gw, void *param); +void gwinSliderDraw_Image(GWidgetObject *gw, void *param); +/* @} */ #ifdef __cplusplus } #endif -#endif /* GWIN_NEED_SLIDER */ - #endif /* _GWIN_SLIDER_H */ /** @} */ |