fomatting of headers -> fixup. and documentation fixing.
[framework/uifw/elementary.git] / src / lib / elm_check.h
1 /**
2  * @defgroup Check Check
3  *
4  * @image html img/widget/check/preview-00.png
5  * @image latex img/widget/check/preview-00.eps
6  * @image html img/widget/check/preview-01.png
7  * @image latex img/widget/check/preview-01.eps
8  * @image html img/widget/check/preview-02.png
9  * @image latex img/widget/check/preview-02.eps
10  *
11  * @brief The check widget allows for toggling a value between true and
12  * false.
13  *
14  * Check objects are a lot like radio objects in layout and functionality
15  * except they do not work as a group, but independently and only toggle the
16  * value of a boolean from false to true (0 or 1). elm_check_state_set() sets
17  * the boolean state (1 for true, 0 for false), and elm_check_state_get()
18  * returns the current state. For convenience, like the radio objects, you
19  * can set a pointer to a boolean directly with elm_check_state_pointer_set()
20  * for it to modify.
21  *
22  * Signals that you can add callbacks for are:
23  * "changed" - This is called whenever the user changes the state of one of
24  *             the check object(event_info is NULL).
25  *
26  * Default contents parts of the check widget that you can use for are:
27  * @li "icon" - An icon of the check
28  *
29  * Default text parts of the check widget that you can use for are:
30  * @li "elm.text" - Label of the check
31  *
32  * @ref tutorial_check should give you a firm grasp of how to use this widget
33  * .
34  * @{
35  */
36 /**
37  * @brief Add a new Check object
38  *
39  * @param parent The parent object
40  * @return The new object or NULL if it cannot be created
41  */
42 EAPI Evas_Object *
43                                   elm_check_add(Evas_Object *parent)
44 EINA_ARG_NONNULL(1);
45
46 /**
47  * @brief Set the text label of the check object
48  *
49  * @param obj The check object
50  * @param label The text label string in UTF-8
51  *
52  * @deprecated use elm_object_text_set() instead.
53  */
54 EINA_DEPRECATED EAPI void         elm_check_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
55
56 /**
57  * @brief Get the text label of the check object
58  *
59  * @param obj The check object
60  * @return The text label string in UTF-8
61  *
62  * @deprecated use elm_object_text_get() instead.
63  */
64 EINA_DEPRECATED EAPI const char  *elm_check_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
65
66 /**
67  * @brief Set the icon object of the check object
68  *
69  * @param obj The check object
70  * @param icon The icon object
71  *
72  * Once the icon object is set, a previously set one will be deleted.
73  * If you want to keep that old content object, use the
74  * elm_object_content_unset() function.
75  *
76  * @deprecated use elm_object_part_content_set() instead.
77  *
78  */
79 EINA_DEPRECATED EAPI void         elm_check_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
80
81 /**
82  * @brief Get the icon object of the check object
83  *
84  * @param obj The check object
85  * @return The icon object
86  *
87  * @deprecated use elm_object_part_content_get() instead.
88  *
89  */
90 EINA_DEPRECATED EAPI Evas_Object *elm_check_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
91
92 /**
93  * @brief Unset the icon used for the check object
94  *
95  * @param obj The check object
96  * @return The icon object that was being used
97  *
98  * Unparent and return the icon object which was set for this widget.
99  *
100  * @deprecated use elm_object_part_content_unset() instead.
101  *
102  */
103 EINA_DEPRECATED EAPI Evas_Object *elm_check_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
104
105 /**
106  * @brief Set the on/off state of the check object
107  *
108  * @param obj The check object
109  * @param state The state to use (1 == on, 0 == off)
110  *
111  * This sets the state of the check. If set
112  * with elm_check_state_pointer_set() the state of that variable is also
113  * changed. Calling this @b doesn't cause the "changed" signal to be emited.
114  */
115 EAPI void                         elm_check_state_set(Evas_Object *obj, Eina_Bool state) EINA_ARG_NONNULL(1);
116
117 /**
118  * @brief Get the state of the check object
119  *
120  * @param obj The check object
121  * @return The boolean state
122  */
123 EAPI Eina_Bool                    elm_check_state_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
124
125 /**
126  * @brief Set a convenience pointer to a boolean to change
127  *
128  * @param obj The check object
129  * @param statep Pointer to the boolean to modify
130  *
131  * This sets a pointer to a boolean, that, in addition to the check objects
132  * state will also be modified directly. To stop setting the object pointed
133  * to simply use NULL as the @p statep parameter. If @p statep is not NULL,
134  * then when this is called, the check objects state will also be modified to
135  * reflect the value of the boolean @p statep points to, just like calling
136  * elm_check_state_set().
137  */
138 EAPI void                         elm_check_state_pointer_set(Evas_Object *obj, Eina_Bool *statep) EINA_ARG_NONNULL(1);
139 EINA_DEPRECATED EAPI void         elm_check_states_labels_set(Evas_Object *obj, const char *ontext, const char *offtext) EINA_ARG_NONNULL(1, 2, 3);
140 EINA_DEPRECATED EAPI void         elm_check_states_labels_get(const Evas_Object *obj, const char **ontext, const char **offtext) EINA_ARG_NONNULL(1, 2, 3);
141
142 /**
143  * @}
144  */