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