diff --git a/include/gwin/button.h b/include/gwin/button.h index 698c840a..ffec858b 100644 --- a/include/gwin/button.h +++ b/include/gwin/button.h @@ -97,24 +97,92 @@ typedef struct GButtonObject_t { extern "C" { #endif - GHandle gwinCreateButton(GButtonObject *gb, coord_t x, coord_t y, coord_t width, coord_t height, font_t font, GButtonType type); - void gwinSetButtonStyle(GHandle gh, const GButtonStyle *style); - void gwinSetButtonText(GHandle gh, const char *txt, bool_t useAlloc); - void gwinButtonDraw(GHandle gh); - #define gwinGetButtonState(gh) (((GButtonObject *)(gh))->state) +/** + * @brief Create a button window. + * @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. + * + * @api + */ +GHandle gwinCreateButton(GButtonObject *gb, coord_t x, coord_t y, coord_t width, coord_t height, font_t font, GButtonType type); - // Get the source handle so the application can listen for events - #define gwinGetButtonSource(gh) ((GSourceHandle)(gh)) +/** + * @brief Set the style of a button. + * @details The button style is defined by its shape and colours. + * + * @param[in] gh The window handle (must be a button window) + * @param[in] style The button style to set. + * @note The button is not automatically redrawn. Call gwinButtonDraw() after changing the button style + * + * @api + */ +void gwinSetButtonStyle(GHandle gh, const GButtonStyle *style); - #if defined(GINPUT_NEED_MOUSE) && GINPUT_NEED_MOUSE - // Attach a mouse source to this button. - bool_t gwinAttachButtonMouseSource(GHandle gh, GSourceHandle gsh); - #endif +/** + * @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); - #if defined(GINPUT_NEED_TOGGLE) && GINPUT_NEED_TOGGLE - // Attach a toggle source to this button. - bool_t gwinAttachButtonToggleSource(GHandle gh, GSourceHandle gsh); - #endif +/** + * @brief Redraw the button. + * + * @param[in] gh The window handle (must be a button window) + * + * @api + */ +void gwinButtonDraw(GHandle gh); + +#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 Hanlde + */ +#define gwinGetButtonSource(gh) ((GSourceHandle)(gh)) + +#if defined(GINPUT_NEED_MOUSE) && GINPUT_NEED_MOUSE + /** + * @brief Attach a mouse source + * @details Attach a mouse source to a given button + * + * @param[in] gh The button handle + * @param[in] gsh The source handle + * + * @return + */ + bool_t gwinAttachButtonMouseSource(GHandle gh, GSourceHandle gsh); +#endif + +#if defined(GINPUT_NEED_TOGGLE) && GINPUT_NEED_TOGGLE + /** + * @brief Attach a toggle source + * @details Attach a toggle source to this button + * + * @gh The button handle + * @gsh The source handle + * + * @return + */ + bool_t gwinAttachButtonToggleSource(GHandle gh, GSourceHandle gsh); +#endif #ifdef __cplusplus } diff --git a/include/gwin/graph.h b/include/gwin/graph.h index 155fd9a9..9267813b 100644 --- a/include/gwin/graph.h +++ b/include/gwin/graph.h @@ -113,50 +113,89 @@ typedef struct GGraphObject_t { extern "C" { #endif - GHandle gwinCreateGraph(GGraphObject *gg, coord_t x, coord_t y, coord_t width, coord_t height); - void gwinGraphSetStyle(GHandle gh, const GGraphStyle *pstyle); - void gwinGraphSetOrigin(GHandle gh, coord_t x, coord_t y); - void gwinGraphDrawAxis(GHandle gh); - void gwinGraphStartSet(GHandle gh); - void gwinGraphDrawPoint(GHandle gh, coord_t x, coord_t y); - void gwinGraphDrawPoints(GHandle gh, const GGraphPoint *points, unsigned count); +/** + * @brief Create a graph window. + * @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) + * @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. + * This gives the best graphing arrangement ie. increasing y values are closer to the top of the display. + * + * @api + */ +GHandle gwinCreateGraph(GGraphObject *gg, coord_t x, coord_t y, coord_t width, coord_t height); -#ifdef __cplusplus -} -#endif +/** + * @brief Set the style of the graphing operations. + * + * @param[in] gh The window handle (must be a graph window) + * @param[in] pstyle The graph style to set. + * @note The graph is not automatically redrawn. The new style will apply to any new drawing operations. + * + * @api + */ +void gwinGraphSetStyle(GHandle gh, const GGraphStyle *pstyle); -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ +/** + * @brief Set the origin for graphing operations. + * + * @param[in] gh The window handle (must be a graph window) + * @param[in] x, y The new origin for the graph (in graph coordinates relative to the bottom left corner). + * @note The graph is not automatically redrawn. The new origin will apply to any new drawing operations. + * + * @api + */ +void gwinGraphSetOrigin(GHandle gh, coord_t x, coord_t y); -typedef struct _Graph { - coord_t origin_x; - coord_t origin_y; - coord_t xmin; - coord_t xmax; - coord_t ymin; - coord_t ymax; - uint16_t grid_size; - uint16_t dot_space; - bool_t full_grid; - bool_t arrows; - color_t axis_color; - color_t grid_color; +/** + * @brief Draw the axis and the background grid. + * + * @param[in] gh The window handle (must be a graph window) + * @note The graph is not automatically cleared. You must do that first by calling gwinClear(). + * + * @api + */ +void gwinGraphDrawAxis(GHandle gh); - /* do never modify values below this line manually */ - coord_t x0; - coord_t x1; - coord_t y0; - coord_t y1; -} Graph; +/** + * @brief Start a new set of graphing data. + * @details This prevents a line being drawn from the last data point to the next point to be drawn. + * + * @param[in] gh The window handle (must be a graph window) + * + * @api + */ +void gwinGraphStartSet(GHandle gh); -#ifdef __cplusplus -extern "C" { -#endif +/** + * @brief Draw a graph point. + * @details A graph point and a line connecting to the previous point will be drawn. + * + * @param[in] gh The window handle (must be a graph window) + * @param[in] x, y The new point for the graph. + * + * @api + */ +void gwinGraphDrawPoint(GHandle gh, coord_t x, coord_t y); -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ +/** + * @brief Draw multiple graph points. + * @details A graph point and a line connecting to each previous point will be drawn. + * + * @param[in] gh The window handle (must be a graph window) + * @param[in] points The array of points for the graph. + * @param[in] count The number of points in the array. + * @note This is slightly more efficient than calling gwinGraphDrawPoint() repeatedly. + * + * @api + */ +void gwinGraphDrawPoints(GHandle gh, const GGraphPoint *points, unsigned count); #ifdef __cplusplus } diff --git a/src/gwin/button.c b/src/gwin/button.c index 9a06f4fe..8a904d95 100644 --- a/src/gwin/button.c +++ b/src/gwin/button.c @@ -131,22 +131,6 @@ static void gwinButtonCallback(void *param, GEvent *pe) { #undef gh } -/** - * @brief Create a button window. - * @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. - * - * @api - */ GHandle gwinCreateButton(GButtonObject *gb, coord_t x, coord_t y, coord_t width, coord_t height, font_t font, GButtonType type) { if (!(gb = (GButtonObject *)_gwinInit((GWindowObject *)gb, x, y, width, height, sizeof(GButtonObject)))) return 0; @@ -161,16 +145,6 @@ GHandle gwinCreateButton(GButtonObject *gb, coord_t x, coord_t y, coord_t width, return (GHandle)gb; } -/** - * @brief Set the style of a button. - * @details The button style is defined by its shape and colours. - * - * @param[in] gh The window handle (must be a button window) - * @param[in] style The button style to set. - * @note The button is not automatically redrawn. Call gwinButtonDraw() after changing the button style - * - * @api - */ void gwinSetButtonStyle(GHandle gh, const GButtonStyle *style) { #define gbw ((GButtonObject *)gh) if (gh->type != GW_BUTTON) @@ -186,16 +160,6 @@ void gwinSetButtonStyle(GHandle gh, const GButtonStyle *style) { #undef gbw } -/** - * @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) { #define gbw ((GButtonObject *)gh) if (gh->type != GW_BUTTON) @@ -224,13 +188,6 @@ void gwinSetButtonText(GHandle gh, const char *txt, bool_t useAlloc) { #undef gbw } -/** - * @brief Redraw the button. - * - * @param[in] gh The window handle (must be a button window) - * - * @api - */ void gwinButtonDraw(GHandle gh) { color_t cedge; color_t cfill; diff --git a/src/gwin/graph.c b/src/gwin/graph.c index b75d76ee..a9d20c4b 100644 --- a/src/gwin/graph.c +++ b/src/gwin/graph.c @@ -176,22 +176,6 @@ static void lineto(GGraphObject *gg, coord_t x0, coord_t y0, coord_t x1, coord_t } } -/** - * @brief Create a graph window. - * @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) - * @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. - * This gives the best graphing arrangement ie. increasing y values are closer to the top of the display. - * - * @api - */ GHandle gwinCreateGraph(GGraphObject *gg, coord_t x, coord_t y, coord_t width, coord_t height) { if (!(gg = (GGraphObject *)_gwinInit((GWindowObject *)gg, x, y, width, height, sizeof(GGraphObject)))) return 0; @@ -202,15 +186,6 @@ GHandle gwinCreateGraph(GGraphObject *gg, coord_t x, coord_t y, coord_t width, c return (GHandle)gg; } -/** - * @brief Set the style of the graphing operations. - * - * @param[in] gh The window handle (must be a graph window) - * @param[in] pstyle The graph style to set. - * @note The graph is not automatically redrawn. The new style will apply to any new drawing operations. - * - * @api - */ void gwinGraphSetStyle(GHandle gh, const GGraphStyle *pstyle) { #define gg ((GGraphObject *)gh) @@ -242,15 +217,6 @@ void gwinGraphSetStyle(GHandle gh, const GGraphStyle *pstyle) { #undef gg } -/** - * @brief Set the origin for graphing operations. - * - * @param[in] gh The window handle (must be a graph window) - * @param[in] x, y The new origin for the graph (in graph coordinates relative to the bottom left corner). - * @note The graph is not automatically redrawn. The new origin will apply to any new drawing operations. - * - * @api - */ void gwinGraphSetOrigin(GHandle gh, coord_t x, coord_t y) { #define gg ((GGraphObject *)gh) @@ -263,14 +229,6 @@ void gwinGraphSetOrigin(GHandle gh, coord_t x, coord_t y) { #undef gg } -/** - * @brief Draw the axis and the background grid. - * - * @param[in] gh The window handle (must be a graph window) - * @note The graph is not automatically cleared. You must do that first by calling gwinClear(). - * - * @api - */ void gwinGraphDrawAxis(GHandle gh) { #define gg ((GGraphObject *)gh) coord_t i, xmin, ymin, xmax, ymax; @@ -332,14 +290,6 @@ void gwinGraphDrawAxis(GHandle gh) { #undef gg } -/** - * @brief Start a new set of graphing data. - * @details This prevents a line being drawn from the last data point to the next point to be drawn. - * - * @param[in] gh The window handle (must be a graph window) - * - * @api - */ void gwinGraphStartSet(GHandle gh) { if (gh->type != GW_GRAPH) return; @@ -347,15 +297,6 @@ void gwinGraphStartSet(GHandle gh) { gh->flags &= ~GGRAPH_FLG_CONNECTPOINTS; } -/** - * @brief Draw a graph point. - * @details A graph point and a line connecting to the previous point will be drawn. - * - * @param[in] gh The window handle (must be a graph window) - * @param[in] x, y The new point for the graph. - * - * @api - */ void gwinGraphDrawPoint(GHandle gh, coord_t x, coord_t y) { #define gg ((GGraphObject *)gh) @@ -382,17 +323,6 @@ void gwinGraphDrawPoint(GHandle gh, coord_t x, coord_t y) { #undef gg } -/** - * @brief Draw multiple graph points. - * @details A graph point and a line connecting to each previous point will be drawn. - * - * @param[in] gh The window handle (must be a graph window) - * @param[in] points The array of points for the graph. - * @param[in] count The number of points in the array. - * @note This is slightly more efficient than calling gwinGraphDrawPoint() repeatedly. - * - * @api - */ void gwinGraphDrawPoints(GHandle gh, const GGraphPoint *points, unsigned count) { #define gg ((GGraphObject *)gh) unsigned i;