diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/gwin/button.h | 104 | ||||
-rw-r--r-- | include/gwin/graph.h | 117 |
2 files changed, 164 insertions, 57 deletions
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
}
|