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