src/lib/elm_progressbar.h

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