src/lib/elm_progressbar.h

   1 /**
   2  * @defgroup Progressbar Progress bar
   3  *
   4  * The progress bar is a widget for visually representing the
   5  * progress status of a given job/task.
   6  *
   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
  14  * for progress bars.
  15  *
  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.
  21  *
  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().
  29  *
  30  * Available widget styles for progress bars:
  31  * - @c "default"
  32  * - @c "wheel" (simple style, no text, no progression, only
  33  *      "pulse" effect is available)
  34  *
  35  * Default contents parts of the progressbar widget that you can use for are:
  36  * @li "icon" - An icon of the progressbar
  37  *
  38  * Here is an example on its usage:
  39  * @li @ref progressbar_example
  40  */
  41
  42 /**
  43  * Add a new progress bar widget to the given parent Elementary
  44  * (container) object
  45  *
  46  * @param parent The parent object
  47  * @return a new progress bar widget handle or @c NULL, on errors
  48  *
  49  * This function inserts a new progress bar widget on the canvas.
  50  *
  51  * @ingroup Progressbar
  52  */
  53 EAPI Evas_Object *
  54                                   elm_progressbar_add(Evas_Object *parent)
  55 EINA_ARG_NONNULL(1);
  56
  57 /**
  58  * Set whether a given progress bar widget is at "pulsing mode" or
  59  * not.
  60  *
  61  * @param obj The progress bar object
  62  * @param pulse @c EINA_TRUE to put @p obj in pulsing mode,
  63  * @c EINA_FALSE to put it back to its default one
  64  *
  65  * By default, progress bars will display values from the low to
  66  * high value boundaries. There are, though, contexts in which the
  67  * state of progression of a given task is @b unknown.  For those,
  68  * one can set a progress bar widget to a "pulsing state", to give
  69  * the user an idea that some computation is being held, but
  70  * without exact progress values. In the default theme it will
  71  * animate its bar with the contents filling in constantly and back
  72  * to non-filled, in a loop. To start and stop this pulsing
  73  * animation, one has to explicitly call elm_progressbar_pulse().
  74  *
  75  * @see elm_progressbar_pulse_get()
  76  * @see elm_progressbar_pulse()
  77  *
  78  * @ingroup Progressbar
  79  */
  80 EAPI void                         elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse) EINA_ARG_NONNULL(1);
  81
  82 /**
  83  * Get whether a given progress bar widget is at "pulsing mode" or
  84  * not.
  85  *
  86  * @param obj The progress bar object
  87  * @return @c EINA_TRUE, if @p obj is in pulsing mode, @c EINA_FALSE
  88  * if it's in the default one (and on errors)
  89  *
  90  * @ingroup Progressbar
  91  */
  92 EAPI Eina_Bool                    elm_progressbar_pulse_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  93
  94 /**
  95  * Start/stop a given progress bar "pulsing" animation, if its
  96  * under that mode
  97  *
  98  * @param obj The progress bar object
  99  * @param state @c EINA_TRUE, to @b start the pulsing animation,
 100  * @c EINA_FALSE to @b stop it
 101  *
 102  * @note This call won't do anything if @p obj is not under "pulsing mode".
 103  *
 104  * @see elm_progressbar_pulse_set() for more details.
 105  *
 106  * @ingroup Progressbar
 107  */
 108 EAPI void                         elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
 109
 110 /**
 111  * Set the progress value (in percentage) on a given progress bar
 112  * widget
 113  *
 114  * @param obj The progress bar object
 115  * @param val The progress value (@b must be between @c 0.0 and @c
 116  * 1.0)
 117  *
 118  * Use this call to set progress bar levels.
 119  *
 120  * @note If you passes a value out of the specified range for @p
 121  * val, it will be interpreted as the @b closest of the @b boundary
 122  * values in the range.
 123  *
 124  * @ingroup Progressbar
 125  */
 126 EAPI void                         elm_progressbar_value_set(Evas_Object *obj, double val) EINA_ARG_NONNULL(1);
 127
 128 /**
 129  * Get the progress value (in percentage) on a given progress bar
 130  * widget
 131  *
 132  * @param obj The progress bar object
 133  * @return The value of the progressbar
 134  *
 135  * @see elm_progressbar_value_set() for more details
 136  *
 137  * @ingroup Progressbar
 138  */
 139 EAPI double                       elm_progressbar_value_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 140
 141 /**
 142  * Set the label of a given progress bar widget
 143  *
 144  * @param obj The progress bar object
 145  * @param label The text label string, in UTF-8
 146  *
 147  * @ingroup Progressbar
 148  * @deprecated use elm_object_text_set() instead.
 149  */
 150 EINA_DEPRECATED EAPI void         elm_progressbar_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
 151
 152 /**
 153  * Get the label of a given progress bar widget
 154  *
 155  * @param obj The progressbar object
 156  * @return The text label string, in UTF-8
 157  *
 158  * @ingroup Progressbar
 159  * @deprecated use elm_object_text_set() instead.
 160  */
 161 EINA_DEPRECATED EAPI const char  *elm_progressbar_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 162
 163 /**
 164  * Set the icon object of a given progress bar widget
 165  *
 166  * @param obj The progress bar object
 167  * @param icon The icon object
 168  *
 169  * Use this call to decorate @p obj with an icon next to it.
 170  *
 171  * @note Once the icon object is set, a previously set one will be
 172  * deleted. If you want to keep that old content object, use the
 173  * elm_progressbar_icon_unset() function.
 174  *
 175  * @see elm_progressbar_icon_get()
 176  * @deprecated use elm_object_part_content_set() instead.
 177  *
 178  * @ingroup Progressbar
 179  */
 180 EINA_DEPRECATED EAPI void         elm_progressbar_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
 181
 182 /**
 183  * Retrieve the icon object set for a given progress bar widget
 184  *
 185  * @param obj The progress bar object
 186  * @return The icon object's handle, if @p obj had one set, or @c NULL,
 187  * otherwise (and on errors)
 188  *
 189  * @see elm_progressbar_icon_set() for more details
 190  * @deprecated use elm_object_part_content_get() instead.
 191  *
 192  * @ingroup Progressbar
 193  */
 194 EINA_DEPRECATED EAPI Evas_Object *elm_progressbar_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 195
 196 /**
 197  * Unset an icon set on a given progress bar widget
 198  *
 199  * @param obj The progress bar object
 200  * @return The icon object that was being used, if any was set, or
 201  * @c NULL, otherwise (and on errors)
 202  *
 203  * This call will unparent and return the icon object which was set
 204  * for this widget, previously, on success.
 205  *
 206  * @see elm_progressbar_icon_set() for more details
 207  * @deprecated use elm_object_part_content_unset() instead.
 208  *
 209  * @ingroup Progressbar
 210  */
 211 EINA_DEPRECATED EAPI Evas_Object *elm_progressbar_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 212
 213 /**
 214  * Set the (exact) length of the bar region of a given progress bar
 215  * widget
 216  *
 217  * @param obj The progress bar object
 218  * @param size The length of the progress bar's bar region
 219  *
 220  * This sets the minimum width (when in horizontal mode) or height
 221  * (when in vertical mode) of the actual bar area of the progress
 222  * bar @p obj. This in turn affects the object's minimum size. Use
 223  * this when you're not setting other size hints expanding on the
 224  * given direction (like weight and alignment hints) and you would
 225  * like it to have a specific size.
 226  *
 227  * @note Icon, label and unit text around @p obj will require their
 228  * own space, which will make @p obj to require more the @p size,
 229  * actually.
 230  *
 231  * @see elm_progressbar_span_size_get()
 232  *
 233  * @ingroup Progressbar
 234  */
 235 EAPI void                         elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size) EINA_ARG_NONNULL(1);
 236
 237 /**
 238  * Get the length set for the bar region of a given progress bar
 239  * widget
 240  *
 241  * @param obj The progress bar object
 242  * @return The length of the progress bar's bar region
 243  *
 244  * If that size was not set previously, with
 245  * elm_progressbar_span_size_set(), this call will return @c 0.
 246  *
 247  * @ingroup Progressbar
 248  */
 249 EAPI Evas_Coord                   elm_progressbar_span_size_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 250
 251 /**
 252  * Set the format string for a given progress bar widget's units
 253  * label
 254  *
 255  * @param obj The progress bar object
 256  * @param format The format string for @p obj's units label
 257  *
 258  * If @c NULL is passed on @p format, it will make @p obj's units
 259  * area to be hidden completely. If not, it'll set the <b>format
 260  * string</b> for the units label's @b text. The units label is
 261  * provided a floating point value, so the units text is up display
 262  * at most one floating point falue. Note that the units label is
 263  * optional. Use a format string such as "%1.2f meters" for
 264  * example.
 265  *
 266  * @note The default format string for a progress bar is an integer
 267  * percentage, as in @c "%.0f %%".
 268  *
 269  * @see elm_progressbar_unit_format_get()
 270  *
 271  * @ingroup Progressbar
 272  */
 273 EAPI void                         elm_progressbar_unit_format_set(Evas_Object *obj, const char *format) EINA_ARG_NONNULL(1);
 274
 275 /**
 276  * Retrieve the format string set for a given progress bar widget's
 277  * units label
 278  *
 279  * @param obj The progress bar object
 280  * @return The format set string for @p obj's units label or
 281  * @c NULL, if none was set (and on errors)
 282  *
 283  * @see elm_progressbar_unit_format_set() for more details
 284  *
 285  * @ingroup Progressbar
 286  */
 287 EAPI const char                  *elm_progressbar_unit_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 288
 289 /**
 290  * Set the orientation of a given progress bar widget
 291  *
 292  * @param obj The progress bar object
 293  * @param horizontal Use @c EINA_TRUE to make @p obj to be
 294  * @b horizontal, @c EINA_FALSE to make it @b vertical
 295  *
 296  * Use this function to change how your progress bar is to be
 297  * disposed: vertically or horizontally.
 298  *
 299  * @see elm_progressbar_horizontal_get()
 300  *
 301  * @ingroup Progressbar
 302  */
 303 EAPI void                         elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
 304
 305 /**
 306  * Retrieve the orientation of a given progress bar widget
 307  *
 308  * @param obj The progress bar object
 309  * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
 310  * @c EINA_FALSE if it's @b vertical (and on errors)
 311  *
 312  * @see elm_progressbar_horizontal_set() for more details
 313  *
 314  * @ingroup Progressbar
 315  */
 316 EAPI Eina_Bool                    elm_progressbar_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 317
 318 /**
 319  * Invert a given progress bar widget's displaying values order
 320  *
 321  * @param obj The progress bar object
 322  * @param inverted Use @c EINA_TRUE to make @p obj inverted,
 323  * @c EINA_FALSE to bring it back to default, non-inverted values.
 324  *
 325  * A progress bar may be @b inverted, in which state it gets its
 326  * values inverted, with high values being on the left or top and
 327  * low values on the right or bottom, as opposed to normally have
 328  * the low values on the former and high values on the latter,
 329  * respectively, for horizontal and vertical modes.
 330  *
 331  * @see elm_progressbar_inverted_get()
 332  *
 333  * @ingroup Progressbar
 334  */
 335 EAPI void                         elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted) EINA_ARG_NONNULL(1);
 336
 337 /**
 338  * Get whether a given progress bar widget's displaying values are
 339  * inverted or not
 340  *
 341  * @param obj The progress bar object
 342  * @return @c EINA_TRUE, if @p obj has inverted values,
 343  * @c EINA_FALSE otherwise (and on errors)
 344  *
 345  * @see elm_progressbar_inverted_set() for more details
 346  *
 347  * @ingroup Progressbar
 348  */
 349 EAPI Eina_Bool                    elm_progressbar_inverted_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 350
 351 /**
 352  * @}
 353  */