2 * @defgroup Progressbar Progress bar
5 * @image html progressbar_inheritance_tree.png
6 * @image latex progressbar_inheritance_tree.eps
8 * The progress bar is a widget for visually representing the
9 * progress status of a given job/task.
11 * A progress bar may be horizontal or vertical. It may display an
12 * icon besides it, as well as primary and @b units labels. The
13 * former is meant to label the widget as a whole, while the
14 * latter, which is formatted with floating point values (and thus
15 * accepts a <c>printf</c>-style format string, like <c>"%1.2f
16 * units"</c>), is meant to label the widget's <b>progress
17 * value</b>. Label, icon and unit strings/objects are @b optional
20 * A progress bar may be @b inverted, in which case it gets its
21 * values inverted, i.e., high values being on the left or top and
22 * low values on the right or bottom, for horizontal and vertical modes
25 * The @b span of the progress, as set by
26 * elm_progressbar_span_size_set(), is its length (horizontally or
27 * vertically), unless one puts size hints on the widget to expand
28 * on desired directions, by any container. That length will be
29 * scaled by the object or applications scaling factor.
30 * Applications can query the progress bar for its value with
31 * elm_progressbar_value_get().
33 * This widget inherits from the @ref Layout one, so that all the
34 * functions acting on it also work for progress bar objects.
36 * This widget emits the following signals, besides the ones sent from
38 * @li @c "changed" - when the value is changed
41 * This widget has the following styles:
43 * - @c "wheel" (simple style, no text, no progression, only
44 * "pulse" effect is available)
46 * Default text parts of the progressbar widget that you can use for are:
47 * @li "default" - Label of the progressbar
49 * Default content parts of the progressbar widget that you can use for are:
50 * @li "icon" - An icon of the progressbar
52 * Supported elm_object common APIs.
53 * @li @ref elm_object_part_text_set
54 * @li @ref elm_object_part_text_get
55 * @li @ref elm_object_part_content_set
56 * @li @ref elm_object_part_content_get
57 * @li @ref elm_object_part_content_unset
59 * Here is an example on its usage:
60 * @li @ref progressbar_example
64 * Add a new progress bar widget to the given parent Elementary
67 * @param parent The parent object
68 * @return a new progress bar widget handle or @c NULL, on errors
70 * This function inserts a new progress bar widget on the canvas.
72 * @ingroup Progressbar
74 EAPI Evas_Object *elm_progressbar_add(Evas_Object *parent);
77 * Set whether a given progress bar widget is at "pulsing mode" or
80 * @param obj The progress bar object
81 * @param pulse @c EINA_TRUE to put @p obj in pulsing mode,
82 * @c EINA_FALSE to put it back to its default one
84 * By default, progress bars will display values from the low to
85 * high value boundaries. There are, though, contexts in which the
86 * progress of a given task is @b unknown. For such cases,
87 * one can set a progress bar widget to a "pulsing state", to give
88 * the user an idea that some computation is being held, but
89 * without exact progress values. In the default theme, it will
90 * animate its bar with the contents filling in constantly and back
91 * to non-filled, in a loop. To start and stop this pulsing
92 * animation, one has to explicitly call elm_progressbar_pulse().
94 * @see elm_progressbar_pulse_get()
95 * @see elm_progressbar_pulse()
97 * @ingroup Progressbar
99 EAPI void elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse);
102 * Get whether a given progress bar widget is at "pulsing mode" or
105 * @param obj The progress bar object
106 * @return @c EINA_TRUE, if @p obj is in pulsing mode, @c EINA_FALSE
107 * if it's in the default one (and on errors)
109 * @ingroup Progressbar
111 EAPI Eina_Bool elm_progressbar_pulse_get(const Evas_Object *obj);
114 * Start/stop a given progress bar "pulsing" animation, if its
117 * @param obj The progress bar object
118 * @param state @c EINA_TRUE, to @b start the pulsing animation,
119 * @c EINA_FALSE to @b stop it
121 * @note This call won't do anything if @p obj is not under "pulsing mode".
123 * @see elm_progressbar_pulse_set() for more details.
125 * @ingroup Progressbar
127 EAPI void elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state);
130 * Set the progress value (in percentage) on a given progress bar
133 * @param obj The progress bar object
134 * @param val The progress value (@b must be between @c 0.0 and @c
137 * Use this call to set progress bar levels.
139 * @note If you passes a value out of the specified range for @p
140 * val, it will be interpreted as the @b closest of the @b boundary
141 * values in the range.
143 * @ingroup Progressbar
145 EAPI void elm_progressbar_value_set(Evas_Object *obj, double val);
148 * Get the progress value (in percentage) on a given progress bar
151 * @param obj The progress bar object
152 * @return The value of the progressbar
154 * @see elm_progressbar_value_set() for more details
156 * @ingroup Progressbar
158 EAPI double elm_progressbar_value_get(const Evas_Object *obj);
161 * Set the (exact) length of the bar region of a given progress bar
164 * @param obj The progress bar object
165 * @param size The length of the progress bar's bar region
167 * This sets the minimum width (when in horizontal mode) or height
168 * (when in vertical mode) of the actual bar area of the progress
169 * bar @p obj. This in turn affects the object's minimum size. Use
170 * this when you're not setting other size hints expanding on the
171 * given direction (like weight and alignment hints) and you would
172 * like it to have a specific size.
174 * @note Icon, label and unit text around @p obj will require their
175 * own space, which will make @p obj to require more the @p size,
178 * @see elm_progressbar_span_size_get()
180 * @ingroup Progressbar
182 EAPI void elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size);
185 * Get the length set for the bar region of a given progress bar
188 * @param obj The progress bar object
189 * @return The length of the progress bar's bar region
191 * If that size was not set previously, with
192 * elm_progressbar_span_size_set(), this call will return @c 0.
194 * @ingroup Progressbar
196 EAPI Evas_Coord elm_progressbar_span_size_get(const Evas_Object *obj);
199 * Set the format string for a given progress bar widget's units
202 * @param obj The progress bar object
203 * @param format The format string for @p obj's units label
205 * If @c NULL is passed on @p format, it will make @p obj's units
206 * area to be hidden completely. If not, it'll set the <b>format
207 * string</b> for the units label's @b text. The units label is
208 * provided a floating point value, so the units text is up display
209 * at most one floating point value. Note that the units label is
210 * optional. Use a format string such as "%1.2f meters" for
213 * @note The default format string for a progress bar is an integer
214 * percentage, as in @c "%.0f %%".
216 * @see elm_progressbar_unit_format_get()
218 * @ingroup Progressbar
220 EAPI void elm_progressbar_unit_format_set(Evas_Object *obj, const char *format);
223 * Retrieve the format string set for a given progress bar widget's
226 * @param obj The progress bar object
227 * @return The format set string for @p obj's units label or
228 * @c NULL, if none was set (and on errors)
230 * @see elm_progressbar_unit_format_set() for more details
232 * @ingroup Progressbar
234 EAPI const char *elm_progressbar_unit_format_get(const Evas_Object *obj);
237 * Set the format function pointer for the units label
239 * @param obj The progress bar object
240 * @param func The unit format function
241 * @param free_func The freeing function for the format string.
243 * Set the callback function to format the unit string.
245 * @see elm_progressbar_unit_format_set() for more info on how this works.
249 * @ingroup Progressbar
251 EAPI void elm_progressbar_unit_format_function_set(Evas_Object *obj, char *(func)(double), void (*free_func) (char *));
254 * Set the orientation of a given progress bar widget
256 * @param obj The progress bar object
257 * @param horizontal Use @c EINA_TRUE to make @p obj to be
258 * @b horizontal, @c EINA_FALSE to make it @b vertical
260 * Use this function to change how your progress bar is to be
261 * disposed: vertically or horizontally.
263 * @see elm_progressbar_horizontal_get()
265 * @ingroup Progressbar
267 EAPI void elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
270 * Retrieve the orientation of a given progress bar widget
272 * @param obj The progress bar object
273 * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
274 * @c EINA_FALSE if it's @b vertical (and on errors)
276 * @see elm_progressbar_horizontal_set() for more details
278 * @ingroup Progressbar
280 EAPI Eina_Bool elm_progressbar_horizontal_get(const Evas_Object *obj);
283 * Invert a given progress bar widget's displaying values order
285 * @param obj The progress bar object
286 * @param inverted Use @c EINA_TRUE to make @p obj inverted,
287 * @c EINA_FALSE to bring it back to default, non-inverted values.
289 * A progress bar may be @b inverted, in which state it gets its
290 * values inverted, with high values being on the left or top and
291 * low values on the right or bottom, as opposed to normally have
292 * the low values on the former and high values on the latter,
293 * respectively, for horizontal and vertical modes.
295 * @see elm_progressbar_inverted_get()
297 * @ingroup Progressbar
299 EAPI void elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted);
302 * Get whether a given progress bar widget's displaying values are
305 * @param obj The progress bar object
306 * @return @c EINA_TRUE, if @p obj has inverted values,
307 * @c EINA_FALSE otherwise (and on errors)
309 * @see elm_progressbar_inverted_set() for more details
311 * @ingroup Progressbar
313 EAPI Eina_Bool elm_progressbar_inverted_get(const Evas_Object *obj);