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  * @li naviframe: Internally used by @ref Naviframe for its back button.
  31  * @li colorselector: Internally used by @ref Colorselector
  32  * for its left and right buttons.
  33  *
  34  * Default content parts of the button widget that you can use for are:
  35  * @li "icon" - An icon of the button
  36  *
  37  * Default text parts of the button widget that you can use for are:
  38  * @li "default" - Label of the button
  39  *
  40  * Supported elm_object common APIs.
  41  * @li elm_object_part_text_set
  42  * @li elm_object_part_text_get
  43  * @li elm_object_part_content_set
  44  * @li elm_object_part_content_get
  45  * @li elm_object_part_content_unset
  46  * @li elm_object_signal_emit
  47  * @li elm_object_signal_callback_add
  48  * @li elm_object_signal_callback_del
  49  *
  50  * Follow through a complete example @ref button_example_01 "here".
  51  * @{
  52  */
  53
  54 /**
  55  * Add a new button to the parent's canvas
  56  *
  57  * @param parent The parent object
  58  * @return The new object or NULL if it cannot be created
  59  */
  60 EAPI Evas_Object                 *elm_button_add(Evas_Object *parent);
  61
  62 /**
  63  * Turn on/off the autorepeat event generated when the button is kept pressed
  64  *
  65  * When off, no autorepeat is performed and buttons emit a normal @c clicked
  66  * signal when they are clicked.
  67  *
  68  * When on, keeping a button pressed will continuously emit a @c repeated
  69  * signal until the button is released. The time it takes until it starts
  70  * emitting the signal is given by
  71  * elm_button_autorepeat_initial_timeout_set(), and the time between each
  72  * new emission by elm_button_autorepeat_gap_timeout_set().
  73  *
  74  * @param obj The button object
  75  * @param on  A bool to turn on/off the event
  76  */
  77 EAPI void                         elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on);
  78
  79 /**
  80  * Get whether the autorepeat feature is enabled
  81  *
  82  * @param obj The button object
  83  * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
  84  *
  85  * @see elm_button_autorepeat_set()
  86  */
  87 EAPI Eina_Bool                    elm_button_autorepeat_get(const Evas_Object *obj);
  88
  89 /**
  90  * Set the initial timeout before the autorepeat event is generated
  91  *
  92  * Sets the timeout, in seconds, since the button is pressed until the
  93  * first @c repeated signal is emitted. If @p t is 0.0 or less, there
  94  * won't be any delay and the event will be fired the moment the button is
  95  * pressed.
  96  *
  97  * @param obj The button object
  98  * @param t   Timeout in seconds
  99  *
 100  * @see elm_button_autorepeat_set()
 101  * @see elm_button_autorepeat_gap_timeout_set()
 102  */
 103 EAPI void                         elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t);
 104
 105 /**
 106  * Get the initial timeout before the autorepeat event is generated
 107  *
 108  * @param obj The button object
 109  * @return Timeout in seconds
 110  *
 111  * @see elm_button_autorepeat_initial_timeout_set()
 112  */
 113 EAPI double                       elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj);
 114
 115 /**
 116  * Set the interval between each generated autorepeat event
 117  *
 118  * After the first @c repeated event is fired, all subsequent ones will
 119  * follow after a delay of @p t seconds for each.
 120  *
 121  * @param obj The button object
 122  * @param t   Interval in seconds
 123  *
 124  * @see elm_button_autorepeat_initial_timeout_set()
 125  */
 126 EAPI void                         elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t);
 127
 128 /**
 129  * Get the interval between each generated autorepeat event
 130  *
 131  * @param obj The button object
 132  * @return Interval in seconds
 133  */
 134 EAPI double                       elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj);
 135
 136 /**
 137  * @}
 138  */