version 2.8
gwin_progressbar.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_progressbar.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Progressbar Progressbar
13  * @ingroup Widgets
14  *
15  * @brief ProgressBar widget.
16  *
17  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
18  * @pre GWIN_NEED_PROGRESSBAR must be set to TRUE in your gfxconf.h
19  * @{
20  */
21 
22 #ifndef _GWIN_PROGRESSBAR_H
23 #define _GWIN_PROGRESSBAR_H
24 
25 /* This file is included within src/gwin/gwin_widget.h */
26 // A progressbar window
27 typedef struct GProgressbarObject {
28  GWidgetObject w;
29  coord_t dpos;
30  int min;
31  int max;
32  int res;
33  int pos;
34  #if GWIN_PROGRESSBAR_AUTO
35  GTimer gt;
36  #endif
37 } GProgressbarObject;
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /**
44  * @brief Create a progressbar window.
45  * @return NULL if there is no resultant drawing area, otherwise a window handle.
46  *
47  * @param[in] g The GDisplay to display this window on
48  * @param[in] gb The GProgressbarObject structure to initialise. If this is NULL the structure is dynamically allocated.
49  * @param[in] pInit The initialization parameters to use
50  *
51  * @note The drawing color and the background color get set to the current defaults. If you haven't called
52  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
53  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
54  * is no default font and text drawing operations will no nothing.
55  * @note A progressbar remembers its normal drawing state. If there is a window manager then it is automatically
56  * redrawn if the window is moved or its visibility state is changed.
57  * @note The initial progressbar range is from 0 to 100 with an initial position of 0.
58  * @note A progressbar does not take any GINPUT inputs.
59  *
60  * @api
61  */
62 GHandle gwinGProgressbarCreate(GDisplay *g, GProgressbarObject *gb, const GWidgetInit *pInit);
63 #define gwinProgressbarCreate(w, pInit) gwinGProgressbarCreate(GDISP, w, pInit)
64 
65 /**
66  * @brief Set the progressbar range.
67  *
68  * @param[in] gh The window handle (must be a progressbar window)
69  * @param[in] min The minimum value
70  * @param[in] max The maximum value
71  *
72  * @note The defaults are 0 and 100
73  * @note Sets the position to the minimum value.
74  * @note The progressbar is not automatically drawn. Call gwinProgressbarDraw() after changing the range.
75  *
76  * @api
77  */
78 void gwinProgressbarSetRange(GHandle gh, int min, int max);
79 
80 /**
81  * @brief Set the progressbar position.
82  *
83  * @param[in] gh The window handle (must be a progressbar window)
84  * @param[in] pos The new position
85  *
86  * @note If the new position is outside the progressbar range then the position
87  * is set to the closest end of the range.
88  * @note The progressbar is not automatically drawn. Call gwinProgressbarDraw() after changing the position.
89  *
90  * @api
91  */
92 void gwinProgressbarSetPosition(GHandle gh, int pos);
93 
94 /**
95  * @brief Set the resolution for the incrementation and decrementation of the progressbar
96  *
97  * @note Default is set to 1
98  *
99  * @param[in] gh The window handle (must be a progressbar window)
100  * @param[in] res The resolution to be set
101  *
102  * @api
103  */
104 void gwinProgressbarSetResolution(GHandle gh, int res);
105 
106 /**
107  * @brief Increment the progressbar value
108  *
109  * @details Increments by the resolution set through gwinProgressbarSetResolution()
110  *
111  * @param[in] gh The window handle (must be a progressbar window)
112  *
113  * @api
114  */
116 
117 /**
118  * @brief Decrement the progressbar value
119  *
120  * @details Decrements by the resolution set through gwinProgressbarSetResolution()
121  *
122  * @param[in] gh The window handle (must be a progressbar window)
123  *
124  * @api
125  */
127 
128 /**
129  * @brief Get the current progressbar position.
130  * @return The progressbar position
131  *
132  * @param[in] gh The window handle (must be a progressbar window)
133  *
134  * @note The use of a listener to get the progressbar position is recommended if you
135  * want continuous updates on the progressbar position.
136  *
137  * @api
138  */
139 #define gwinProgressbarGetPosition(gh) (((GProgressbarObject *)(gh))->pos)
140 
141  /**
142  * @brief Reset the progressbar to the minimum position
143  *
144  * @param[in] gh The window handle (must be a progressbar window)
145  *
146  * @api
147  */
148 #define gwinProgressbarReset(gh) gwinProgressbarSetPosition(gh, ((GProgressbarObject *)(gh))->min)
149 
150 #if GWIN_PROGRESSBAR_AUTO || defined(__DOXYGEN__)
151  /**
152  * @brief Automatically increments the progress bar
153  *
154  * @note The delay is generated using the GTIMER module which is based on software/virtual timer.
155  * Therefore, the delay is totally unprecise.
156  *
157  * @note The progressbar incrementation starts at the current level. It is not reset to the minimum value.
158  *
159  * @note An event is generated once the maximum value has been reached (ToDo)
160  *
161  * @param[in] gh The window handle (must be a progressbar window)
162  * @param[in] delay The incrementation delay (in milliseconds)
163  *
164  * @api
165  */
166  void gwinProgressbarStart(GHandle gh, delaytime_t delay);
167 
168  /**
169  * @brief Stop the timer which is started by @p gwinProgressbarStart()
170  *
171  * @param[in] gh The window handle (must be a progressbar window)
172  *
173  * @api
174  */
175  void gwinProgressbarStop(GHandle gh);
176 #endif /* GWIN_PROGRESSBAR_AUTO */
177 
178 /**
179  * @defgroup Renderings_Progressbar Renderings
180  *
181  * @brief Built-in rendering functions for the progressbar widget.
182  *
183  * @details These function may be passed to @p gwinSetCustomDraw() to get different progressbar drawing styles.
184  *
185  * @note In your custom progressbar drawing function you may optionally call these
186  * standard functions and then draw your extra details on top.
187  * @note These custom drawing routines don't have to worry about setting clipping as the framework
188  * sets clipping to the object window prior to calling these routines.
189  *
190  * @{
191  */
192 
193 /**
194  * @brief The default rendering function for the progressbar widget
195  *
196  * @param[in] gw The widget object (must be a progressbar object)
197  * @param[in] param A parameter passed in from the user. Ignored by this function.
198  *
199  * @api
200  */
201 void gwinProgressbarDraw_Std(GWidgetObject *gw, void *param);
202 
203 #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
204  /**
205  * @brief Renders a progressbar using an image.
206  *
207  * @param[in] gw The widget object (must be a progressbar handle)
208  * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
209  *
210  * @note The image must be already opened before calling @p gwinSetCustomDraw().
211  * @note The image is tiled to fill the active area of the progressbar. The normal colors
212  * apply to the border and inactive area and the dividing line between the active
213  * and inactive areas. No checking is done to compare the dimensions of the progressbar
214  * to the size of the image. Note text is drawn on top of the image.
215  *
216  * @pre GDISP_NEED_IMAGE must be set to TRUE
217  *
218  * @api
219  */
220  void gwinProgressbarDraw_Image(GWidgetObject *gw, void *param);
221 #endif /* GDISP_NEED_IMAGE */
222 /** @} */
223 
224 #ifdef __cplusplus
225 }
226 #endif
227 
228 #endif /* _GWIN_PROGRESSBAR_H */
229 /** @} */
#define gt(str)
A wrapper macro to make writing and reading translatable applications easier.
Definition: gtrans.h:41
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
A GTimer structure.
Definition: gtimer.h:52
The structure to initialise a widget.
Definition: gwin_widget.h:97
GHandle gwinGProgressbarCreate(GDisplay *g, GProgressbarObject *gb, const GWidgetInit *pInit)
Create a progressbar window.
void gwinProgressbarSetResolution(GHandle gh, int res)
Set the resolution for the incrementation and decrementation of the progressbar.
void gwinProgressbarSetRange(GHandle gh, int min, int max)
Set the progressbar range.
The GWIN Widget structure.
Definition: gwin_widget.h:118
void gwinProgressbarDecrement(GHandle gh)
Decrement the progressbar value.
void gwinProgressbarIncrement(GHandle gh)
Increment the progressbar value.
void gwinProgressbarStop(GHandle gh)
Stop the timer which is started by gwinProgressbarStart()
A window object structure.
Definition: gwin.h:40
void gwinProgressbarDraw_Std(GWidgetObject *gw, void *param)
The default rendering function for the progressbar widget.
void gwinProgressbarSetPosition(GHandle gh, int pos)
Set the progressbar position.
void gwinProgressbarDraw_Image(GWidgetObject *gw, void *param)
Renders a progressbar using an image.
void gwinProgressbarStart(GHandle gh, delaytime_t delay)
Automatically increments the progress bar.