From b6a8a15536b450049a4985d36825317b633af6b1 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Fri, 21 Dec 2012 15:18:22 +0100 Subject: doxygen & cleanup --- include/gwin/button.h | 104 ++++++++++++++++++++++++++++++++++++-------- include/gwin/graph.h | 117 +++++++++++++++++++++++++++++++++----------------- 2 files changed, 164 insertions(+), 57 deletions(-) (limited to 'include/gwin') 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) - - // Get the source handle so the application can listen for events - #define gwinGetButtonSource(gh) ((GSourceHandle)(gh)) - - #if defined(GINPUT_NEED_MOUSE) && GINPUT_NEED_MOUSE - // Attach a mouse source to this button. - bool_t gwinAttachButtonMouseSource(GHandle gh, GSourceHandle gsh); - #endif - - #if defined(GINPUT_NEED_TOGGLE) && GINPUT_NEED_TOGGLE - // Attach a toggle source to this button. - bool_t gwinAttachButtonToggleSource(GHandle gh, GSourceHandle gsh); - #endif +/** + * @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); + +/** + * @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); + +/** + * @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); + +#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; - - /* do never modify values below this line manually */ - coord_t x0; - coord_t x1; - coord_t y0; - coord_t y1; -} Graph; +/** + * @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); -#ifdef __cplusplus -extern "C" { -#endif +/** + * @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); -/*===========================================================================*/ -/* Type definitions */ -/*===========================================================================*/ +/** + * @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); + +/** + * @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 } -- cgit v1.2.3