diff options
Diffstat (limited to 'src/lib/elm_spinner.h')
| -rw-r--r-- | src/lib/elm_spinner.h | 446 |
1 files changed, 417 insertions, 29 deletions
diff --git a/src/lib/elm_spinner.h b/src/lib/elm_spinner.h index a6ced26c5..59ab385f1 100644 --- a/src/lib/elm_spinner.h +++ b/src/lib/elm_spinner.h @@ -1,19 +1,16 @@ /** * @defgroup Spinner Spinner - * @ingroup Elementary + * @ingroup elm_widget_group * * @image html spinner_inheritance_tree.png * @image latex spinner_inheritance_tree.eps * - * @image html img/widget/spinner/preview-00.png - * @image latex img/widget/spinner/preview-00.eps + * @brief A spinner is a widget which allows the user to increase or decrease + * numeric values using arrow buttons, or edit values directly by + * clicking over it and typing the new value. * - * A spinner is a widget which allows the user to increase or decrease - * numeric values using arrow buttons, or edit values directly, clicking - * over it and typing the new value. - * - * By default the spinner will not wrap and has a label - * of "%.0f" (just showing the integer value of the double). + * By default, the spinner does not wrap and has a label + * of "%.0f" (just showing the integer value of double). * * A spinner has a label that is formatted with floating * point values and thus accepts a printf-style format string, like @@ -25,44 +22,435 @@ * functions acting on it also work for spinner objects. * * This widget emits the following signals, besides the ones sent from - * @ref Layout: + * @ref Layout : * - @c "changed" - Whenever the spinner value is changed. * - @c "delay,changed" - A short time after the value is changed by - * the user. This will be called only when the user stops dragging + * the user. This is called only when the user stops dragging * for a very short period or when they release their finger/mouse, - * so it avoids possibly expensive reactions to the value change. - * - @c "language,changed" - the program's language changed - * - @c "focused" - When the spinner has received focus. (since 1.8) - * - @c "unfocused" - When the spinner has lost focus. (since 1.8) - * - @c "spinner,drag,start" - When dragging has started. (since 1.8) - * - @c "spinner,drag,stop" - When dragging has stopped. (since 1.8) + * so it avoids the possible expensive reactions to the value change. + * - @c "language,changed" - The program's language is changed. * * Available styles for it: * - @c "default"; - * - @c "vertical": up/down buttons at the right side and text left aligned. + * - @c "vertical": Up/down buttons on the right side and text aligned to the left. * - * Supported elm_object common APIs. + * Supported common elm_object APIs. * @li @ref elm_object_signal_emit * @li @ref elm_object_signal_callback_add * @li @ref elm_object_signal_callback_del * @li @ref elm_object_disabled_set * @li @ref elm_object_disabled_get * - * Here is an example on its usage: - * @ref spinner_example + * @{ */ /** - * @addtogroup Spinner - * @{ + * @brief Adds a new spinner widget to the given parent Elementary + * (container) object. + * + * @details This function inserts a new spinner widget on the canvas. + * + * @since_tizen 2.3 + * + * @param[in] parent The parent object + * @return A new spinner widget handle, otherwise @c NULL in case of an error + * + */ +EAPI Evas_Object *elm_spinner_add(Evas_Object *parent); + +/** + * @brief Sets the format string of the displayed label. + * + * @since_tizen 2.3 + * + * @remarks If @c NULL, this sets the format to "%.0f". If not, it sets the format + * string for the label text. For label text a floating point value is provided, + * so the label text can display up to @c 1 floating point value. + * Note that this is optional. + * + * @remarks Use a format string such as "%1.2f meters" for example, and it + * displays values like: "3.14 meters" for a value equal to 3.14159. + * + * @remarks Default is "%0.f". + * + * @param[in] obj The spinner object + * @param[in] fmt The format string for the label display + * + * @see elm_spinner_label_format_get() + */ +EAPI void elm_spinner_label_format_set(Evas_Object *obj, const char *fmt); + +/** + * @brief Gets the label format of the spinner. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return The text label format string in UTF-8 + * + * @see elm_spinner_label_format_set() */ +EAPI const char *elm_spinner_label_format_get(const Evas_Object *obj); -#ifdef EFL_EO_API_SUPPORT -#include "elm_spinner_eo.h" -#endif -#ifndef EFL_NOLEGACY_API_SUPPORT -#include "elm_spinner_legacy.h" -#endif +/** + * @brief Sets the minimum and maximum values for the spinner. + * + * @details This defines the allowed range of values to be selected by the user. + * + * @since_tizen 2.3 + * + * @remarks If the actual value is less than @a min, it is updated to @a min. If it + * is bigger then @a max, it is updated to @a max. Actual value can be + * obtained with elm_spinner_value_get(). + * + * @remarks By default, @a min is equal to @c 0, and @a max is equal to @c 100. + * + * @remarks Maximum must be greater than minimum. + * + * @param[in] obj The spinner object + * @param[in] min The minimum value + * @param[in] max The maximum value + * + * @see elm_spinner_min_max_get() + */ +EAPI void elm_spinner_min_max_set(Evas_Object *obj, double min, double max); + +/** + * @brief Gets the minimum and maximum values of the spinner. + * + * @since_tizen 2.3 + * + * @remarks If only one value is needed, the other pointer can be passed + * as @c NULL. + * + * @param[in] obj The spinner object + * @param[out] min The pointer to store the minimum value + * @param[out] max The pointer to store the maximum value + * + * @see elm_spinner_min_max_set() + */ +EAPI void elm_spinner_min_max_get(const Evas_Object *obj, double *min, double *max); + +/** + * @brief Sets the step used to increment or decrement the spinner value. + * + * @since_tizen 2.3 + * + * @remarks This value is incremented or decremented to the displayed value. + * It is incremented while the user keeps the right or top arrow pressed, + * and is decremented while the user keeps the left or bottom arrow pressed. + * + * @remarks The interval to increment / decrement can be set using + * elm_spinner_interval_set(). + * + * @remarks By default the step value is equal to @c 1. + * + * @param[in] obj The spinner object + * @param[in] step The step value + * + * @see elm_spinner_step_get() + */ +EAPI void elm_spinner_step_set(Evas_Object *obj, double step); + +/** + * @brief Gets the step used to increment or decrement the spinner value. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return The step value + * + * @see elm_spinner_step_get() + */ +EAPI double elm_spinner_step_get(const Evas_Object *obj); + +/** + * @brief Sets the value that the spinner displays. + * + * @since_tizen 2.3 + * + * @remarks The value is presented on the label following the format specified by + * elm_spinner_format_set(). + * + * @remarks The value must to be between the @a min and @a max values. These values + * are set by elm_spinner_min_max_set(). + * + * @param[in] obj The spinner object + * @param[in] val The value to be displayed + * + * @see elm_spinner_value_get() + * @see elm_spinner_format_set() + * @see elm_spinner_min_max_set() + */ +EAPI void elm_spinner_value_set(Evas_Object *obj, double val); + +/** + * @brief Gets the value displayed by the spinner. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return The value displayed + * + * @see elm_spinner_value_set() + */ +EAPI double elm_spinner_value_get(const Evas_Object *obj); + +/** + * @brief Sets whether the spinner should wrap when it reaches its + * minimum or maximum value. + * + * @since_tizen 2.3 + * + * @remarks It is disabled by default. If disabled when the user tries to increment the + * value, but the displayed value plus the step value is bigger than the maximum value, + * the new value is the maximum value. + * The same happens when the user tries to decrement it, + * but the value less than step is less than the minimum value. In this case, + * the new displayed value is the minimum value. + * + * @remarks If wrap is enabled when the user tries to increment the value, + * but the displayed value plus the step value is bigger than the maximum value, + * the new value is the minimum value. When the the user tries to + * decrement it, but the value less step is less than the minimum value, + * the new displayed value is the maximum value. + * + * E.g.: + * @li min value = 10 + * @li max value = 50 + * @li step value = 20 + * @li displayed value = 20 + * + * When the user decrements the value (using left or bottom arrow), it + * displays @c 50. + * + * @param[in] obj The spinner object + * @param[in] wrap If @c EINA_TRUE wrap is enabled, otherwise @c EINA_FALSE to + * disable it + * + * @see elm_spinner_wrap_get() + */ +EAPI void elm_spinner_wrap_set(Evas_Object *obj, Eina_Bool wrap); + +/** + * @brief Gets whether the spinner should wrap when it reaches its + * minimum or maximum value. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return @c EINA_TRUE indicates that wrap is enabled, otherwise @c EINA_FALSE indicates that it's disabled \n + * If @a obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_spinner_wrap_set() + */ +EAPI Eina_Bool elm_spinner_wrap_get(const Evas_Object *obj); + +/** + * @brief Sets whether the spinner can be directly edited by the user. + * + * @since_tizen 2.3 + * + * @remarks Spinner objects can have an edition @b disabled, in which case they can + * be changed only by arrows. + * Useful for contexts + * where you don't want your users to interact by writing the value. + * Specially when using special values, the user can see real values instead + * of special labels on the edition. + * + * @remarks It's enabled by default. + * + * @param[in] obj The spinner object + * @param[in] editable If @c EINA_TRUE allow users to edit it, otherwise @c EINA_FALSE to + * not allow users to edit it directly + * + * @see elm_spinner_editable_get() + */ +EAPI void elm_spinner_editable_set(Evas_Object *obj, Eina_Bool editable); + +/** + * @brief Gets whether the spinner can be directly edited by the user. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return @c EINA_TRUE indicates that the edition is enabled, otherwise @c EINA_FALSE indicates that it's disabled \n + * If @a obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_spinner_editable_set() + */ +EAPI Eina_Bool elm_spinner_editable_get(const Evas_Object *obj); + +/** + * @brief Sets a special string to display in place of the numerical value. + * + * @since_tizen 2.3 + * + * @remarks It's useful for cases when a user should select an item that is + * better indicated by a label than a value. For example, weekdays or months. + * + * E.g.: + * @code + * sp = elm_spinner_add(win); + * elm_spinner_min_max_set(sp, 1, 3); + * elm_spinner_special_value_add(sp, 1, "January"); + * elm_spinner_special_value_add(sp, 2, "February"); + * elm_spinner_special_value_add(sp, 3, "March"); + * evas_object_show(sp); + * @endcode + * + * @remarks If another label was previously set to @a value, it is replaced + * by the new label. + * + * @param[in] obj The spinner object + * @param[in] value The value to be replaced + * @param[in] label The label to be used + * + * @see elm_spinner_special_value_get() + * @see elm_spinner_special_value_del() + */ +EAPI void elm_spinner_special_value_add(Evas_Object *obj, double value, const char *label); + +/** + * @brief Deletes the special string displayed in place of the numerical value. + * + * @since 1.8 + * + * @since_tizen 2.3 + * + * @remarks It removes a previously added special value. After this, the spinner + * displays the value itself instead of a label. + * + * @param[in] obj The spinner object + * @param[in] value The replaced value + * + * @see elm_spinner_special_value_add() + */ +EAPI void elm_spinner_special_value_del(Evas_Object *obj, double value); + +/** + * @brief Gets the special string displayed in place of the numerical value. + * + * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @param[in] value The replaced value + * @return The used label + * + * @see elm_spinner_special_value_add() + */ +EAPI const char *elm_spinner_special_value_get(Evas_Object *obj, double value); + +/** + * @brief Sets the interval on the time updates for a user's mouse button hold + * on the spinner widgets' arrows. + * + * @since_tizen 2.3 + * + * @remarks This interval value is @b decreased while the user holds the + * mouse pointer either by incrementing or decrementing the spinner's value. + * + * @remarks This helps the user to get to a given value, which is distant from the + * current one, in an easier/faster way, as it updates the value in that set interval time + * on mouse button holds. + * + * @remarks The default starting interval value for automatic changes is + * @c 0.85 seconds. + * + * @param[in] obj The spinner object + * @param[in] interval The interval value in seconds + * + * @see elm_spinner_interval_get() + */ +EAPI void elm_spinner_interval_set(Evas_Object *obj, double interval); + +/** + * @brief Gets the interval on the time updates for a user's mouse button hold + * on the spinner widgets' arrows. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return The interval value, in seconds, set on it + * + * @see elm_spinner_interval_set() + */ +EAPI double elm_spinner_interval_get(const Evas_Object *obj); + +/** + * @brief Sets the base for rounding. + * + * @since_tizen 2.3 + * + * @remarks Rounding works as follows: + * + * rounded_val = base + (double)(((value - base) / round) * round) + * + * Where rounded_val, value, and base are doubles, and round is an integer. + * + * This means that things are rounded to increments (or decrements) of + * "round" starting from the value @a base. The default base for rounding is @c 0. + * + * Example: round = 3, base = 2 + * Values: 3, 6, 9, 12, 15, ... + * + * Example: round = 2, base = 5.5 + * Values: 5.5, 7.5, 9.5, 11.5, ... + * + * @param[in] obj The spinner object + * @param[in] base The base value + * + * @see elm_spinner_round_get() + * @see elm_spinner_base_get() + */ +EAPI void elm_spinner_base_set(Evas_Object *obj, double base); + +/** + * @brief Gets the base for rounding. + * + * @since_tizen 2.3 + * + * @remarks This returns the base for rounding + * + * @param[in] obj The spinner object + * @return The base rounding value + * + * @see elm_spinner_round_set() + * @see elm_spinner_base_set() + */ +EAPI double elm_spinner_base_get(const Evas_Object *obj); + +/** + * @brief Sets the round value for rounding. + * + * @details This sets the rounding value used for the value rounding in the spinner. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @param[in] rnd The rounding value + * + * @see elm_spinner_round_get() + * @see elm_spinner_base_set() + */ +EAPI void elm_spinner_round_set(Evas_Object *obj, int rnd); + +/** + * @brief Gets the round value for rounding. + * + * @details This returns the round value for rounding. + * + * @since_tizen 2.3 + * + * @param[in] obj The spinner object + * @return The rounding value + * + * @see elm_spinner_round_set() + * @see elm_spinner_base_set() + */ +EAPI int elm_spinner_round_get(const Evas_Object *obj); /** * @} */ |