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