src/lib/elm_button.h

   1 /**
   2  * @defgroup Button Button
   3  *
   4  * @image html img/widget/button/preview-00.png
   5  * @image latex img/widget/button/preview-00.eps
   6  * @image html img/widget/button/preview-01.png
   7  * @image latex img/widget/button/preview-01.eps
   8  * @image html img/widget/button/preview-02.png
   9  * @image latex img/widget/button/preview-02.eps
  10  *
  11  * This is a push-button. Press it and run some function. It can contain
  12  * a simple label and icon object and it also has an autorepeat feature.
  13  *
  14  * This widget emits the following signals:
  15  * @li "clicked": the user clicked the button (press/release).
  16  * @li "repeated": the user pressed the button without releasing it.
  17  * @li "pressed": button was pressed.
  18  * @li "unpressed": button was released after being pressed.
  19  * In all cases, the @c event parameter of the callback will be
  20  * @c NULL.
  21  *
  22  * Also, defined in the default theme, the button has the following styles
  23  * available:
  24  * @li default: a normal button.
  25  * @li anchor: Like default, but the button fades away when the mouse is not
  26  * over it, leaving only the text or icon.
  27  * @li hoversel_vertical: Internally used by @ref Hoversel to give a
  28  * continuous look across its options.
  29  * @li hoversel_vertical_entry: Another internal for @ref Hoversel.
  30  *
  31  * XXX: add more styles in default theme.
  32  *
  33  * Default contents parts of the button widget that you can use for are:
  34  * @li "icon" - An icon of the button
  35  *
  36  * Default text parts of the button widget that you can use for are:
  37  * @li "default" - Label of the button
  38  *
  39  * Supported elm_object common APIs.
  40  * @li elm_object_part_text_set
  41  * @li elm_object_part_text_get
  42  * @li elm_object_part_content_set
  43  * @li elm_object_part_content_get
  44  * @li elm_object_part_content_unset
  45  * @li elm_object_signal_emit
  46  * @li elm_object_signal_callback_add
  47  * @li elm_object_signal_callback_del
  48  *
  49  * Follow through a complete example @ref button_example_01 "here".
  50  * @{
  51  */
  52
  53 /**
  54  * Add a new button to the parent's canvas
  55  *
  56  * @param parent The parent object
  57  * @return The new object or NULL if it cannot be created
  58  */
  59 EAPI Evas_Object                 *elm_button_add(Evas_Object *parent);
  60
  61 /**
  62  * Turn on/off the autorepeat event generated when the button is kept pressed
  63  *
  64  * When off, no autorepeat is performed and buttons emit a normal @c clicked
  65  * signal when they are clicked.
  66  *
  67  * When on, keeping a button pressed will continuously emit a @c repeated
  68  * signal until the button is released. The time it takes until it starts
  69  * emitting the signal is given by
  70  * elm_button_autorepeat_initial_timeout_set(), and the time between each
  71  * new emission by elm_button_autorepeat_gap_timeout_set().
  72  *
  73  * @param obj The button object
  74  * @param on  A bool to turn on/off the event
  75  */
  76 EAPI void                         elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on);
  77
  78 /**
  79  * Get whether the autorepeat feature is enabled
  80  *
  81  * @param obj The button object
  82  * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
  83  *
  84  * @see elm_button_autorepeat_set()
  85  */
  86 EAPI Eina_Bool                    elm_button_autorepeat_get(const Evas_Object *obj);
  87
  88 /**
  89  * Set the initial timeout before the autorepeat event is generated
  90  *
  91  * Sets the timeout, in seconds, since the button is pressed until the
  92  * first @c repeated signal is emitted. If @p t is 0.0 or less, there
  93  * won't be any delay and the event will be fired the moment the button is
  94  * pressed.
  95  *
  96  * @param obj The button object
  97  * @param t   Timeout in seconds
  98  *
  99  * @see elm_button_autorepeat_set()
 100  * @see elm_button_autorepeat_gap_timeout_set()
 101  */
 102 EAPI void                         elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t);
 103
 104 /**
 105  * Get the initial timeout before the autorepeat event is generated
 106  *
 107  * @param obj The button object
 108  * @return Timeout in seconds
 109  *
 110  * @see elm_button_autorepeat_initial_timeout_set()
 111  */
 112 EAPI double                       elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj);
 113
 114 /**
 115  * Set the interval between each generated autorepeat event
 116  *
 117  * After the first @c repeated event is fired, all subsequent ones will
 118  * follow after a delay of @p t seconds for each.
 119  *
 120  * @param obj The button object
 121  * @param t   Interval in seconds
 122  *
 123  * @see elm_button_autorepeat_initial_timeout_set()
 124  */
 125 EAPI void                         elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t);
 126
 127 /**
 128  * Get the interval between each generated autorepeat event
 129  *
 130  * @param obj The button object
 131  * @return Interval in seconds
 132  */
 133 EAPI double                       elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj);
 134
 135 /**
 136  * @}
 137  */