2 * @defgroup Progressbar Progress bar
4 * The progress bar is a widget for visually representing the
5 * progress status of a given job/task.
7 * A progress bar may be horizontal or vertical. It may display an
8 * icon besides it, as well as primary and @b units labels. The
9 * former is meant to label the widget as a whole, while the
10 * latter, which is formatted with floating point values (and thus
11 * accepts a <c>printf</c>-style format string, like <c>"%1.2f
12 * units"</c>), is meant to label the widget's <b>progress
13 * value</b>. Label, icon and unit strings/objects are @b optional
16 * A progress bar may be @b inverted, in which state it gets its
17 * values inverted, with high values being on the left or top and
18 * low values on the right or bottom, as opposed to normally have
19 * the low values on the former and high values on the latter,
20 * respectively, for horizontal and vertical modes.
22 * The @b span of the progress, as set by
23 * elm_progressbar_span_size_set(), is its length (horizontally or
24 * vertically), unless one puts size hints on the widget to expand
25 * on desired directions, by any container. That length will be
26 * scaled by the object or applications scaling factor. At any
27 * point code can query the progress bar for its value with
28 * elm_progressbar_value_get().
30 * Available widget styles for progress bars:
32 * - @c "wheel" (simple style, no text, no progression, only
33 * "pulse" effect is available)
35 * Default contents parts of the progressbar widget that you can use for are:
36 * @li "icon" - An icon of the progressbar
38 * Here is an example on its usage:
39 * @li @ref progressbar_example
43 * Add a new progress bar widget to the given parent Elementary
46 * @param parent The parent object
47 * @return a new progress bar widget handle or @c NULL, on errors
49 * This function inserts a new progress bar widget on the canvas.
51 * @ingroup Progressbar
53 EAPI Evas_Object *elm_progressbar_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
56 * Set whether a given progress bar widget is at "pulsing mode" or
59 * @param obj The progress bar object
60 * @param pulse @c EINA_TRUE to put @p obj in pulsing mode,
61 * @c EINA_FALSE to put it back to its default one
63 * By default, progress bars will display values from the low to
64 * high value boundaries. There are, though, contexts in which the
65 * state of progression of a given task is @b unknown. For those,
66 * one can set a progress bar widget to a "pulsing state", to give
67 * the user an idea that some computation is being held, but
68 * without exact progress values. In the default theme it will
69 * animate its bar with the contents filling in constantly and back
70 * to non-filled, in a loop. To start and stop this pulsing
71 * animation, one has to explicitly call elm_progressbar_pulse().
73 * @see elm_progressbar_pulse_get()
74 * @see elm_progressbar_pulse()
76 * @ingroup Progressbar
78 EAPI void elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse) EINA_ARG_NONNULL(1);
81 * Get whether a given progress bar widget is at "pulsing mode" or
84 * @param obj The progress bar object
85 * @return @c EINA_TRUE, if @p obj is in pulsing mode, @c EINA_FALSE
86 * if it's in the default one (and on errors)
88 * @ingroup Progressbar
90 EAPI Eina_Bool elm_progressbar_pulse_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
93 * Start/stop a given progress bar "pulsing" animation, if its
96 * @param obj The progress bar object
97 * @param state @c EINA_TRUE, to @b start the pulsing animation,
98 * @c EINA_FALSE to @b stop it
100 * @note This call won't do anything if @p obj is not under "pulsing mode".
102 * @see elm_progressbar_pulse_set() for more details.
104 * @ingroup Progressbar
106 EAPI void elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
109 * Set the progress value (in percentage) on a given progress bar
112 * @param obj The progress bar object
113 * @param val The progress value (@b must be between @c 0.0 and @c
116 * Use this call to set progress bar levels.
118 * @note If you passes a value out of the specified range for @p
119 * val, it will be interpreted as the @b closest of the @b boundary
120 * values in the range.
122 * @ingroup Progressbar
124 EAPI void elm_progressbar_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1);
127 * Get the progress value (in percentage) on a given progress bar
130 * @param obj The progress bar object
131 * @return The value of the progressbar
133 * @see elm_progressbar_value_set() for more details
135 * @ingroup Progressbar
137 EAPI double elm_progressbar_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
140 * Set the label of a given progress bar widget
142 * @param obj The progress bar object
143 * @param label The text label string, in UTF-8
145 * @ingroup Progressbar
146 * @deprecated use elm_object_text_set() instead.
148 EINA_DEPRECATED EAPI void elm_progressbar_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
151 * Get the label of a given progress bar widget
153 * @param obj The progressbar object
154 * @return The text label string, in UTF-8
156 * @ingroup Progressbar
157 * @deprecated use elm_object_text_set() instead.
159 EINA_DEPRECATED EAPI const char *elm_progressbar_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
162 * Set the icon object of a given progress bar widget
164 * @param obj The progress bar object
165 * @param icon The icon object
167 * Use this call to decorate @p obj with an icon next to it.
169 * @note Once the icon object is set, a previously set one will be
170 * deleted. If you want to keep that old content object, use the
171 * elm_progressbar_icon_unset() function.
173 * @see elm_progressbar_icon_get()
174 * @deprecated use elm_object_part_content_set() instead.
176 * @ingroup Progressbar
178 EINA_DEPRECATED EAPI void elm_progressbar_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
181 * Retrieve the icon object set for a given progress bar widget
183 * @param obj The progress bar object
184 * @return The icon object's handle, if @p obj had one set, or @c NULL,
185 * otherwise (and on errors)
187 * @see elm_progressbar_icon_set() for more details
188 * @deprecated use elm_object_part_content_get() instead.
190 * @ingroup Progressbar
192 EINA_DEPRECATED EAPI Evas_Object *elm_progressbar_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
195 * Unset an icon set on a given progress bar widget
197 * @param obj The progress bar object
198 * @return The icon object that was being used, if any was set, or
199 * @c NULL, otherwise (and on errors)
201 * This call will unparent and return the icon object which was set
202 * for this widget, previously, on success.
204 * @see elm_progressbar_icon_set() for more details
205 * @deprecated use elm_object_part_content_unset() instead.
207 * @ingroup Progressbar
209 EINA_DEPRECATED EAPI Evas_Object *elm_progressbar_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
212 * Set the (exact) length of the bar region of a given progress bar
215 * @param obj The progress bar object
216 * @param size The length of the progress bar's bar region
218 * This sets the minimum width (when in horizontal mode) or height
219 * (when in vertical mode) of the actual bar area of the progress
220 * bar @p obj. This in turn affects the object's minimum size. Use
221 * this when you're not setting other size hints expanding on the
222 * given direction (like weight and alignment hints) and you would
223 * like it to have a specific size.
225 * @note Icon, label and unit text around @p obj will require their
226 * own space, which will make @p obj to require more the @p size,
229 * @see elm_progressbar_span_size_get()
231 * @ingroup Progressbar
233 EAPI void elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size) EINA_ARG_NONNULL(1);
236 * Get the length set for the bar region of a given progress bar
239 * @param obj The progress bar object
240 * @return The length of the progress bar's bar region
242 * If that size was not set previously, with
243 * elm_progressbar_span_size_set(), this call will return @c 0.
245 * @ingroup Progressbar
247 EAPI Evas_Coord elm_progressbar_span_size_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
250 * Set the format string for a given progress bar widget's units
253 * @param obj The progress bar object
254 * @param format The format string for @p obj's units label
256 * If @c NULL is passed on @p format, it will make @p obj's units
257 * area to be hidden completely. If not, it'll set the <b>format
258 * string</b> for the units label's @b text. The units label is
259 * provided a floating point value, so the units text is up display
260 * at most one floating point falue. Note that the units label is
261 * optional. Use a format string such as "%1.2f meters" for
264 * @note The default format string for a progress bar is an integer
265 * percentage, as in @c "%.0f %%".
267 * @see elm_progressbar_unit_format_get()
269 * @ingroup Progressbar
271 EAPI void elm_progressbar_unit_format_set(Evas_Object *obj, const char *format) EINA_ARG_NONNULL(1);
274 * Retrieve the format string set for a given progress bar widget's
277 * @param obj The progress bar object
278 * @return The format set string for @p obj's units label or
279 * @c NULL, if none was set (and on errors)
281 * @see elm_progressbar_unit_format_set() for more details
283 * @ingroup Progressbar
285 EAPI const char *elm_progressbar_unit_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
288 * Set the orientation of a given progress bar widget
290 * @param obj The progress bar object
291 * @param horizontal Use @c EINA_TRUE to make @p obj to be
292 * @b horizontal, @c EINA_FALSE to make it @b vertical
294 * Use this function to change how your progress bar is to be
295 * disposed: vertically or horizontally.
297 * @see elm_progressbar_horizontal_get()
299 * @ingroup Progressbar
301 EAPI void elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
304 * Retrieve the orientation of a given progress bar widget
306 * @param obj The progress bar object
307 * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
308 * @c EINA_FALSE if it's @b vertical (and on errors)
310 * @see elm_progressbar_horizontal_set() for more details
312 * @ingroup Progressbar
314 EAPI Eina_Bool elm_progressbar_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
317 * Invert a given progress bar widget's displaying values order
319 * @param obj The progress bar object
320 * @param inverted Use @c EINA_TRUE to make @p obj inverted,
321 * @c EINA_FALSE to bring it back to default, non-inverted values.
323 * A progress bar may be @b inverted, in which state it gets its
324 * values inverted, with high values being on the left or top and
325 * low values on the right or bottom, as opposed to normally have
326 * the low values on the former and high values on the latter,
327 * respectively, for horizontal and vertical modes.
329 * @see elm_progressbar_inverted_get()
331 * @ingroup Progressbar
333 EAPI void elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted) EINA_ARG_NONNULL(1);
336 * Get whether a given progress bar widget's displaying values are
339 * @param obj The progress bar object
340 * @return @c EINA_TRUE, if @p obj has inverted values,
341 * @c EINA_FALSE otherwise (and on errors)
343 * @see elm_progressbar_inverted_set() for more details
345 * @ingroup Progressbar
347 EAPI Eina_Bool elm_progressbar_inverted_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);