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                 *elm_progressbar_add(Evas_Object *parent);
  54
  55 /**
  56  * Set whether a given progress bar widget is at "pulsing mode" or
  57  * not.
  58  *
  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
  62  *
  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().
  72  *
  73  * @see elm_progressbar_pulse_get()
  74  * @see elm_progressbar_pulse()
  75  *
  76  * @ingroup Progressbar
  77  */
  78 EAPI void                         elm_progressbar_pulse_set(Evas_Object *obj, Eina_Bool pulse);
  79
  80 /**
  81  * Get whether a given progress bar widget is at "pulsing mode" or
  82  * not.
  83  *
  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)
  87  *
  88  * @ingroup Progressbar
  89  */
  90 EAPI Eina_Bool                    elm_progressbar_pulse_get(const Evas_Object *obj);
  91
  92 /**
  93  * Start/stop a given progress bar "pulsing" animation, if its
  94  * under that mode
  95  *
  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
  99  *
 100  * @note This call won't do anything if @p obj is not under "pulsing mode".
 101  *
 102  * @see elm_progressbar_pulse_set() for more details.
 103  *
 104  * @ingroup Progressbar
 105  */
 106 EAPI void                         elm_progressbar_pulse(Evas_Object *obj, Eina_Bool state);
 107
 108 /**
 109  * Set the progress value (in percentage) on a given progress bar
 110  * widget
 111  *
 112  * @param obj The progress bar object
 113  * @param val The progress value (@b must be between @c 0.0 and @c
 114  * 1.0)
 115  *
 116  * Use this call to set progress bar levels.
 117  *
 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.
 121  *
 122  * @ingroup Progressbar
 123  */
 124 EAPI void                         elm_progressbar_value_set(Evas_Object *obj, double val);
 125
 126 /**
 127  * Get the progress value (in percentage) on a given progress bar
 128  * widget
 129  *
 130  * @param obj The progress bar object
 131  * @return The value of the progressbar
 132  *
 133  * @see elm_progressbar_value_set() for more details
 134  *
 135  * @ingroup Progressbar
 136  */
 137 EAPI double                       elm_progressbar_value_get(const Evas_Object *obj);
 138
 139 /**
 140  * Set the (exact) length of the bar region of a given progress bar
 141  * widget
 142  *
 143  * @param obj The progress bar object
 144  * @param size The length of the progress bar's bar region
 145  *
 146  * This sets the minimum width (when in horizontal mode) or height
 147  * (when in vertical mode) of the actual bar area of the progress
 148  * bar @p obj. This in turn affects the object's minimum size. Use
 149  * this when you're not setting other size hints expanding on the
 150  * given direction (like weight and alignment hints) and you would
 151  * like it to have a specific size.
 152  *
 153  * @note Icon, label and unit text around @p obj will require their
 154  * own space, which will make @p obj to require more the @p size,
 155  * actually.
 156  *
 157  * @see elm_progressbar_span_size_get()
 158  *
 159  * @ingroup Progressbar
 160  */
 161 EAPI void                         elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size);
 162
 163 /**
 164  * Get the length set for the bar region of a given progress bar
 165  * widget
 166  *
 167  * @param obj The progress bar object
 168  * @return The length of the progress bar's bar region
 169  *
 170  * If that size was not set previously, with
 171  * elm_progressbar_span_size_set(), this call will return @c 0.
 172  *
 173  * @ingroup Progressbar
 174  */
 175 EAPI Evas_Coord                   elm_progressbar_span_size_get(const Evas_Object *obj);
 176
 177 /**
 178  * Set the format string for a given progress bar widget's units
 179  * label
 180  *
 181  * @param obj The progress bar object
 182  * @param format The format string for @p obj's units label
 183  *
 184  * If @c NULL is passed on @p format, it will make @p obj's units
 185  * area to be hidden completely. If not, it'll set the <b>format
 186  * string</b> for the units label's @b text. The units label is
 187  * provided a floating point value, so the units text is up display
 188  * at most one floating point falue. Note that the units label is
 189  * optional. Use a format string such as "%1.2f meters" for
 190  * example.
 191  *
 192  * @note The default format string for a progress bar is an integer
 193  * percentage, as in @c "%.0f %%".
 194  *
 195  * @see elm_progressbar_unit_format_get()
 196  *
 197  * @ingroup Progressbar
 198  */
 199 EAPI void                         elm_progressbar_unit_format_set(Evas_Object *obj, const char *format);
 200
 201 /**
 202  * Retrieve the format string set for a given progress bar widget's
 203  * units label
 204  *
 205  * @param obj The progress bar object
 206  * @return The format set string for @p obj's units label or
 207  * @c NULL, if none was set (and on errors)
 208  *
 209  * @see elm_progressbar_unit_format_set() for more details
 210  *
 211  * @ingroup Progressbar
 212  */
 213 EAPI const char                  *elm_progressbar_unit_format_get(const Evas_Object *obj);
 214
 215 /**
 216  * Set the orientation of a given progress bar widget
 217  *
 218  * @param obj The progress bar object
 219  * @param horizontal Use @c EINA_TRUE to make @p obj to be
 220  * @b horizontal, @c EINA_FALSE to make it @b vertical
 221  *
 222  * Use this function to change how your progress bar is to be
 223  * disposed: vertically or horizontally.
 224  *
 225  * @see elm_progressbar_horizontal_get()
 226  *
 227  * @ingroup Progressbar
 228  */
 229 EAPI void                         elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 230
 231 /**
 232  * Retrieve the orientation of a given progress bar widget
 233  *
 234  * @param obj The progress bar object
 235  * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
 236  * @c EINA_FALSE if it's @b vertical (and on errors)
 237  *
 238  * @see elm_progressbar_horizontal_set() for more details
 239  *
 240  * @ingroup Progressbar
 241  */
 242 EAPI Eina_Bool                    elm_progressbar_horizontal_get(const Evas_Object *obj);
 243
 244 /**
 245  * Invert a given progress bar widget's displaying values order
 246  *
 247  * @param obj The progress bar object
 248  * @param inverted Use @c EINA_TRUE to make @p obj inverted,
 249  * @c EINA_FALSE to bring it back to default, non-inverted values.
 250  *
 251  * A progress bar may be @b inverted, in which state it gets its
 252  * values inverted, with high values being on the left or top and
 253  * low values on the right or bottom, as opposed to normally have
 254  * the low values on the former and high values on the latter,
 255  * respectively, for horizontal and vertical modes.
 256  *
 257  * @see elm_progressbar_inverted_get()
 258  *
 259  * @ingroup Progressbar
 260  */
 261 EAPI void                         elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted);
 262
 263 /**
 264  * Get whether a given progress bar widget's displaying values are
 265  * inverted or not
 266  *
 267  * @param obj The progress bar object
 268  * @return @c EINA_TRUE, if @p obj has inverted values,
 269  * @c EINA_FALSE otherwise (and on errors)
 270  *
 271  * @see elm_progressbar_inverted_set() for more details
 272  *
 273  * @ingroup Progressbar
 274  */
 275 EAPI Eina_Bool                    elm_progressbar_inverted_get(const Evas_Object *obj);
 276
 277 /**
 278  * @}
 279  */