version 2.8
gwin_graph.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gwin/gwin_graph.h
10  * @brief GWIN GRAPH module header file
11  *
12  * @defgroup Graph Graph
13  * @ingroup Windows
14  *
15  * @brief Graph window. Used to display highly customizable graphs.
16  *
17  * @details GWIN allows it to easily draw graphs.
18  *
19  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
20  * @pre GWIN_NEED_GRAPH must be set to TRUE in your gfxconf.h
21  *
22  * @{
23  */
24 
25 #ifndef _GWIN_GRAPH_H
26 #define _GWIN_GRAPH_H
27 
28 /* This file is included within "src/gwin/gwin.h" */
29 
30 typedef enum GGraphPointType_e {
31  GGRAPH_POINT_NONE, GGRAPH_POINT_DOT, GGRAPH_POINT_SQUARE, GGRAPH_POINT_CIRCLE
32  } GGraphPointType;
33 
34 typedef struct GGraphPointStyle_t {
35  GGraphPointType type;
36  coord_t size;
37  color_t color;
38  } GGraphPointStyle;
39 
40 typedef enum GGraphLineType_e {
41  GGRAPH_LINE_NONE, GGRAPH_LINE_SOLID, GGRAPH_LINE_DOT, GGRAPH_LINE_DASH
42  } GGraphLineType;
43 
44 typedef struct GGraphLineStyle_t {
45  GGraphLineType type;
46  coord_t size;
47  color_t color;
48  } GGraphLineStyle;
49 
50 typedef struct GGraphGridStyle_t {
51  GGraphLineType type;
52  coord_t size;
53  color_t color;
54  coord_t spacing;
55  } GGraphGridStyle;
56 
57 typedef struct GGraphStyle_t {
58  GGraphPointStyle point;
59  GGraphLineStyle line;
60  GGraphLineStyle xaxis;
61  GGraphLineStyle yaxis;
62  GGraphGridStyle xgrid;
63  GGraphGridStyle ygrid;
64  uint16_t flags;
65  #define GWIN_GRAPH_STYLE_XAXIS_POSITIVE_ARROWS 0x0001
66  #define GWIN_GRAPH_STYLE_XAXIS_NEGATIVE_ARROWS 0x0002
67  #define GWIN_GRAPH_STYLE_YAXIS_POSITIVE_ARROWS 0x0004
68  #define GWIN_GRAPH_STYLE_YAXIS_NEGATIVE_ARROWS 0x0008
69  #define GWIN_GRAPH_STYLE_POSITIVE_AXIS_ARROWS (GWIN_GRAPH_STYLE_XAXIS_POSITIVE_ARROWS|GWIN_GRAPH_STYLE_YAXIS_POSITIVE_ARROWS)
70  #define GWIN_GRAPH_STYLE_NEGATIVE_AXIS_ARROWS (GWIN_GRAPH_STYLE_XAXIS_NEGATIVE_ARROWS|GWIN_GRAPH_STYLE_YAXIS_NEGATIVE_ARROWS)
71  #define GWIN_GRAPH_STYLE_XAXIS_ARROWS (GWIN_GRAPH_STYLE_XAXIS_POSITIVE_ARROWS|GWIN_GRAPH_STYLE_XAXIS_NEGATIVE_ARROWS)
72  #define GWIN_GRAPH_STYLE_YAXIS_ARROWS (GWIN_GRAPH_STYLE_YAXIS_POSITIVE_ARROWS|GWIN_GRAPH_STYLE_YAXIS_NEGATIVE_ARROWS)
73  #define GWIN_GRAPH_STYLE_ALL_AXIS_ARROWS (GWIN_GRAPH_STYLE_XAXIS_ARROWS|GWIN_GRAPH_STYLE_YAXIS_ARROWS)
74 } GGraphStyle;
75 
76 // A graph window
77 typedef struct GGraphObject {
78  GWindowObject g;
79  GGraphStyle style;
80  coord_t xorigin, yorigin;
81  coord_t lastx, lasty;
82  } GGraphObject;
83 
84 /*===========================================================================*/
85 /* External declarations. */
86 /*===========================================================================*/
87 
88 #ifdef __cplusplus
89 extern "C" {
90 #endif
91 
92 /**
93  * @brief Create a graph window.
94  * @return NULL if there is no resultant drawing area, otherwise a window handle.
95  *
96  * @param[in] g The GDisplay to display this window on
97  * @param[in] gg The GGraphObject structure to initialise. If this is NULL the structure is dynamically allocated.
98  * @param[in] pInit The initialization parameters to use
99  *
100  * @note The drawing color and the background color get set to the current defaults. If you haven't called
101  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
102  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
103  * is no default font and text drawing operations will no nothing.
104  * @note The dimensions and position may be changed to fit on the real screen.
105  * @note A graph does not save the drawing state. It is not automatically redrawn if the window is moved or
106  * its visibility state is changed.
107  * @note The coordinate system within the window for graphing operations (but not for any other drawing
108  * operation) is relative to the bottom left corner and then shifted right and up by the specified
109  * graphing x and y origin. Note that this system is inverted in the y direction relative to the display.
110  * This gives the best graphing arrangement ie. increasing y values are closer to the top of the display.
111  *
112  * @api
113  */
114 GHandle gwinGGraphCreate(GDisplay *g, GGraphObject *gg, const GWindowInit *pInit);
115 #define gwinGraphCreate(gg, pInit) gwinGGraphCreate(GDISP, gg, pInit)
116 
117 /**
118  * @brief Set the style of the graphing operations.
119  *
120  * @param[in] gh The window handle (must be a graph window)
121  * @param[in] pstyle The graph style to set.
122  * @note The graph is not automatically redrawn. The new style will apply to any new drawing operations.
123  *
124  * @api
125  */
126 void gwinGraphSetStyle(GHandle gh, const GGraphStyle *pstyle);
127 
128 /**
129  * @brief Set the origin for graphing operations.
130  *
131  * @param[in] gh The window handle (must be a graph window)
132  * @param[in] x, y The new origin for the graph (in graph coordinates relative to the bottom left corner).
133  * @note The graph is not automatically redrawn. The new origin will apply to any new drawing operations.
134  *
135  * @api
136  */
138 
139 /**
140  * @brief Draw the axis and the background grid.
141  *
142  * @param[in] gh The window handle (must be a graph window)
143  * @note The graph is not automatically cleared. You must do that first by calling gwinClear().
144  *
145  * @api
146  */
147 void gwinGraphDrawAxis(GHandle gh);
148 
149 /**
150  * @brief Start a new set of graphing data.
151  * @details This prevents a line being drawn from the last data point to the next point to be drawn.
152  *
153  * @param[in] gh The window handle (must be a graph window)
154  *
155  * @api
156  */
157 void gwinGraphStartSet(GHandle gh);
158 
159 /**
160  * @brief Draw a graph point.
161  * @details A graph point and a line connecting to the previous point will be drawn.
162  *
163  * @param[in] gh The window handle (must be a graph window)
164  * @param[in] x, y The new point for the graph.
165  *
166  * @api
167  */
169 
170 /**
171  * @brief Draw multiple graph points.
172  * @details A graph point and a line connecting to each previous point will be drawn.
173  *
174  * @param[in] gh The window handle (must be a graph window)
175  * @param[in] points The array of points for the graph.
176  * @param[in] count The number of points in the array.
177  * @note This is slightly more efficient than calling gwinGraphDrawPoint() repeatedly.
178  *
179  * @api
180  */
181 void gwinGraphDrawPoints(GHandle gh, const point *points, unsigned count);
182 
183 #ifdef __cplusplus
184 }
185 #endif
186 
187 #endif /* _GWIN_GRAPH_H */
188 /** @} */
189 
The structure to initialise a GWIN.
Definition: gwin.h:75
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
GHandle gwinGGraphCreate(GDisplay *g, GGraphObject *gg, const GWindowInit *pInit)
Create a graph window.
void gwinGraphSetStyle(GHandle gh, const GGraphStyle *pstyle)
Set the style of the graphing operations.
void gwinGraphDrawPoints(GHandle gh, const point *points, unsigned count)
Draw multiple graph points.
void gwinGraphSetOrigin(GHandle gh, coord_t x, coord_t y)
Set the origin for graphing operations.
void gwinGraphStartSet(GHandle gh)
Start a new set of graphing data.
void gwinGraphDrawAxis(GHandle gh)
Draw the axis and the background grid.
void gwinGraphDrawPoint(GHandle gh, coord_t x, coord_t y)
Draw a graph point.
Type for a 2D point on the screen.
Definition: gdisp.h:51
A window object structure.
Definition: gwin.h:40
COLOR_TYPE color_t
The color type definition.
Definition: gdisp_colors.h:412