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 widgets 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 three 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  * Default contents parts of the button widget that you can use for are:
  32  * @li "icon" - An icon of the button
  33  *
  34  * Default text parts of the button widget that you can use for are:
  35  * @li "default" - Label of the button
  36  *
  37  * Follow through a complete example @ref button_example_01 "here".
  38  * @{
  39  */
  40
  41 /**
  42  * Add a new button to the parent's canvas
  43  *
  44  * @param parent The parent object
  45  * @return The new object or NULL if it cannot be created
  46  */
  47 EAPI Evas_Object *
  48                                   elm_button_add(Evas_Object *parent)
  49 EINA_ARG_NONNULL(1);
  50
  51 /**
  52  * Set the label used in the button
  53  *
  54  * The passed @p label can be NULL to clean any existing text in it and
  55  * leave the button as an icon only object.
  56  *
  57  * @param obj The button object
  58  * @param label The text will be written on the button
  59  * @deprecated use elm_object_text_set() instead.
  60  */
  61 EINA_DEPRECATED EAPI void         elm_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  62
  63 /**
  64  * Get the label set for the button
  65  *
  66  * The string returned is an internal pointer and should not be freed or
  67  * altered. It will also become invalid when the button is destroyed.
  68  * The string returned, if not NULL, is a stringshare, so if you need to
  69  * keep it around even after the button is destroyed, you can use
  70  * eina_stringshare_ref().
  71  *
  72  * @param obj The button object
  73  * @return The text set to the label, or NULL if nothing is set
  74  * @deprecated use elm_object_text_set() instead.
  75  */
  76 EINA_DEPRECATED EAPI const char  *elm_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  77
  78 /**
  79  * Set the icon used for the button
  80  *
  81  * Setting a new icon will delete any other that was previously set, making
  82  * any reference to them invalid. If you need to maintain the previous
  83  * object alive, unset it first with elm_button_icon_unset().
  84  *
  85  * @param obj The button object
  86  * @param icon The icon object for the button
  87  * @deprecated use elm_object_part_content_set() instead.
  88  */
  89 EINA_DEPRECATED EAPI void         elm_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
  90
  91 /**
  92  * Get the icon used for the button
  93  *
  94  * Return the icon object which is set for this widget. If the button is
  95  * destroyed or another icon is set, the returned object will be deleted
  96  * and any reference to it will be invalid.
  97  *
  98  * @param obj The button object
  99  * @return The icon object that is being used
 100  *
 101  * @deprecated use elm_object_part_content_get() instead
 102  */
 103 EINA_DEPRECATED EAPI Evas_Object *elm_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 104
 105 /**
 106  * Remove the icon set without deleting it and return the object
 107  *
 108  * This function drops the reference the button holds of the icon object
 109  * and returns this last object. It is used in case you want to remove any
 110  * icon, or set another one, without deleting the actual object. The button
 111  * will be left without an icon set.
 112  *
 113  * @param obj The button object
 114  * @return The icon object that was being used
 115  * @deprecated use elm_object_part_content_unset() instead.
 116  */
 117 EINA_DEPRECATED EAPI Evas_Object *elm_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 118
 119 /**
 120  * Turn on/off the autorepeat event generated when the button is kept pressed
 121  *
 122  * When off, no autorepeat is performed and buttons emit a normal @c clicked
 123  * signal when they are clicked.
 124  *
 125  * When on, keeping a button pressed will continuously emit a @c repeated
 126  * signal until the button is released. The time it takes until it starts
 127  * emitting the signal is given by
 128  * elm_button_autorepeat_initial_timeout_set(), and the time between each
 129  * new emission by elm_button_autorepeat_gap_timeout_set().
 130  *
 131  * @param obj The button object
 132  * @param on  A bool to turn on/off the event
 133  */
 134 EAPI void                         elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on) EINA_ARG_NONNULL(1);
 135
 136 /**
 137  * Get whether the autorepeat feature is enabled
 138  *
 139  * @param obj The button object
 140  * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
 141  *
 142  * @see elm_button_autorepeat_set()
 143  */
 144 EAPI Eina_Bool                    elm_button_autorepeat_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 145
 146 /**
 147  * Set the initial timeout before the autorepeat event is generated
 148  *
 149  * Sets the timeout, in seconds, since the button is pressed until the
 150  * first @c repeated signal is emitted. If @p t is 0.0 or less, there
 151  * won't be any delay and the even will be fired the moment the button is
 152  * pressed.
 153  *
 154  * @param obj The button object
 155  * @param t   Timeout in seconds
 156  *
 157  * @see elm_button_autorepeat_set()
 158  * @see elm_button_autorepeat_gap_timeout_set()
 159  */
 160 EAPI void                         elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
 161
 162 /**
 163  * Get the initial timeout before the autorepeat event is generated
 164  *
 165  * @param obj The button object
 166  * @return Timeout in seconds
 167  *
 168  * @see elm_button_autorepeat_initial_timeout_set()
 169  */
 170 EAPI double                       elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 171
 172 /**
 173  * Set the interval between each generated autorepeat event
 174  *
 175  * After the first @c repeated event is fired, all subsequent ones will
 176  * follow after a delay of @p t seconds for each.
 177  *
 178  * @param obj The button object
 179  * @param t   Interval in seconds
 180  *
 181  * @see elm_button_autorepeat_initial_timeout_set()
 182  */
 183 EAPI void                         elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
 184
 185 /**
 186  * Get the interval between each generated autorepeat event
 187  *
 188  * @param obj The button object
 189  * @return Interval in seconds
 190  */
 191 EAPI double                       elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 192
 193 /**
 194  * @}
 195  */