1 /**
2  * @addtogroup Elm_Prefs
3  *
4  * @{
5  */
6 
7 /**
8  * @brief Add a new prefs widget
9  *
10  * @param parent The parent widget to hold the new one
11  * @return The new object or @c NULL, on errors
12  *
13  * @since 1.8
14  */
15 EAPI Evas_Object       *elm_prefs_add(Evas_Object *parent);
16 
17 /* API for prefs interface modules, from now on */
18 
19 typedef struct _Elm_Prefs_Item_Spec_Void Elm_Prefs_Item_Spec_Void;
20 struct _Elm_Prefs_Item_Spec_Void
21 {
22    char dummy;  //for compatibility (warning: empty struct has size 0 in C, size 1 in C++)
23 };
24 
25 typedef struct _Elm_Prefs_Item_Spec_Bool Elm_Prefs_Item_Spec_Bool;
26 struct _Elm_Prefs_Item_Spec_Bool
27 {
28    Eina_Bool def;
29 };
30 
31 typedef struct _Elm_Prefs_Item_Spec_Int Elm_Prefs_Item_Spec_Int;
32 struct _Elm_Prefs_Item_Spec_Int
33 {
34    int def, min, max;
35 };
36 
37 typedef struct _Elm_Prefs_Item_Spec_Float Elm_Prefs_Item_Spec_Float;
38 struct _Elm_Prefs_Item_Spec_Float
39 {
40    float def, min, max;
41 };
42 
43 typedef struct _Elm_Prefs_Item_Spec_String Elm_Prefs_Item_Spec_String;
44 struct _Elm_Prefs_Item_Spec_String
45 {
46    const char *def;
47    const char *placeholder;
48    const char *accept;
49    const char *deny;
50 
51    struct
52    {
53       int min, max;
54    } length;
55 };
56 
57 typedef struct _Elm_Prefs_Item_Spec_Date Elm_Prefs_Item_Spec_Date;
58 struct _Elm_Prefs_Item_Spec_Date
59 {
60    struct
61    {
62       unsigned char  d; /* day*/
63       unsigned char  m; /* month*/
64       unsigned short y; /* year */
65    } def;
66 
67    struct
68    {
69       unsigned char  d; /* day*/
70       unsigned char  m; /* month*/
71       unsigned short y; /* year */
72    } min;
73 
74    struct
75    {
76       unsigned char  d; /* day*/
77       unsigned char  m; /* month*/
78       unsigned short y; /* year */
79    } max;
80 };
81 
82 typedef struct _Elm_Prefs_Item_Spec_Page Elm_Prefs_Item_Spec_Page;
83 struct _Elm_Prefs_Item_Spec_Page
84 {
85    const char *source;
86 };
87 
88 typedef union _Elm_Prefs_Item_Spec Elm_Prefs_Item_Spec;
89 union _Elm_Prefs_Item_Spec
90 {
91    Elm_Prefs_Item_Spec_Void   v;
92    Elm_Prefs_Item_Spec_Bool   b;
93    Elm_Prefs_Item_Spec_Int    i;
94    Elm_Prefs_Item_Spec_Float  f;
95    Elm_Prefs_Item_Spec_String s;
96    Elm_Prefs_Item_Spec_Date   d;
97    Elm_Prefs_Item_Spec_Page   p;
98 };
99 
100 typedef struct _Elm_Prefs_Item_Iface Elm_Prefs_Item_Iface;
101 
102 typedef void                            (*Elm_Prefs_Item_Changed_Cb)(Evas_Object *it_obj);   /**< Elementary prefs' item widget changed function signature */
103 
104 /**
105  * @struct _Elm_Prefs_Item_Iface
106  *
107  * @brief Interface between items of the @ref elm-prefs-widget widget
108  *        and the real widgets implementing them.
109  *
110  * This structure defines the interface between the
111  * @ref elm-prefs-widget widget's items (all item types in Elementary prefs
112  * collections but the @c PAGE one) and Elementary widgets
113  * implementing them. @c add() is the only mandatory function an
114  * item widget has to implement.
115  *
116  * @note For items of type @c PAGE, refer to #Elm_Prefs_Page_Iface.
117  *
118  * @since 1.8
119  */
120 struct _Elm_Prefs_Item_Iface
121 {
122 #define ELM_PREFS_ITEM_IFACE_ABI_VERSION (1)
123    unsigned int               abi_version; /**< always use:
124                                             *  - #ELM_PREFS_ITEM_IFACE_ABI_VERSION to declare.
125                                             *  - elm_prefs_widget_iface_abi_version_get() to check.
126                                             */
127 
128    const Elm_Prefs_Item_Type *types;  /**< types of prefs items supported by the widget, #ELM_PREFS_TYPE_UNKNOWN terminated */
129 
130    Evas_Object              * (*add)(const Elm_Prefs_Item_Iface * iface,
131                                      Evas_Object * prefs,
132                                      const Elm_Prefs_Item_Type type,
133                                      const Elm_Prefs_Item_Spec spec,
134                                      Elm_Prefs_Item_Changed_Cb it_changed_cb); /**< Function to instantiate the item widget. It must return the widget handle, which should be the @c obj argument on the functions which follow. That object argument, by the way, should always have their respective #Elm_Prefs_Item_Node handle accessible via a @c "prefs_item" Evas object data value. The return value of the following functions should be @c EINA_TRUE, on success or @c EINA_FALSE, otherwise. */
135 
136    Eina_Bool                  (*value_set)(Evas_Object *obj,
137                                            Eina_Value *value); /**< Function to set the value on the item widget. Note that for items of type #ELM_PREFS_TYPE_SEPARATOR, this function has a special meaning of making the separator widget a @b horizontal one */
138 
139    Eina_Bool                  (*value_get)(Evas_Object *obj,
140                                            Eina_Value *value); /**< Function to set the value on the item widget. Note that for items of type #ELM_PREFS_TYPE_SEPARATOR, this function has a special meaning of making the separator widget a @b vertical one */
141 
142    Eina_Bool                  (*value_validate)(Evas_Object *obj); /** < Function to validate the value from the item widget before saving it. The return value of the following function should be @c EINA_TRUE, if the value conforms with the expected or @c EINA_FALSE, otherwise. */
143 
144    Eina_Bool                  (*label_set)(Evas_Object *obj,
145                                            const char *label); /**< function to set a label on the item widget */
146 
147    Eina_Bool                  (*icon_set)(Evas_Object *obj,
148                                           const char *icon); /**< function to set an icon on the item widget */
149 
150    Eina_Bool                  (*editable_set)(Evas_Object *obj,
151                                               Eina_Bool val); /**< function to set an item widget as editable or not */
152 
153    Eina_Bool                  (*editable_get)(Evas_Object *obj); /**< function to retrieve whether an item widget is editable or not */
154 
155    Eina_Bool                  (*expand_want)(Evas_Object *obj); /**< function to get whether the item implementation needs to be expanded in the page's longitudinal axis or not */
156 };
157 
158 typedef struct _Elm_Prefs_Item_Iface_Info Elm_Prefs_Item_Iface_Info;
159 /**
160  * Convenience struct used to mass-register widgets implementing
161  * prefs @b items interfaces.
162  *
163  * To be used with elm_prefs_item_iface_register() and
164  * elm_prefs_item_iface_unregister().
165  */
166 struct _Elm_Prefs_Item_Iface_Info
167 {
168    const char                 *widget_name; /**< The name of the widget implementing the interface, to be exposed on the prefs collections language. */
169    const Elm_Prefs_Item_Iface *info; /**< The type interface's implementation. */
170 };
171 
172 /**
173  * Mass-register widgets implementing prefs @b items interfaces.
174  *
175  * @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
176  * terminated.
177  *
178  * This will register all item interfaces declared on @a array in
179  * Elementary, so that the prefs widget will recognize them on @c .epc
180  * files @c 'widget:' (item) declarations.
181  *
182  * @see elm_prefs_item_iface_unregister()
183  *
184  * @since 1.8
185  */
186 EAPI void      elm_prefs_item_iface_register(const Elm_Prefs_Item_Iface_Info *array);
187 
188 /**
189  * Mass-unregister widgets implementing prefs @b items interfaces.
190  *
191  * @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
192  * terminated.
193  *
194  * This will unregister all item interfaces declared on @a array in
195  * Elementary, given they had been previously registered.
196  *
197  * @see elm_prefs_item_iface_register() for more details
198  *
199  * @since 1.8
200  */
201 EAPI void      elm_prefs_item_iface_unregister(const Elm_Prefs_Item_Iface_Info *array);
202 
203 EAPI Eina_Bool elm_prefs_item_widget_common_add(Evas_Object *prefs,
204                                                 Evas_Object *obj);
205 
206 typedef struct _Elm_Prefs_Page_Iface Elm_Prefs_Page_Iface;
207 /**
208  * @struct _Elm_Prefs_Page_Iface
209  *
210  * @brief Interface between pages of the @ref elm-prefs-widget widget
211  *        and the real widgets implementing them.
212  *
213  * This structure defines the interface between the
214  * @ref elm-prefs-widget widget's pages and Elementary widgets
215  * implementing them.
216  *
217  * It is @b mandatory that the following functions be implemented, at
218  * least, for a page widget:
219  *
220  * - #Elm_Prefs_Page_Iface::add
221  * - #Elm_Prefs_Page_Iface::item_pack
222  * - #Elm_Prefs_Page_Iface::item_unpack
223  * - #Elm_Prefs_Page_Iface::item_pack_before
224  * - #Elm_Prefs_Page_Iface::item_pack_after
225  *
226  * @note For regular, non-page prefs items, refer to #Elm_Prefs_Item_Iface.
227  *
228  * @since 1.8
229  */
230 struct _Elm_Prefs_Page_Iface
231 {
232 #define ELM_PREFS_PAGE_IFACE_ABI_VERSION (1)
233    unsigned int  abi_version; /**< always use:
234                                *  - #ELM_PREFS_PAGE_IFACE_ABI_VERSION to declare.
235                                *  - elm_prefs_widget_iface_abi_version_get() to check.
236                                */
237 
238    Evas_Object * (*add)(const Elm_Prefs_Page_Iface * iface,
239                         Evas_Object * prefs); /**< Function to instantiate the page widget. It must return the widget handle, which should be the @c obj argument on the functions which follow. That object argument, by the way, should always have their respective #Elm_Prefs_Page_Node handle accessible via a @c "prefs_page" Evas object data value. The return value of the following functions should be @c EINA_TRUE, on success or @c EINA_FALSE, otherwise. */
240 
241    Eina_Bool     (*title_set)(Evas_Object *obj,
242                               const char *title); /**< function to set a title on the page widget */
243 
244    Eina_Bool     (*sub_title_set)(Evas_Object *obj,
245                                   const char *sub_title); /**< function to set a sub-title on the page widget */
246 
247    Eina_Bool     (*icon_set)(Evas_Object *obj,
248                              const char *icon); /**< function to set an icon on the page widget */
249 
250    Eina_Bool     (*item_pack)(Evas_Object *obj,
251                               Evas_Object *it,
252                               const Elm_Prefs_Item_Type type,
253                               const Elm_Prefs_Item_Iface *iface); /**< function to pack an item (widget) on the page widget */
254 
255 
256    Eina_Bool     (*item_unpack)(Evas_Object *obj,
257                                 Evas_Object *it); /**< function to unpack an item (widget) on the page widget */
258 
259    Eina_Bool     (*item_pack_before)(Evas_Object *obj,
260                                      Evas_Object *it,
261                                      Evas_Object *it_before,
262                                      const Elm_Prefs_Item_Type type,
263                                      const Elm_Prefs_Item_Iface *iface); /**< function to pack an item (widget) on the page widget, before a pre-existing, referential, packed one */
264 
265    Eina_Bool     (*item_pack_after)(Evas_Object *obj,
266                                     Evas_Object *it,
267                                     Evas_Object *it_after, /**< function to pack an item (widget) on the page widget, after a pre-existing, referential, packed one */
268                                     const Elm_Prefs_Item_Type type,
269                                     const Elm_Prefs_Item_Iface *iface);
270 };
271 
272 typedef struct _Elm_Prefs_Page_Iface_Info Elm_Prefs_Page_Iface_Info;
273 /**
274  * Convenience struct used to mass-register widgets implementing
275  * prefs @b pages interfaces.
276  *
277  * To be used with elm_prefs_page_iface_register() and
278  * elm_prefs_page_iface_unregister().
279  */
280 struct _Elm_Prefs_Page_Iface_Info
281 {
282    const char                 *widget_name; /**< The name of the widget implementing the interface, to be exposed on the prefs collections language. */
283    const Elm_Prefs_Page_Iface *info; /**< The interface's implementation. */
284 };
285 
286 /**
287  * Mass-register widgets implementing prefs @b pages interfaces.
288  *
289  * @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
290  * terminated.
291  *
292  * This will register all page interfaces declared on @a array in
293  * Elementary, so that the prefs widget will recognize them on @c .epc
294  * files @c 'widget:' (page) declarations.
295  *
296  * @see elm_prefs_page_iface_unregister()
297  *
298  * @since 1.8
299  */
300 EAPI void      elm_prefs_page_iface_register(const Elm_Prefs_Page_Iface_Info *array);
301 
302 /**
303  * Mass-unregister widgets implementing prefs @b pages interfaces.
304  *
305  * @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
306  * terminated.
307  *
308  * This will unregister all page interfaces declared on @a array in
309  * Elementary, given they had been previously registered.
310  *
311  * @see elm_prefs_page_iface_register() for more details
312  *
313  * @since 1.8
314  */
315 EAPI void      elm_prefs_page_iface_unregister(const Elm_Prefs_Page_Iface_Info *array);
316 
317 /**
318  * @}
319  */
320