mobile/src/lib/elm_progressbar.h

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