2 * @defgroup Button Button
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
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.
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
22 * Also, defined in the default theme, the button has the following styles
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.
31 * Default contents parts of the button widget that you can use for are:
32 * @li "icon" - An icon of the button
34 * Default text parts of the button widget that you can use for are:
35 * @li "default" - Label of the button
37 * Follow through a complete example @ref button_example_01 "here".
42 * Add a new button to the parent's canvas
44 * @param parent The parent object
45 * @return The new object or NULL if it cannot be created
47 EAPI Evas_Object *elm_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
50 * Set the label used in the button
52 * The passed @p label can be NULL to clean any existing text in it and
53 * leave the button as an icon only object.
55 * @param obj The button object
56 * @param label The text will be written on the button
57 * @deprecated use elm_object_text_set() instead.
59 EINA_DEPRECATED EAPI void elm_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
62 * Get the label set for the button
64 * The string returned is an internal pointer and should not be freed or
65 * altered. It will also become invalid when the button is destroyed.
66 * The string returned, if not NULL, is a stringshare, so if you need to
67 * keep it around even after the button is destroyed, you can use
68 * eina_stringshare_ref().
70 * @param obj The button object
71 * @return The text set to the label, or NULL if nothing is set
72 * @deprecated use elm_object_text_set() instead.
74 EINA_DEPRECATED EAPI const char *elm_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
77 * Set the icon used for the button
79 * Setting a new icon will delete any other that was previously set, making
80 * any reference to them invalid. If you need to maintain the previous
81 * object alive, unset it first with elm_button_icon_unset().
83 * @param obj The button object
84 * @param icon The icon object for the button
85 * @deprecated use elm_object_part_content_set() instead.
87 EINA_DEPRECATED EAPI void elm_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
90 * Get the icon used for the button
92 * Return the icon object which is set for this widget. If the button is
93 * destroyed or another icon is set, the returned object will be deleted
94 * and any reference to it will be invalid.
96 * @param obj The button object
97 * @return The icon object that is being used
99 * @deprecated use elm_object_part_content_get() instead
101 EINA_DEPRECATED EAPI Evas_Object *elm_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
104 * Remove the icon set without deleting it and return the object
106 * This function drops the reference the button holds of the icon object
107 * and returns this last object. It is used in case you want to remove any
108 * icon, or set another one, without deleting the actual object. The button
109 * will be left without an icon set.
111 * @param obj The button object
112 * @return The icon object that was being used
113 * @deprecated use elm_object_part_content_unset() instead.
115 EINA_DEPRECATED EAPI Evas_Object *elm_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
118 * Turn on/off the autorepeat event generated when the button is kept pressed
120 * When off, no autorepeat is performed and buttons emit a normal @c clicked
121 * signal when they are clicked.
123 * When on, keeping a button pressed will continuously emit a @c repeated
124 * signal until the button is released. The time it takes until it starts
125 * emitting the signal is given by
126 * elm_button_autorepeat_initial_timeout_set(), and the time between each
127 * new emission by elm_button_autorepeat_gap_timeout_set().
129 * @param obj The button object
130 * @param on A bool to turn on/off the event
132 EAPI void elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on) EINA_ARG_NONNULL(1);
135 * Get whether the autorepeat feature is enabled
137 * @param obj The button object
138 * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
140 * @see elm_button_autorepeat_set()
142 EAPI Eina_Bool elm_button_autorepeat_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
145 * Set the initial timeout before the autorepeat event is generated
147 * Sets the timeout, in seconds, since the button is pressed until the
148 * first @c repeated signal is emitted. If @p t is 0.0 or less, there
149 * won't be any delay and the even will be fired the moment the button is
152 * @param obj The button object
153 * @param t Timeout in seconds
155 * @see elm_button_autorepeat_set()
156 * @see elm_button_autorepeat_gap_timeout_set()
158 EAPI void elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
161 * Get the initial timeout before the autorepeat event is generated
163 * @param obj The button object
164 * @return Timeout in seconds
166 * @see elm_button_autorepeat_initial_timeout_set()
168 EAPI double elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
171 * Set the interval between each generated autorepeat event
173 * After the first @c repeated event is fired, all subsequent ones will
174 * follow after a delay of @p t seconds for each.
176 * @param obj The button object
177 * @param t Interval in seconds
179 * @see elm_button_autorepeat_initial_timeout_set()
181 EAPI void elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
184 * Get the interval between each generated autorepeat event
186 * @param obj The button object
187 * @return Interval in seconds
189 EAPI double elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);