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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
 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) EINA_ARG_NONNULL(1);
 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) EINA_ARG_NONNULL(1);
 138
 139    /**
 140     * Set the label of a given progress bar widget
 141     *
 142     * @param obj The progress bar object
 143     * @param label The text label string, in UTF-8
 144     *
 145     * @ingroup Progressbar
 146     * @deprecated use elm_object_text_set() instead.
 147     */
 148    EINA_DEPRECATED EAPI void         elm_progressbar_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
 149
 150    /**
 151     * Get the label of a given progress bar widget
 152     *
 153     * @param obj The progressbar object
 154     * @return The text label string, in UTF-8
 155     *
 156     * @ingroup Progressbar
 157     * @deprecated use elm_object_text_set() instead.
 158     */
 159    EINA_DEPRECATED EAPI const char  *elm_progressbar_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 160
 161    /**
 162     * Set the icon object of a given progress bar widget
 163     *
 164     * @param obj The progress bar object
 165     * @param icon The icon object
 166     *
 167     * Use this call to decorate @p obj with an icon next to it.
 168     *
 169     * @note Once the icon object is set, a previously set one will be
 170     * deleted. If you want to keep that old content object, use the
 171     * elm_progressbar_icon_unset() function.
 172     *
 173     * @see elm_progressbar_icon_get()
 174     * @deprecated use elm_object_part_content_set() instead.
 175     *
 176     * @ingroup Progressbar
 177     */
 178    EINA_DEPRECATED EAPI void         elm_progressbar_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
 179
 180    /**
 181     * Retrieve the icon object set for a given progress bar widget
 182     *
 183     * @param obj The progress bar object
 184     * @return The icon object's handle, if @p obj had one set, or @c NULL,
 185     * otherwise (and on errors)
 186     *
 187     * @see elm_progressbar_icon_set() for more details
 188     * @deprecated use elm_object_part_content_get() instead.
 189     *
 190     * @ingroup Progressbar
 191     */
 192    EINA_DEPRECATED EAPI Evas_Object *elm_progressbar_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 193
 194    /**
 195     * Unset an icon set on a given progress bar widget
 196     *
 197     * @param obj The progress bar object
 198     * @return The icon object that was being used, if any was set, or
 199     * @c NULL, otherwise (and on errors)
 200     *
 201     * This call will unparent and return the icon object which was set
 202     * for this widget, previously, on success.
 203     *
 204     * @see elm_progressbar_icon_set() for more details
 205     * @deprecated use elm_object_part_content_unset() instead.
 206     *
 207     * @ingroup Progressbar
 208     */
 209    EINA_DEPRECATED EAPI Evas_Object *elm_progressbar_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 210
 211    /**
 212     * Set the (exact) length of the bar region of a given progress bar
 213     * widget
 214     *
 215     * @param obj The progress bar object
 216     * @param size The length of the progress bar's bar region
 217     *
 218     * This sets the minimum width (when in horizontal mode) or height
 219     * (when in vertical mode) of the actual bar area of the progress
 220     * bar @p obj. This in turn affects the object's minimum size. Use
 221     * this when you're not setting other size hints expanding on the
 222     * given direction (like weight and alignment hints) and you would
 223     * like it to have a specific size.
 224     *
 225     * @note Icon, label and unit text around @p obj will require their
 226     * own space, which will make @p obj to require more the @p size,
 227     * actually.
 228     *
 229     * @see elm_progressbar_span_size_get()
 230     *
 231     * @ingroup Progressbar
 232     */
 233    EAPI void         elm_progressbar_span_size_set(Evas_Object *obj, Evas_Coord size) EINA_ARG_NONNULL(1);
 234
 235    /**
 236     * Get the length set for the bar region of a given progress bar
 237     * widget
 238     *
 239     * @param obj The progress bar object
 240     * @return The length of the progress bar's bar region
 241     *
 242     * If that size was not set previously, with
 243     * elm_progressbar_span_size_set(), this call will return @c 0.
 244     *
 245     * @ingroup Progressbar
 246     */
 247    EAPI Evas_Coord   elm_progressbar_span_size_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 248
 249    /**
 250     * Set the format string for a given progress bar widget's units
 251     * label
 252     *
 253     * @param obj The progress bar object
 254     * @param format The format string for @p obj's units label
 255     *
 256     * If @c NULL is passed on @p format, it will make @p obj's units
 257     * area to be hidden completely. If not, it'll set the <b>format
 258     * string</b> for the units label's @b text. The units label is
 259     * provided a floating point value, so the units text is up display
 260     * at most one floating point falue. Note that the units label is
 261     * optional. Use a format string such as "%1.2f meters" for
 262     * example.
 263     *
 264     * @note The default format string for a progress bar is an integer
 265     * percentage, as in @c "%.0f %%".
 266     *
 267     * @see elm_progressbar_unit_format_get()
 268     *
 269     * @ingroup Progressbar
 270     */
 271    EAPI void         elm_progressbar_unit_format_set(Evas_Object *obj, const char *format) EINA_ARG_NONNULL(1);
 272
 273    /**
 274     * Retrieve the format string set for a given progress bar widget's
 275     * units label
 276     *
 277     * @param obj The progress bar object
 278     * @return The format set string for @p obj's units label or
 279     * @c NULL, if none was set (and on errors)
 280     *
 281     * @see elm_progressbar_unit_format_set() for more details
 282     *
 283     * @ingroup Progressbar
 284     */
 285    EAPI const char  *elm_progressbar_unit_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 286
 287    /**
 288     * Set the orientation of a given progress bar widget
 289     *
 290     * @param obj The progress bar object
 291     * @param horizontal Use @c EINA_TRUE to make @p obj to be
 292     * @b horizontal, @c EINA_FALSE to make it @b vertical
 293     *
 294     * Use this function to change how your progress bar is to be
 295     * disposed: vertically or horizontally.
 296     *
 297     * @see elm_progressbar_horizontal_get()
 298     *
 299     * @ingroup Progressbar
 300     */
 301    EAPI void         elm_progressbar_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
 302
 303    /**
 304     * Retrieve the orientation of a given progress bar widget
 305     *
 306     * @param obj The progress bar object
 307     * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
 308     * @c EINA_FALSE if it's @b vertical (and on errors)
 309     *
 310     * @see elm_progressbar_horizontal_set() for more details
 311     *
 312     * @ingroup Progressbar
 313     */
 314    EAPI Eina_Bool    elm_progressbar_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 315
 316    /**
 317     * Invert a given progress bar widget's displaying values order
 318     *
 319     * @param obj The progress bar object
 320     * @param inverted Use @c EINA_TRUE to make @p obj inverted,
 321     * @c EINA_FALSE to bring it back to default, non-inverted values.
 322     *
 323     * A progress bar may be @b inverted, in which state it gets its
 324     * values inverted, with high values being on the left or top and
 325     * low values on the right or bottom, as opposed to normally have
 326     * the low values on the former and high values on the latter,
 327     * respectively, for horizontal and vertical modes.
 328     *
 329     * @see elm_progressbar_inverted_get()
 330     *
 331     * @ingroup Progressbar
 332     */
 333    EAPI void         elm_progressbar_inverted_set(Evas_Object *obj, Eina_Bool inverted) EINA_ARG_NONNULL(1);
 334
 335    /**
 336     * Get whether a given progress bar widget's displaying values are
 337     * inverted or not
 338     *
 339     * @param obj The progress bar object
 340     * @return @c EINA_TRUE, if @p obj has inverted values,
 341     * @c EINA_FALSE otherwise (and on errors)
 342     *
 343     * @see elm_progressbar_inverted_set() for more details
 344     *
 345     * @ingroup Progressbar
 346     */
 347    EAPI Eina_Bool    elm_progressbar_inverted_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 348
 349    /**
 350     * @}
 351     */