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/graph.h | 117 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 78 insertions(+), 39 deletions(-) (limited to 'include/gwin/graph.h') 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