radio:preview-00.png:widget_preview_radio:60:20 \
toggle:preview-00.png:widget_preview_toggle:150:30 \
panel:preview-00.png:widget_preview_panel:150:50 \
- gengrid:preview-00.png:widget_preview_gengrid:200:160
+ gengrid:preview-00.png:widget_preview_gengrid:200:160 \
+ progressbar:preview-00.png:widget_preview_progressbar:150:50
widget-build:
@$(MAKE) -C widgets
* @ref genlist_example_01
*
* @ref genlist_example_02
+ *
+ * @ref progressbar_example
*/
/**
*
* This is how the example program's window looks like:
* @image html screenshots/gengrid_example.png
- * @image latex screenshots/gengrid_example.eps
+ * @image latex screenshots/gengrid_example.eps width=\textwidth
*
* Note that it starts with three items which we included at will:
* @dontinclude gengrid_example.c
*/
/**
+ * @page progressbar_example Progress bar widget example
+ *
+ * This application is a thorough example of the progress bar widget,
+ * consisting of a window with varios progress bars, each with a given
+ * look/style one can give to those widgets. With two auxiliary
+ * buttons, one can start or stop a timer which will fill in the bars
+ * in synchrony, simulating an underlying task being completed.
+ *
+ * We create @b seven progress bars, being three of them horizontal,
+ * three vertical and a final one under the "wheel" alternate style.
+ *
+ * For the first one, we add a progress bar on total pristine state,
+ * with no other call than the elm_progressbar_add() one:
+ * @dontinclude progressbar_example.c
+ * @skip pb with no label
+ * @until pb1
+ * See, than, that the defaults of a progress bar are:
+ * - no primary label shown,
+ * - unit label set to @c "%.0f %%",
+ * - no icon set
+ *
+ * The second progress bar is given a primary label, <c>"Infinite
+ * bounce"</c>, and, besides, it's set to @b pulse. See how, after one
+ * starts the progress timer, with the "Start" button, it animates
+ * differently than the previous one. It won't account for the
+ * progress, itself, and just dumbly animate a small bar within its
+ * bar region.
+ * @dontinclude progressbar_example.c
+ * @skip pb with label
+ * @until pb2
+ *
+ * Next, comes a progress bar with an @b icon, a primary label and a
+ * @b custom unit label set. It's also made to grow its bar in an
+ * @b inverted manner, so check that out during the timer's progression:
+ * @dontinclude progressbar_example.c
+ * @skip ic1 =
+ * @until pb3
+ * Another important thing in this one is the call to
+ * elm_progressbar_span_size_set() -- this is how we forcefully set a
+ * minimum horizontal size to our whole window! We're not resizing it
+ * manually, as you can see in the @ref progressbar_example_c
+ * "complete code".
+ *
+ * The next three progress bars are just variants on the ones already
+ * shown, but now all being @b vertical. Another time we use one of
+ * than to give the window a minimum vertical size, with
+ * elm_progressbar_span_size_set(). To demonstrate this trick once
+ * more, the fifth one, which is also set to pulse, has a smaller
+ * hardcoded span size:
+ * @dontinclude progressbar_example.c
+ * @skip vertical pb, with pulse
+ * @until pb5
+ *
+ * We end the widget demonstration by showing a progress bar with the
+ * special @b "wheel" progress bar style. One does @b not need to set
+ * it to pulse, with elm_progressbar_pulse_set(), explicitly, because
+ * its theme does not take it in account:
+ * @dontinclude progressbar_example.c
+ * @skip "wheel"
+ * @until pb7
+ *
+ * The two buttons exercising the bars, the facto, follow:
+ * @dontinclude progressbar_example.c
+ * @skip elm_button_add
+ * @until evas_object_show(bt)
+ * @until evas_object_show(bt)
+ *
+ * The first of the callbacks will, for the progress bars set to
+ * pulse, start the pulsing animation at that time. For the others, a
+ * timer callback will take care of updating the values:
+ * @dontinclude progressbar_example.c
+ * @skip static Eina_Bool
+ * @until }
+ * @until }
+ * @until }
+ *
+ * Finally, the callback to stop the progress timer will stop the
+ * pulsing on the pulsing progress bars and, for the others, to delete
+ * the timer which was acting on their values:
+ * @dontinclude progressbar_example.c
+ * @skip end of show
+ * @until }
+ * @until }
+ *
+ * This is how the example program's window looks like:
+ * @image html screenshots/progressbar_example.png
+ * @image latex screenshots/progressbar_example.eps width=\textwidth
+ *
+ * See the full @ref progressbar_example_c "source code" for
+ * this example.
+ *
+ * @example progressbar_example.c
+ */
+
+/**
* @page bg_example_01_c bg_example_01.c
* @include bg_example_01.c
* @example bg_example_01.c
* @include genlist_example_02.c
* @example genlist_example_02.c
*/
+
+/**
+ * @page progressbar_example_c Progress bar example
+ * @include progressbar_example.c
+ * @example progressbar_example.c
+ */
* @li @ref Photo
* @li @ref Photocam
* @li @ref Progressbar
+ *
+ * @image html img/widget/progressbar/preview-00.png
+ * @image latex img/widget/progressbar/preview-00.eps
* @li @ref Radio
*
* @image html img/widget/radio/preview-00.png
widget_preview_radio \
widget_preview_toggle \
widget_preview_panel \
-widget_preview_gengrid
+widget_preview_gengrid \
+widget_preview_progressbar
LDADD = $(top_builddir)/src/lib/libelementary.la @ELEMENTARY_EWEATHER_LIBS@ @ELEMENTARY_EDBUS_LIBS@ @ELEMENTARY_EFREET_LIBS@ @ELEMENTARY_LIBS@ @EIO_LIBS@ @my_libs@
widget_preview_toggle.c \
widget_preview_panel.c \
widget_preview_gengrid.c \
+ widget_preview_progressbar.c \
widget_preview_tmpl_foot.c \
widget_preview_tmpl_head.c
--- /dev/null
+#include "widget_preview_tmpl_head.c"
+
+Evas_Object *ic, *pb, *bx;
+
+bx = elm_box_add(win);
+evas_object_show(bx);
+elm_win_resize_object_add(win, bx);
+
+ic = elm_icon_add(win);
+elm_icon_standard_set(ic, "file");
+evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
+evas_object_show(ic);
+
+/* pb with label, icon, custom unit label and span size set */
+pb = elm_progressbar_add(win);
+elm_object_text_set(pb, "Label");
+elm_progressbar_span_size_set(pb, 100);
+elm_progressbar_icon_set(pb, ic);
+elm_progressbar_unit_format_set(pb, "%1.1f units");
+evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, EVAS_HINT_FILL);
+evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+evas_object_show(pb);
+elm_progressbar_value_set(pb, 0.5);
+elm_box_pack_end(bx, pb);
+
+#include "widget_preview_tmpl_foot.c"
radio_example_01.c \
panel_example_01.c \
gengrid_example.c \
- entry_example.c
+ entry_example.c \
+ progressbar_example.c
pkglib_PROGRAMS =
genlist_example_01 \
genlist_example_02 \
genlist_example_03 \
- entry_example
+ entry_example \
+ progressbar_example
# This variable will hold the list of screenshots that will be made
# by "make screenshots". Each item in the list is of the form:
toggle_example_01:toggle_example_01.png:0.0 \
panel_example_01:panel_example_01.png:0.0 \
gengrid_example:gengrid_example.png:0.0 \
- entry_example:entry_example.png:0.0
+ entry_example:entry_example.png:0.0 \
+ progressbar_example:progressbar_example.png:0.0
HTML_SS_DIR=$(top_builddir)/doc/html/screenshots
LATEX_SS_DIR=$(top_builddir)/doc/latex/screenshots
--- /dev/null
+/**
+ * Simple Elementary's <b>progress bar widget</b> example, illustrating its
+ * usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` progressbar_example.c -o progressbar_example
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+typedef struct Progressbar_Example
+{
+ Evas_Object *pb1;
+ Evas_Object *pb2; /* pulsing */
+ Evas_Object *pb3;
+ Evas_Object *pb4;
+ Evas_Object *pb5; /* pulsing */
+ Evas_Object *pb6;
+ Evas_Object *pb7; /* pulsing */
+
+ Eina_Bool run;
+ Ecore_Timer *timer;
+} Progressbar_Example;
+
+static Progressbar_Example example_data;
+
+static Eina_Bool
+_progressbar_example_value_set(void *data __UNUSED__)
+{
+ double progress;
+
+ progress = elm_progressbar_value_get(example_data.pb1);
+ if (progress < 1.0) progress += 0.0123;
+ else progress = 0.0;
+
+ /* just the non-pulsing ones need an update */
+ elm_progressbar_value_set(example_data.pb1, progress);
+ elm_progressbar_value_set(example_data.pb3, progress);
+ elm_progressbar_value_set(example_data.pb4, progress);
+ elm_progressbar_value_set(example_data.pb6, progress);
+
+ if (progress < 1.0) return ECORE_CALLBACK_RENEW;
+
+ example_data.run = 0;
+ return ECORE_CALLBACK_CANCEL;
+}
+
+static void
+_progressbar_example_start(void *data __UNUSED__,
+ Evas_Object *obj __UNUSED__,
+ void *event_info __UNUSED__)
+{
+ elm_progressbar_pulse(example_data.pb2, EINA_TRUE);
+ elm_progressbar_pulse(example_data.pb5, EINA_TRUE);
+ elm_progressbar_pulse(example_data.pb7, EINA_TRUE);
+
+ if (!example_data.run)
+ {
+ example_data.timer = ecore_timer_add(
+ 0.1, _progressbar_example_value_set, NULL);
+ example_data.run = EINA_TRUE;
+ }
+}
+
+/* end of show */
+static void
+_progressbar_example_stop(void *data __UNUSED__,
+ Evas_Object *obj __UNUSED__,
+ void *event_info __UNUSED__)
+{
+ elm_progressbar_pulse(example_data.pb2, EINA_FALSE);
+ elm_progressbar_pulse(example_data.pb5, EINA_FALSE);
+ elm_progressbar_pulse(example_data.pb7, EINA_FALSE);
+
+ if (example_data.run)
+ {
+ ecore_timer_del(example_data.timer);
+ example_data.run = EINA_FALSE;
+ }
+}
+
+static void
+_on_done(void *data __UNUSED__,
+ Evas_Object *obj __UNUSED__,
+ void *event_info __UNUSED__)
+{
+ _progressbar_example_stop(NULL, NULL, NULL);
+ elm_exit();
+}
+
+int
+elm_main(int argc __UNUSED__,
+ char **argv __UNUSED__)
+{
+ Evas_Object *win, *bg, *pb, *bx, *hbx, *bt, *bt_bx, *ic1, *ic2;
+ char buf[PATH_MAX];
+
+ win = elm_win_add(NULL, "progressbar", ELM_WIN_BASIC);
+ elm_win_title_set(win, "Progress bar example");
+ evas_object_smart_callback_add(win, "delete,request", _on_done, NULL);
+
+ bg = elm_bg_add(win);
+ elm_win_resize_object_add(win, bg);
+ evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ evas_object_show(bg);
+
+ bx = elm_box_add(win);
+ elm_win_resize_object_add(win, bx);
+ evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ evas_object_show(bx);
+
+ /* pb with no label, default unit label and no icon */
+ pb = elm_progressbar_add(win);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, 0.5);
+ elm_box_pack_end(bx, pb);
+ evas_object_show(pb);
+ example_data.pb1 = pb;
+
+ /* pb with label, and set to pulse */
+ pb = elm_progressbar_add(win);
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, 0.5);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_object_text_set(pb, "Infinite bounce");
+ elm_progressbar_pulse_set(pb, EINA_TRUE);
+ elm_box_pack_end(bx, pb);
+ evas_object_show(pb);
+ example_data.pb2 = pb;
+
+ ic1 = elm_icon_add(win);
+ snprintf(buf, sizeof(buf), "%s/images/logo_small.png", PACKAGE_DATA_DIR);
+ elm_icon_file_set(ic1, buf, NULL);
+ evas_object_size_hint_aspect_set(ic1, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
+
+ /* pb with label, icon, custom unit label and span size set */
+ pb = elm_progressbar_add(win);
+ elm_object_text_set(pb, "Label");
+ elm_progressbar_icon_set(pb, ic1);
+ elm_progressbar_inverted_set(pb, EINA_TRUE);
+ elm_progressbar_unit_format_set(pb, "%1.1f units");
+ elm_progressbar_span_size_set(pb, 200);
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, 0.5);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_box_pack_end(bx, pb);
+ evas_object_show(ic1);
+ evas_object_show(pb);
+ example_data.pb3 = pb;
+
+ hbx = elm_box_add(win);
+ elm_box_horizontal_set(hbx, EINA_TRUE);
+ evas_object_size_hint_weight_set(hbx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ evas_object_size_hint_align_set(hbx, EVAS_HINT_FILL, EVAS_HINT_FILL);
+ elm_box_pack_end(bx, hbx);
+ evas_object_show(hbx);
+
+ /* vertical pb */
+ pb = elm_progressbar_add(win);
+ elm_progressbar_horizontal_set(pb, EINA_FALSE);
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, EVAS_HINT_FILL);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_box_pack_end(hbx, pb);
+ elm_object_text_set(pb, "percent");
+ evas_object_show(pb);
+ example_data.pb4 = pb;
+
+ /* vertical pb, with pulse and custom (small) span size */
+ pb = elm_progressbar_add(win);
+ elm_progressbar_horizontal_set(pb, EINA_FALSE);
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, 0.5);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_progressbar_span_size_set(pb, 80);
+ elm_progressbar_pulse_set(pb, EINA_TRUE);
+ elm_progressbar_unit_format_set(pb, NULL);
+ elm_object_text_set(pb, "Infinite bounce");
+ elm_box_pack_end(hbx, pb);
+ evas_object_show(pb);
+ example_data.pb5 = pb;
+
+ ic2 = elm_icon_add(win);
+ elm_icon_file_set(ic2, buf, NULL);
+ evas_object_size_hint_aspect_set(ic2, EVAS_ASPECT_CONTROL_HORIZONTAL, 1, 1);
+
+ /* vertical pb, inverted, with custom unit format and icon*/
+ pb = elm_progressbar_add(win);
+ elm_progressbar_horizontal_set(pb, EINA_FALSE);
+ elm_object_text_set(pb, "Label");
+ elm_progressbar_icon_set(pb, ic2);
+ elm_progressbar_inverted_set(pb, EINA_TRUE);
+ elm_progressbar_unit_format_set(pb, "%1.2f%%");
+ elm_progressbar_span_size_set(pb, 200);
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, 0.5);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_box_pack_end(hbx, pb);
+ evas_object_show(ic2);
+ evas_object_show(pb);
+ example_data.pb6 = pb;
+
+ /* "wheel" style progress bar */
+ pb = elm_progressbar_add(win);
+ elm_object_style_set(pb, "wheel");
+ elm_object_text_set(pb, "Style: wheel");
+ evas_object_size_hint_align_set(pb, EVAS_HINT_FILL, 0.5);
+ evas_object_size_hint_weight_set(pb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_box_pack_end(bx, pb);
+ evas_object_show(pb);
+ example_data.pb7 = pb;
+
+ bt_bx = elm_box_add(win);
+ elm_box_horizontal_set(bt_bx, EINA_TRUE);
+ evas_object_size_hint_weight_set(bt_bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+ elm_box_pack_end(bx, bt_bx);
+ evas_object_show(bt_bx);
+
+ bt = elm_button_add(win);
+ elm_object_text_set(bt, "Start");
+ evas_object_smart_callback_add(bt, "clicked", _progressbar_example_start,
+ NULL);
+ elm_box_pack_end(bt_bx, bt);
+ evas_object_show(bt);
+
+ bt = elm_button_add(win);
+ elm_object_text_set(bt, "Stop");
+ evas_object_smart_callback_add(bt, "clicked", _progressbar_example_stop,
+ NULL);
+ elm_box_pack_end(bt_bx, bt);
+ evas_object_show(bt);
+
+ evas_object_show(win);
+
+ elm_run();
+ return 0;
+}
+
+ELM_MAIN()
* @}
*/
- /* progressbar */
+ /**
+ * @defgroup Progressbar Progress bar
+ *
+ * The progress bar is a widget for visually representing the
+ * progress status of a given job/task.
+ *
+ * A progress bar may be horizontal or vertical. It may display an
+ * icon besides it, as well as primary and @b units labels. The
+ * former is meant to label the widget as a whole, while the
+ * latter, which is formatted with floating point values (and thus
+ * accepts a <c>printf</c>-style format string, like <c>"%1.2f
+ * units"</c>), is meant to label the widget's <b>progress
+ * value</b>. Label, icon and unit strings/objects are @b optional
+ * for progress bars.
+ *
+ * A progress bar may be @b inverted, in which state it gets its
+ * values inverted, with high values being on the left or top and
+ * low values on the right or bottom, as opposed to normally have
+ * the low values on the former and high values on the latter,
+ * respectively, for horizontal and vertical modes.
+ *
+ * The @b span of the progress, as set by
+ * elm_progressbar_span_size_set(), is its length (horizontally or
+ * vertically), unless one puts size hints on the widget to expand
+ * on desired directions, by any container. That length will be
+ * scaled by the object or applications scaling factor. At any
+ * point code can query the progress bar for its value with
+ * elm_progressbar_value_get().
+ *
+ * Available widget styles for progress bars:
+ * - @c "default"
+ * - @c "wheel" (simple style, no text, no progression, only
+ * "pulse" effect is available)
+ *
+ * Here is an example on its usage:
+ * @li @ref progressbar_example
+ */
+
+ /**
+ * Add a new progress bar widget to the given parent Elementary
+ * (container) object
+ *
+ * @param parent The parent object
+ * @return a new progress bar widget handle or @c NULL, on errors
+ *
+ * This function inserts a new progress bar widget on the canvas.
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Object *elm_progressbar_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set whether a given progress bar widget is at "pulsing mode" or
+ * not.
+ *
+ * @param obj The progress bar object
+ * @param pulse @c EINA_TRUE to put @obj in pulsing mode,
+ * @c EINA_FALSE to put it back to its default one
+ *
+ * By default, progress bars will display values from the low to
+ * high value boundaries. There are, though, contexts in which the
+ * state of progression of a given task is @b unknown. For those,
+ * one can set a progress bar widget to a "pulsing state", to give
+ * the user an idea that some computation is being held, but
+ * without exact progress values. In the default theme it will
+ * animate its bar with the contents filling in constantly and back
+ * to non-filled, in a loop. To start and stop this pulsing
+ * animation, one has to explicitly call elm_progressbar_pulse().
+ *
+ * @see elm_progressbar_pulse_get()
+ * @see elm_progressbar_pulse()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given progress bar widget is at "pulsing mode" or
+ * not.
+ *
+ * @param obj The progress bar object
+ * @return @c EINA_TRUE, if @obj is in pulsing mode, @c EINA_FALSE
+ * if it's in the default one (and on errors)
+ *
+ * @ingroup Progressbar
+ */
EAPI Eina_Bool elm_progressbar_pulse_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Start/stop a given progress bar "pulsing" animation, if its
+ * under that mode
+ *
+ * @param obj The progress bar object
+ * @param state @c EINA_TRUE, to @b start the pulsing animation,
+ * @c EINA_FALSE to @b stop it
+ *
+ * @note This call won't do anything if @p obj is not under "pulsing mode".
+ *
+ * @see elm_progressbar_pulse_set() for more details.
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the progress value (in percentage) on a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @param val The progress value (@b must be between @c 0.0 and @c
+ * 1.0)
+ *
+ * Use this call to set progress bar levels.
+ *
+ * @note If you passes a value out of the specified range for @p
+ * val, it will be interpreted as the @b closest of the @b boundary
+ * values in the range.
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the progress value (in percentage) on a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @return The value of the progressbar
+ *
+ * @see elm_progressbar_value_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI double elm_progressbar_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the label of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @param label The text label string, in UTF-8
+ *
+ * @ingroup Progressbar
+ * @deprecated use elm_object_text_set() instead.
+ */
EINA_DEPRECATED EAPI void elm_progressbar_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the label of a given progress bar widget
+ *
+ * @param obj The progressbar object
+ * @return The text label string, in UTF-8
+ *
+ * @ingroup Progressbar
+ * @deprecated use elm_object_text_set() instead.
+ */
EINA_DEPRECATED EAPI const char *elm_progressbar_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the icon object of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @param icon The icon object
+ *
+ * Use this call to decorate @p obj with an icon next to it.
+ *
+ * @note Once the icon object is set, a previously set one will be
+ * deleted. If you want to keep that old content object, use the
+ * elm_progressbar_icon_unset() function.
+ *
+ * @see elm_progressbar_icon_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the icon object set for a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @return The icon object's handle, if @p obj had one set, or @c NULL,
+ * otherwise (and on errors)
+ *
+ * @see elm_progressbar_icon_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Object *elm_progressbar_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Unset an icon set on a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @return The icon object that was being used, if any was set, or
+ * @c NULL, otherwise (and on errors)
+ *
+ * This call will unparent and return the icon object which was set
+ * for this widget, previously, on success.
+ *
+ * @see elm_progressbar_icon_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Object *elm_progressbar_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the (exact) length of the bar region of a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @param size The length of the progress bar's bar region
+ *
+ * This sets the minimum width (when in horizontal mode) or height
+ * (when in vertical mode) of the actual bar area of the progress
+ * bar @p obj. This in turn affects the object's minimum size. Use
+ * this when you're not setting other size hints expanding on the
+ * given direction (like weight and alignment hints) and you would
+ * like it to have a specific size.
+ *
+ * @note Icon, label and unit text around @p obj will require their
+ * own space, which will make @p obj to require more the @p size,
+ * actually.
+ *
+ * @see elm_progressbar_span_size_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get the length set for the bar region of a given progress bar
+ * widget
+ *
+ * @param obj The progress bar object
+ * @return The length of the progress bar's bar region
+ *
+ * If that size was not set previously, with
+ * elm_progressbar_span_size_set(), this call will return @c 0.
+ *
+ * @ingroup Progressbar
+ */
EAPI Evas_Coord elm_progressbar_span_size_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the format string for a given progress bar widget's units
+ * label
+ *
+ * @param obj The progress bar object
+ * @param format The format string for @p obj's units label
+ *
+ * If @c NULL is passed on @p format, it will make @p obj's units
+ * area to be hidden completely. If not, it'll set the <b>format
+ * string</b> for the units label's @b text. The units label is
+ * provided a floating point value, so the units text is up display
+ * at most one floating point falue. Note that the units label is
+ * optional. Use a format string such as "%1.2f meters" for
+ * example.
+ *
+ * @note The default format string for a progress bar is an integer
+ * percentage, as in @c "%.0f %%".
+ *
+ * @see elm_progressbar_unit_format_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_unit_format_set(Evas_Object *obj, const char *format) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the format string set for a given progress bar widget's
+ * units label
+ *
+ * @param obj The progress bar object
+ * @return The format set string for @p obj's units label or
+ * @c NULL, if none was set (and on errors)
+ *
+ * @see elm_progressbar_unit_format_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI const char *elm_progressbar_unit_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+ /**
+ * Set the orientation of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @param horizontal Use @c EINA_TRUE to make @p obj to be
+ * @b horizontal, @c EINA_FALSE to make it @b vertical
+ *
+ * Use this function to change how your progress bar is to be
+ * disposed: vertically or horizontally.
+ *
+ * @see elm_progressbar_horizontal_get()
+ *
+ * @ingroup Progressbar
+ */
EAPI void elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
+
+ /**
+ * Retrieve the orientation of a given progress bar widget
+ *
+ * @param obj The progress bar object
+ * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
+ * @c EINA_FALSE if it's @b vertical (and on errors)
+ *
+ * @see elm_progressbar_horizontal_set() for more details
+ *
+ * @ingroup Progressbar
+ */
EAPI Eina_Bool elm_progressbar_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- EAPI void elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted) EINA_ARG_NONNULL(1);
- EAPI Eina_Bool elm_progressbar_inverted_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
- /* smart callbacks called:
+
+ /**
+ * Invert a given progress bar widget's displaying values order
+ *
+ * @param obj The progress bar object
+ * @param inverted Use @c EINA_TRUE to make @p obj inverted,
+ * @c EINA_FALSE to bring it back to default, non-inverted values.
+ *
+ * A progress bar may be @b inverted, in which state it gets its
+ * values inverted, with high values being on the left or top and
+ * low values on the right or bottom, as opposed to normally have
+ * the low values on the former and high values on the latter,
+ * respectively, for horizontal and vertical modes.
+ *
+ * @see elm_progressbar_inverted_get()
+ *
+ * @ingroup Progressbar
*/
- /* available item styles:
- * default
- * wheel (simple style, no text, no progression, only pulse is available)
+ EAPI void elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted) EINA_ARG_NONNULL(1);
+
+ /**
+ * Get whether a given progress bar widget's displaying values are
+ * inverted or not
+ *
+ * @param obj The progress bar object
+ * @return @c EINA_TRUE, if @p obj has inverted values,
+ * @c EINA_FALSE otherwise (and on errors)
+ *
+ * @see elm_progressbar_inverted_set() for more details
+ *
+ * @ingroup Progressbar
*/
+ EAPI Eina_Bool elm_progressbar_inverted_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* @defgroup Separator Separator
#include <Elementary.h>
#include "elm_priv.h"
-/**
- * @defgroup Progressbar Progressbar
- *
- * The progressbar adds a widget for representing current progress
- * of a job status
- *
- * A progressbar can be horizontal or vertical. It can contain an Icon and has a
- * primary label as well as a units label (that is formatted with floating
- * point values and thus accepts a printf-style format string, like
- * “%1.2f units”.
- *
- * Label, Icon and Unit strings/objects are optional.
- *
- * A progressbar may be inverted which means values invert, with high vales being
- * on the left or top and low values on the right or bottom (as opposed to
- * normally being low on the left or top and high on the bottom and right).
- *
- * The span of the progressbar is its length (horizontally or vertically).
- * This will be scaled by the object or applications scaling factor. At any point
- * code can query the progressbar for its value with elm_progressbar_value_get().
- */
-
#define MIN_RATIO_LVL 0.0
#define MAX_RATIO_LVL 1.0
return wd->label;
}
-/**
- * Add a new progressbar to the parent
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @ingroup Progressbar
- */
EAPI Evas_Object *
elm_progressbar_add(Evas_Object *parent)
{
return obj;
}
-/**
- * Normally the progressbar will display and interpret values from low to high.
- * This display a progressbar for jobs with unknow state of progression,
- * (the cursor pulse right to left and left to right, and loop) if pulse is set to 1.
- *
- * @param obj The progressbar object
- * @param pulse The pulse flag. 1 == pulse, 0 == normal
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse)
{
_theme_hook(obj);
}
-/**
- * Normally the progressbar will display and interpret values from low to high.
- * This display a progressbar for jobs with unknow state of progression,
- * (the cursor pulse right to left and left to right, and loop) if pulse is set to 1.
- *
- * @param obj The progressbar object
- * @return The pulse flag
- * (1 == pulse, 0 == normal)
- *
- * @ingroup Progressbar
- */
EAPI Eina_Bool
elm_progressbar_pulse_get(const Evas_Object *obj)
{
return wd->pulse;
}
-/**
- * Stat/Stop de pulse action
- *
- * @param obj The progressbar object
- * @param state The pulse flag. 1 == start pulse, 0 == stop pulse
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state)
{
edje_object_signal_emit(wd->progressbar, "elm,state,pulse,stop", "elm");
}
-/**
- * Set the value the progressbar indicates
- *
- * @param obj The progressbar object
- * @param val The fraction value (must be between 0.0 and 1.0)
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_value_set(Evas_Object *obj, double val)
{
_units_set(obj);
}
-
-/**
- * Get the value the progressbar has
- *
- * @param obj The progressbar object
- * @return The value of the progressbar
- *
- * @ingroup Progressbar
- */
EAPI double
elm_progressbar_value_get(const Evas_Object *obj)
{
return wd->val;
}
-/**
- * Set the label of the progressbar
- *
- * @param obj The progressbar object
- * @param label The text label string in UTF-8
- *
- * @ingroup Progressbar
- * @deprecated use elm_object_text_set() instead.
- */
EAPI void
elm_progressbar_label_set(Evas_Object *obj, const char *label)
{
_elm_progressbar_label_set(obj, NULL, label);
}
-/**
- * Get the label of the progressbar
- *
- * @param obj The progressbar object
- * @return The text label string in UTF-8
- *
- * @ingroup Progressbar
- * @deprecated use elm_object_text_set() instead.
- */
EAPI const char *
elm_progressbar_label_get(const Evas_Object *obj)
{
return _elm_progressbar_label_get(obj, NULL);
}
-/**
- * Set the icon object of the progressbar object
- *
- * Once the icon object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_progressbar_icon_unset() function.
- *
- * @param obj The progressbar object
- * @param icon The icon object
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_icon_set(Evas_Object *obj, Evas_Object *icon)
{
_sizing_eval(obj);
}
-/**
- * Get the icon object of the progressbar object
- *
- * @param obj The progressbar object
- * @return The icon object
- *
- * @ingroup Progressbar
- */
EAPI Evas_Object *
elm_progressbar_icon_get(const Evas_Object *obj)
{
return wd->icon;
}
-/**
- * Unset the icon used for the progressbar object
- *
- * Unparent and return the icon object which was set for this widget.
- *
- * @param obj The progressbar object
- * @return The icon object that was being used
- *
- * @ingroup Progressbar
- */
EAPI Evas_Object *
elm_progressbar_icon_unset(Evas_Object *obj)
{
return icon;
}
-/**
- * Set the length of the progression region of the progressbar
- *
- * This sets the minimum width or height (depending on orientation) of the
- * area of the progressbar that allows the progressbar to be dragged around. This in
- * turn affects the objects minimum size (along with icon label and unit
- * text).
- *
- * @param obj The progressbar object
- * @param size The length of the progressbar area
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size)
{
_sizing_eval(obj);
}
-/**
- * Get the length of the progression region of the progressbar
- *
- * @param obj The progressbar object
- * @return The length of the progressbar area
- *
- * @ingroup Progressbar
- */
EAPI Evas_Coord
elm_progressbar_span_size_get(const Evas_Object *obj)
{
return wd->size;
}
-/**
- * Set the format string of the unit area
- *
- * If NULL, this disabls the unit area display. If not it sets the format
- * string for the unit text. The unit text is provided a floating point
- * value, so the unit text can display up to 1 floating point falue. Note that
- * this is optional. Use a format string such as "%1.2f meters" for example.
- *
- * @param obj The progressbar object
- * @param units The format string for the units display
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_unit_format_set(Evas_Object *obj, const char *units)
{
_sizing_eval(obj);
}
-/**
- * Get the format string of the unit area
- *
- * @param obj The progressbar object
- * @return The format string for the units display
- *
- * @ingroup Progressbar
- */
EAPI const char *
elm_progressbar_unit_format_get(const Evas_Object *obj)
{
return wd->units;
}
-/**
- * Set orientation of the progressbar
- *
- * @param obj The progressbar object
- * @param horizontal If set, the progressbar will be horizontal
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal)
{
_theme_hook(obj);
}
-/**
- * Gets orientation of the progressbar
- *
- * @param obj The progressbar object
- * @return The orientation
- * (0 = vertical, 1 = horizontal)
- *
- * @ingroup Progressbar
- */
EAPI Eina_Bool
elm_progressbar_horizontal_get(const Evas_Object *obj)
{
return wd->horizontal;
}
-/**
- * Invert the progressbar display
- *
- * Normally the progressbar will display and interpret values from low to high
- * and when horizontal that is left to right. When vertical that is top
- * to bottom. This inverts this (so from right to left or bottom to top) if
- * inverted is set to 1.
- *
- * @param obj The progressbar object
- * @param inverted The inverted flag. 1 == inverted, 0 == normal
- *
- * @ingroup Progressbar
- */
EAPI void
elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted)
{
_units_set(obj);
}
-/**
- * Gets if the progressbar will displayed inverted
- *
- * @param obj The progressbar object
- * @return The inverted flag
- * (1 == inverted, 0 == normal)
- *
- * @ingroup Progressbar
- */
EAPI Eina_Bool
elm_progressbar_inverted_get(const Evas_Object *obj)
{
projects / framework / uifw / elementary.git / commitdiff