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