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