#ifndef ELM_PREFS_H
#define ELM_PREFS_H
#define ELM_OBJ_PREFS_CLASS elm_obj_prefs_class_get()
const Eo_Class *elm_obj_prefs_class_get(void) EINA_CONST;
extern EAPI Eo_Op ELM_OBJ_PREFS_BASE_ID;
enum
{
ELM_OBJ_PREFS_SUB_ID_FILE_SET,
ELM_OBJ_PREFS_SUB_ID_FILE_GET,
ELM_OBJ_PREFS_SUB_ID_DATA_SET,
ELM_OBJ_PREFS_SUB_ID_DATA_GET,
ELM_OBJ_PREFS_SUB_ID_AUTOSAVE_SET,
ELM_OBJ_PREFS_SUB_ID_AUTOSAVE_GET,
ELM_OBJ_PREFS_SUB_ID_RESET,
ELM_OBJ_PREFS_SUB_ID_ITEM_VALUE_SET,
ELM_OBJ_PREFS_SUB_ID_ITEM_VALUE_GET,
ELM_OBJ_PREFS_SUB_ID_ITEM_OBJECT_GET,
ELM_OBJ_PREFS_SUB_ID_ITEM_VISIBLE_SET,
ELM_OBJ_PREFS_SUB_ID_ITEM_VISIBLE_GET,
ELM_OBJ_PREFS_SUB_ID_ITEM_DISABLED_SET,
ELM_OBJ_PREFS_SUB_ID_ITEM_DISABLED_GET,
ELM_OBJ_PREFS_SUB_ID_ITEM_EDITABLE_SET,
ELM_OBJ_PREFS_SUB_ID_ITEM_EDITABLE_GET,
ELM_OBJ_PREFS_SUB_ID_ITEM_SWALLOW,
ELM_OBJ_PREFS_SUB_ID_ITEM_UNSWALLOW,
ELM_OBJ_PREFS_SUB_ID_LAST
};
#define ELM_OBJ_PREFS_ID(sub_id) (ELM_OBJ_PREFS_BASE_ID + sub_id)
/**
* @def elm_obj_prefs_file_set
*
* Set file and page to populate a given prefs widget's interface.
*
* @param[in] file
* @param[in] page
* @param[out] ret
*
* @see elm_prefs_file_set()
*
* @since 1.8
*/
#define elm_obj_prefs_file_set(file, page, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_FILE_SET), \
EO_TYPECHECK(const char *, file), \
EO_TYPECHECK(const char *, page), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_file_get
*
* Retrieve file and page bound to a given prefs widget.
*
* @param[out] file
* @param[out] page
* @param[out] ret
*
* @see elm_prefs_file_get()
*
* @since 1.8
*/
#define elm_obj_prefs_file_get(file, page, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_FILE_GET), \
EO_TYPECHECK(const char **, file), \
EO_TYPECHECK(const char **, page), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_data_set
*
* Set user data for a given prefs widget
*
* @param[in] data
* @param[out] ret
*
* @see elm_prefs_data_set()
*
* @since 1.8
*/
#define elm_obj_prefs_data_set(data, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_DATA_SET), \
EO_TYPECHECK(Elm_Prefs_Data *, data), \
EO_TYPECHECK(Eina_Bool *, ret)
//FIXME: prefs_data == eobject?
/**
* @def elm_obj_prefs_data_get
*
* Retrieve user data for a given prefs widget
*
* @param[out] ret
*
* @see elm_prefs_data_get()
*
* @since 1.8
*/
#define elm_obj_prefs_data_get(ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_DATA_GET), \
EO_TYPECHECK(Elm_Prefs_Data **, ret)
/**
* @def elm_obj_prefs_autosave_set
*
* Set whether a given prefs widget should save its values back (on
* the user data file, if set) automatically on every UI element
* changes.
*
* @param[in] autosave
*
* @see elm_prefs_autosave_get()
*
* @since 1.8
*/
#define elm_obj_prefs_autosave_set(autosave) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_AUTOSAVE_SET), \
EO_TYPECHECK(Eina_Bool, autosave)
/**
* @def elm_obj_prefs_autosave_get
*
* Get whether a given prefs widget is saving its values back
* automatically on changes.
*
* @param[out] ret
*
* @see elm_prefs_autosave_set()
*
* @since 1.8
*/
#define elm_obj_prefs_autosave_get(ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_AUTOSAVE_GET), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_reset
*
* Reset the values of a given prefs widget to a previous state.
*
* @param[in] mode
*
* @since 1.8
*/
#define elm_obj_prefs_reset(mode) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_RESET), \
EO_TYPECHECK(Elm_Prefs_Reset_Mode, mode)
/**
* @def elm_obj_prefs_item_value_set
*
* Set the value on a given prefs widget's item.
*
* @param[in] name
* @param[in] value
* @param[out] ret
*
* @see elm_prefs_item_value_get()
*
* @since 1.8
*/
#define elm_obj_prefs_item_value_set(name, value, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_VALUE_SET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(const Eina_Value *, value), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_item_value_get
*
* Retrieve the value of a given prefs widget's item.
*
* @param[in] name
* @param[out] value
* @param[out] ret
*
* @see elm_prefs_item_value_set()
*
* @since 1.8
*/
#define elm_obj_prefs_item_value_get(name, value, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_VALUE_GET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Eina_Value *, value), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_item_object_get
*
* Retrieve the Elementary widget bound to a given prefs widget's
* item.
*
* @param[in] name
* @param[out] ret
*
* @see elm_prefs_item_value_get()
*
* @since 1.8
*/
#define elm_obj_prefs_item_object_get(name, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_OBJECT_GET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(const Evas_Object **, ret) //FIXME: return EObject?
/**
* @def elm_obj_prefs_item_visible_set
*
* Set whether the widget bound to given prefs widget's item should be
* visible or not.
*
* @param[in] name
* @param[in] visible
*
* @see elm_prefs_item_visible_set()
*
* @since 1.8
*/
#define elm_obj_prefs_item_visible_set(name, visible) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_VISIBLE_SET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Eina_Bool, visible)
/**
* @def elm_obj_prefs_item_visible_get
*
* Retrieve whether the widget bound to a given prefs widget's item is
* visible or not.
*
* @param[in] name
* @param[out] ret
*
* @see elm_prefs_item_visible_get()
*
* @since 1.8
*/
#define elm_obj_prefs_item_visible_get(name, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_VISIBLE_GET), \
EO_TYPECHECK(const char *,name), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_item_disabled_set
*
* Set whether the widget bound to a given prefs widget's item is
* disabled or not.
*
* @param[in] name
* @param[in] disabled
*
* @see elm_prefs_item_disabled_set()
*
* @since 1.8
*/
#define elm_obj_prefs_item_disabled_set(name, disabled) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_DISABLED_SET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Eina_Bool, disabled)
/**
* @def elm_obj_prefs_item_disabled_get
*
* Retrieve whether the widget bound to a given prefs widget's item is
* disabled or not.
*
* @param[in] name
* @param[out] ret
*
* @see elm_prefs_item_disabled_get()
*
* @since 1.8
*/
#define elm_obj_prefs_item_disabled_get(name, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_DISABLED_GET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_item_editable_set
*
* Set whether the widget bound to a given prefs widget's item is
* editable or not.
*
* @param[in] name
* @param[in] editable
*
* @see elm_prefs_item_editable_set()
*
* @since 1.8
*/
#define elm_obj_prefs_item_editable_set(name, editable) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_EDITABLE_SET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Eina_Bool, editable)
/**
* @def elm_obj_prefs_item_editable_get
*
* Retrieve whether the widget bound to a given prefs widget's item is
* editable or not.
*
* @param[in] name
* @param[out] ret
*
* @see elm_prefs_item_editable_get()
*
* @since 1.8
*/
#define elm_obj_prefs_item_editable_get(name, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_EDITABLE_GET), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Eina_Bool *, ret)
/**
* @def elm_obj_prefs_item_swallow
*
* "Swallows" an object into a SWALLOW item of a prefs widget.
*
* @param[in] name
* @param[in] child
* @param[out] ret
*
* @see elm_prefs_item_swallow()
*
* @since 1.8
*/
#define elm_obj_prefs_item_swallow(name, child, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_SWALLOW), \
EO_TYPECHECK(const char *, name), \
EO_TYPECHECK(Evas_Object *, child), \
EO_TYPECHECK(Eina_Bool *, ret)
//FIXME: child == EObject?
/**
* @def elm_obj_prefs_item_unswallow
*
* Unswallow an object from a SWALLOW item of a prefs widget.
*
* @param[in] name
* @param[out] ret
*
* @see elm_prefs_item_unswallow()
*
* @since 1.8
*/
#define elm_obj_prefs_item_unswallow(name, ret) \
ELM_OBJ_PREFS_ID(ELM_OBJ_PREFS_SUB_ID_ITEM_UNSWALLOW), \
EO_TYPECHECK(const char *,name), \
EO_TYPECHECK(Evas_Object **, ret)
//FIXME: ret == EObject?
/**
* @addtogroup Prefs
* @{
*
* @section elm-prefs-widget Prefs
*
* @image html img/widget/prefs/preview-00.png
* @image latex img/widget/prefs/preview-00.eps width=\textwidth
*
* @image html prefs_inheritance_tree.png
* @image latex prefs_inheritance_tree.eps
*
* Prefs is a special widget inside Elementary. It is mainly targeted
* to configuration dialogs. Its viewport is blank until you associate
* a definition file to it. That file (usually with @b .epb
* extension), is a binary format (Eet) one, coming from a
* human-readable textual declaration. This textual form, an
* Elementary prefs collection (usually with @b .epc
* extension), is translated to the binary form by means of the
* @b prefs_cc compiler.
*
* On it one declares UI elements to populate prefs widgets, which are
* contained in @b pages (a prefs widget is always bound to one page).
* Those elements get properties like:
* - default value,
* - maximum and minumum ranges,
* - acceptance and denial regular expressions, for strings,
* - visibility,
* - persistence,
* - editability, etc.
*
* Once a prefs widget is created, after elm_prefs_file_set() is
* issued on it, all of its UI elements will get default values,
* declared on that file. To fetch an user's own, personal set of
* those values, one gets to pair an @ref elm-prefs-data handle
* to the prefs widget.
*
* Personal, prefs data values with keys matching the ones present on
* the file passed on elm_prefs_file_set() to will have their values
* applied to the respective UI elements of the widget.
*
* When a prefs widget dies, the values of the elements declared on
* its @b .epb file marked as permanent will be written back to
* the user prefs data handle, if it is writable. One is also able to
* make this writing event to take place automatically after each UI
* element modification by using elm_prefs_autosave_set().
*
* This widget emits the following signals:
* - @c "page,saved": a given page has had its values saved back on
* user config file (event info is the page's
* name)
* - @c "page,reset": a given page has had its values reset (event
* info is the page's name)
* - @c "page,changed": a given page has been loaded with user
* (@c .cfg) values (event info is the page's name)
* - @c "page,loaded": a given page has been loaded with system
* (@c .epb) values (event info is the page's name)
* - @c "item,changed": a given page's item has changed (event info is
* the item's full hierarchical name, in the form
* @c "page:subpage:subsubpage:item")
* - @c "action": an action item has been triggered (event info is the
* item's full hierarchical name, in the form @c
* "page:subpage:subsubpage:item")
*
* @li @ref epcref
*
* The following are examples on how to use prefs:
* @li @ref prefs_example_01
* @li @ref prefs_example_02
* @li @ref prefs_example_03
*/
/**
* Modes of resetting a prefs widget.
*
* @see elm_prefs_reset()
*
* @since 1.8
*/
typedef enum
{
ELM_PREFS_RESET_DEFAULTS, /** reset to default values, declared in its @b .epb file */
ELM_PREFS_RESET_LAST /** prefs will keep a small history of changes, so this resets back to last batch of changes on the UI elements. it does @b not work on autosave mode */
} Elm_Prefs_Reset_Mode;
/**
* @brief Add a new prefs widget
*
* @param parent The parent widget to hold the new one
* @return The new object or @c NULL, on errors
*
* @since 1.8
*/
EAPI Evas_Object *elm_prefs_add(Evas_Object *parent);
/**
* Set file and page to populate a given prefs widget's interface.
*
* @param o A prefs widget handle
* @param file The @b .epb (binary) file to get contents from
* @param page The page, inside @a file, where to get item contents from
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* Elm prefs widgets start blank, with no child widgets. It's meant to
* have its viewport populated with child elements coming from a
* declaration file. That file (usually with @b .epb extension), is a
* binary format (Eet) one, coming from a human-readable textual
* declaration. This textual form (usually with @b .epc extension) is
* translated to the binary form by means of the @b prefs_cc compiler.
*
* With this function, one thus populates a prefs widget with UI
* elements.
*
* If @a file is @c NULL, "elm_app_data_dir_get()/preferences.epb"
* will be used, by default. If @a file is a @b relative path, the
* prefix "elm_app_data_dir_get()/" will be implicitly used with it.
* If @a page is @c NULL, it is considered "main", as default.
*
* @warning If your binary is not properly installed and
* elm_app_data_dir_get() can't be figured out, a fallback value of
* "." will be tryed, instead.
*
* @see elm_prefs_file_get()
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_file_set(Evas_Object *o,
const char *file,
const char *page);
/**
* Retrieve file and page bound to a given prefs widget.
*
* @param o A prefs widget handle
* @param file Where to store the file @a o is bound to
* @param page Where to store the page @a o is bound to
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* @note Use @c NULL pointers on the components you're not
* interested in: they'll be ignored by the function.
*
* @see elm_prefs_file_set() for more information
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_file_get(const Evas_Object *o,
const char **file,
const char **page);
/**
* Set user data for a given prefs widget
*
* @param obj A prefs widget handle
* @param prefs_data A valid prefs_data handle
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* Once a prefs widget is created, after elm_prefs_file_set() is
* issued on it, all of its UI elements will get default values, when
* declared on that file. To fetch an user's own, personal set of
* those values, one gets to pair a prefs data handle to the
* prefs widget. This is what this call is intended for.
*
* Prefs data values from @a prefs_data with keys matching the ones
* present on the file passed on elm_prefs_file_set() to @a obj will
* have their values applied to the respective UI elements of the
* widget.
*
* When @a obj dies, the values of the elements declared on its @b
* .epb file (the one set on elm_prefs_file_set()) marked as permanent
* will be written back to @a prefs_data, if it is writable.
* One is also able to make this writing event to take place
* automatically after each UI element modification by using
* elm_prefs_autosave_set().
*
* @note @a obj will keep a reference of its own for @a prefs_data,
* but you should still unreference it by yourself, after the widget
* is gone.
*
* @see elm_prefs_data_set()
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_data_set(Evas_Object *obj,
Elm_Prefs_Data *data);
/**
* Retrieve user data for a given prefs widget
*
* @param obj A prefs widget handle
* @param prefs_data A valid prefs_data handle
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* @see elm_prefs_data_set() for more details
*
* @since 1.8
*/
EAPI Elm_Prefs_Data *elm_prefs_data_get(const Evas_Object *o);
/**
* Set whether a given prefs widget should save its values back (on
* the user data file, if set) automatically on every UI element
* changes.
*
* @param prefs A valid prefs widget handle
* @param autosave @c EINA_TRUE to save automatically, @c EINA_FALSE
* otherwise.
*
* If @a autosave is @c EINA_TRUE, every call to
* elm_prefs_item_value_set(), every
* Elm_Prefs_Data_Event_Type::ELM_PREFS_DATA_EVENT_ITEM_CHANGED event
* coming for its prefs data and every UI element direct value
* changing will implicitly make the prefs values to be flushed back
* to it prefs data. If a prefs data handle with no writing
* permissions or no prefs data is set on @a prefs, naturally nothing
* will happen.
*
* @see elm_prefs_autosave_get()
*
* @since 1.8
*/
EAPI void elm_prefs_autosave_set(Evas_Object *prefs,
Eina_Bool autosave);
/**
* Get whether a given prefs widget is saving its values back
* automatically on changes.
*
* @param prefs A valid prefs widget handle
* @return @c EINA_TRUE if @a prefs is saving automatically,
* @c EINA_FALSE otherwise.
*
* @see elm_prefs_autosave_set(), for more details
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_autosave_get(const Evas_Object *prefs);
/**
* Reset the values of a given prefs widget to a previous state.
*
* @param prefs A valid prefs widget handle
* @param mode The reset mode to apply on @a prefs
*
* As can be seen on #Elm_Prefs_Reset_Mode, there are two possible
* actions to be taken by this call -- either to reset @a prefs'
* values to the defaults (declared on the @c .epb file it is bound
* to) or to reset to the state they were before the last modification
* it got.
*
* @since 1.8
*/
EAPI void elm_prefs_reset(Evas_Object *prefs,
Elm_Prefs_Reset_Mode mode);
/**
* Set the value on a given prefs widget's item.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection)
* @param value The value to set on the item. It should be typed as
* the item expects, preferably, or a conversion will
* take place
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* This will change the value of item named @a name programatically.
*
* @see elm_prefs_item_value_get()
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_item_value_set(Evas_Object *prefs,
const char *name,
const Eina_Value *value);
/**
* Retrieve the value of a given prefs widget's item.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to get value from
* @param value Where to store the value of the item. It will be
* overwritten and setup with the type the item
* is bound to
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* This will retrieve the value of item named @a name.
*
* @see elm_prefs_item_value_set()
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_item_value_get(const Evas_Object *prefs,
const char *name,
Eina_Value *value);
/**
* Retrieve the Elementary widget bound to a given prefs widget's
* item.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to get object from
* @return A valid widget handle, on success, or @c NULL, otherwise
*
* This will retrieve a handle to the real widget implementing a given
* item of @a prefs, for read-only actions.
*
* @warning You should @b never modify the state of the returned
* widget, because it's meant to be managed by @a prefs, solely.
*
* @see elm_prefs_item_value_set()
*
* @since 1.8
*/
EAPI const Evas_Object *elm_prefs_item_object_get(Evas_Object *prefs,
const char *name);
/**
* Set whether the widget bound to given prefs widget's item should be
* visible or not.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to change visibility of
* @param visible @c EINA_TRUE, to make it visible, @c EINA_FALSE
* otherwise
*
* Each prefs item may have a default visibility state, declared on
* the @c .epb @a prefs it was loaded with. By this call one may alter
* that state, programatically.
*
* @see elm_prefs_item_visible_get()
*
* @since 1.8
*/
EAPI void elm_prefs_item_visible_set(Evas_Object *prefs,
const char *name,
Eina_Bool visible);
/**
* Retrieve whether the widget bound to a given prefs widget's item is
* visible or not.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to get visibility state from
* @return @c EINA_TRUE, if it is visible, @c EINA_FALSE
* otherwise
*
* @see elm_prefs_item_visible_set() for more details
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_item_visible_get(const Evas_Object *prefs,
const char *name);
/**
* Set whether the widget bound to a given prefs widget's item is
* disabled or not.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to act on
* @param disabled @c EINA_TRUE, to make it disabled, @c EINA_FALSE
* otherwise
*
* @see elm_prefs_item_disabled_get()
*
* @since 1.8
*/
EAPI void elm_prefs_item_disabled_set(Evas_Object *prefs,
const char *name,
Eina_Bool disabled);
/**
* Retrieve whether the widget bound to a given prefs widget's item is
* disabled or not.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to get disabled state from
* @return @c EINA_TRUE, if it is disabled, @c EINA_FALSE
* otherwise
*
* @see elm_prefs_item_disabled_set()
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_item_disabled_get(const Evas_Object *prefs,
const char *name);
/**
* Set whether the widget bound to a given prefs widget's item is
* editable or not.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to act on
* @param editable @c EINA_TRUE, to make it editable, @c EINA_FALSE
* otherwise
*
* @note Only @c TEXT or @c TEXTAREA items' default widgets implement
* the 'editable' property. Custom registered widgets may as well
* implement them.
*
* @see elm_prefs_item_editable_get()
*
* @since 1.8
*/
EAPI void elm_prefs_item_editable_set(Evas_Object *prefs,
const char *name,
Eina_Bool editable);
/**
* Retrieve whether the widget bound to a given prefs widget's item is
* editable or not.
*
* @param prefs A valid prefs widget handle
* @param name The name of the item (as declared in the prefs
* collection) to get editable state from
* @return @c EINA_TRUE, if it is editable, @c EINA_FALSE
* otherwise
*
* @see elm_prefs_item_editable_set() for more details
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_item_editable_get(const Evas_Object *prefs,
const char *name);
/**
* "Swallows" an object into a SWALLOW item of a prefs widget.
*
* @param obj A valid prefs widget handle
* @param name the name of the SWALLOW item (as declared in the prefs
* collection)
* @param child The object to occupy the item
* @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise
*
* @see elm_prefs_item_swallow() for more details
*
* @since 1.8
*/
EAPI Eina_Bool elm_prefs_item_swallow(Evas_Object *obj,
const char *name,
Evas_Object *child);
/**
* Unswallow an object from a SWALLOW item of a prefs widget.
*
* @param obj A valid prefs widget handle
* @param name the name of the SWALLOW item (as declared in the prefs
* collection)
* @return The unswallowed object, or NULL on errors
*
* @see elm_prefs_item_unswallow() for more details
*
* @since 1.8
*/
EAPI Evas_Object *elm_prefs_item_unswallow(Evas_Object *obj,
const char *name);
/* API for prefs interface modules, from now on */
typedef struct _Elm_Prefs_Item_Spec_Void
{
} Elm_Prefs_Item_Spec_Void;
typedef struct _Elm_Prefs_Item_Spec_Bool
{
Eina_Bool def;
} Elm_Prefs_Item_Spec_Bool;
typedef struct _Elm_Prefs_Item_Spec_Int
{
int def, min, max;
} Elm_Prefs_Item_Spec_Int;
typedef struct _Elm_Prefs_Item_Spec_Float
{
float def, min, max;
} Elm_Prefs_Item_Spec_Float;
typedef struct _Elm_Prefs_Item_Spec_String
{
const char *def;
const char *placeholder;
const char *accept;
const char *deny;
struct
{
int min, max;
} length;
} Elm_Prefs_Item_Spec_String;
typedef struct _Elm_Prefs_Item_Spec_Date
{
struct
{
unsigned char d; /* day*/
unsigned char m; /* month*/
unsigned short y; /* year */
} def;
struct
{
unsigned char d; /* day*/
unsigned char m; /* month*/
unsigned short y; /* year */
} min;
struct
{
unsigned char d; /* day*/
unsigned char m; /* month*/
unsigned short y; /* year */
} max;
} Elm_Prefs_Item_Spec_Date;
typedef struct _Elm_Prefs_Item_Spec_Page
{
const char *source;
} Elm_Prefs_Item_Spec_Page;
typedef union _Elm_Prefs_Item_Spec
{
Elm_Prefs_Item_Spec_Void v;
Elm_Prefs_Item_Spec_Bool b;
Elm_Prefs_Item_Spec_Int i;
Elm_Prefs_Item_Spec_Float f;
Elm_Prefs_Item_Spec_String s;
Elm_Prefs_Item_Spec_Date d;
Elm_Prefs_Item_Spec_Page p;
} Elm_Prefs_Item_Spec;
typedef struct _Elm_Prefs_Item_Iface Elm_Prefs_Item_Iface;
/**
* Convenience struct used to mass-register widgets implementing
* prefs @b items interfaces.
*
* To be used with elm_prefs_item_iface_register() and
* elm_prefs_item_iface_unregister().
*/
struct _Elm_Prefs_Item_Iface_Info
{
const char *widget_name; /**< The name of the widget implementing the interface, to be exposed on the prefs collections language. */
const Elm_Prefs_Item_Iface *info; /**< The type interface's implementation. */
};
typedef struct _Elm_Prefs_Item_Iface_Info Elm_Prefs_Item_Iface_Info;
typedef void (*Elm_Prefs_Item_Changed_Cb)(Evas_Object *it_obj); /**< Elementary prefs' item widget changed function signature */
/**
* @struct _Elm_Prefs_Item_Iface
*
* @brief Interface between items of the @ref elm-prefs-widget widget
* and the real widgets implementing them.
*
* This structure defines the interface between the
* @ref elm-prefs-widget widget's items (all item types in Elementary prefs
* collections but the @c PAGE one) and Elementary widgets
* implementing them. @c add() is the only mandatory function an
* item widget has to implement.
*
* @note For items of type @c PAGE, refer to #Elm_Prefs_Page_Iface.
*
* @since 1.8
*/
struct _Elm_Prefs_Item_Iface
{
#define ELM_PREFS_ITEM_IFACE_ABI_VERSION (1)
unsigned int abi_version; /**< always use:
* - #ELM_PREFS_ITEM_IFACE_ABI_VERSION to declare.
* - elm_prefs_widget_iface_abi_version_get() to check.
*/
const Elm_Prefs_Item_Type *types; /**< types of prefs items supported by the widget, #ELM_PREFS_TYPE_UNKNOWN terminated */
Evas_Object * (*add)(const Elm_Prefs_Item_Iface * iface,
Evas_Object * prefs,
const Elm_Prefs_Item_Type type,
const Elm_Prefs_Item_Spec spec,
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. */
Eina_Bool (*value_set)(Evas_Object *obj,
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 */
Eina_Bool (*value_get)(Evas_Object *obj,
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 */
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. */
Eina_Bool (*label_set)(Evas_Object *obj,
const char *label); /**< function to set a label on the item widget */
Eina_Bool (*icon_set)(Evas_Object *obj,
const char *icon); /**< function to set an icon on the item widget */
Eina_Bool (*editable_set)(Evas_Object *obj,
Eina_Bool val); /**< function to set an item widget as editable or not */
Eina_Bool (*editable_get)(Evas_Object *obj); /**< function to retrieve whether an item widget is editable or not */
Eina_Bool (*expand_want)(Evas_Object *obj); /**< function to get wether the item implementation needs to be expanded in the page's longitudinal axis or not */
};
/**
* Mass-register widgets implementing prefs @b items interfaces.
*
* @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
* terminated.
*
* This will register all item interfaces declared on @a array in
* Elementary, so that the prefs widget will recognize them on @c .epc
* files @c 'widget:' (item) declarations.
*
* @see elm_prefs_item_iface_unregister()
*
* @since 1.8
*/
EAPI void elm_prefs_item_iface_register(const Elm_Prefs_Item_Iface_Info *array);
/**
* Mass-unregister widgets implementing prefs @b items interfaces.
*
* @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
* terminated.
*
* This will unregister all item interfaces declared on @a array in
* Elementary, given they had been previously registered.
*
* @see elm_prefs_item_iface_register() for more details
*
* @since 1.8
*/
EAPI void elm_prefs_item_iface_unregister(const Elm_Prefs_Item_Iface_Info *array);
EAPI Eina_Bool elm_prefs_item_widget_common_add(Evas_Object *prefs,
Evas_Object *obj);
typedef struct _Elm_Prefs_Page_Iface Elm_Prefs_Page_Iface;
/**
* Convenience struct used to mass-register widgets implementing
* prefs @b pages interfaces.
*
* To be used with elm_prefs_page_iface_register() and
* elm_prefs_page_iface_unregister().
*/
struct _Elm_Prefs_Page_Iface_Info
{
const char *widget_name; /**< The name of the widget implementing the interface, to be exposed on the prefs collections language. */
const Elm_Prefs_Page_Iface *info; /**< The interface's implementation. */
};
typedef struct _Elm_Prefs_Page_Iface_Info Elm_Prefs_Page_Iface_Info;
/**
* @struct _Elm_Prefs_Page_Iface
*
* @brief Interface between pages of the @ref elm-prefs-widget widget
* and the real widgets implementing them.
*
* This structure defines the interface between the
* @ref elm-prefs-widget widget's pages and Elementary widgets
* implementing them.
*
* It is @b mandatory that the following functions be implemented, at
* least, for a page widget:
*
* - #Elm_Prefs_Page_Iface::add
* - #Elm_Prefs_Page_Iface::item_pack
* - #Elm_Prefs_Page_Iface::item_unpack
* - #Elm_Prefs_Page_Iface::item_pack_before
* - #Elm_Prefs_Page_Iface::item_pack_after
*
* @note For regular, non-page prefs items, refer to #Elm_Prefs_Item_Iface.
*
* @since 1.8
*/
struct _Elm_Prefs_Page_Iface
{
#define ELM_PREFS_PAGE_IFACE_ABI_VERSION (1)
unsigned int abi_version; /**< always use:
* - #ELM_PREFS_PAGE_IFACE_ABI_VERSION to declare.
* - elm_prefs_widget_iface_abi_version_get() to check.
*/
Evas_Object * (*add)(const Elm_Prefs_Page_Iface * iface,
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. */
Eina_Bool (*title_set)(Evas_Object *obj,
const char *title); /**< function to set a title on the page widget */
Eina_Bool (*sub_title_set)(Evas_Object *obj,
const char *sub_title); /**< function to set a sub-title on the page widget */
Eina_Bool (*icon_set)(Evas_Object *obj,
const char *icon); /**< function to set an icon on the page widget */
Eina_Bool (*item_pack)(Evas_Object *obj,
Evas_Object *it,
const Elm_Prefs_Item_Type type,
const Elm_Prefs_Item_Iface *iface); /**< function to pack an item (widget) on the page widget */
Eina_Bool (*item_unpack)(Evas_Object *obj,
Evas_Object *it); /**< function to unpack an item (widget) on the page widget */
Eina_Bool (*item_pack_before)(Evas_Object *obj,
Evas_Object *it,
Evas_Object *it_before,
const Elm_Prefs_Item_Type type,
const Elm_Prefs_Item_Iface *iface); /**< function to pack an item (widget) on the page widget, before a pre-existing, referential, packed one */
Eina_Bool (*item_pack_after)(Evas_Object *obj,
Evas_Object *it,
Evas_Object *it_after, /**< function to pack an item (widget) on the page widget, after a pre-existing, referential, packed one */
const Elm_Prefs_Item_Type type,
const Elm_Prefs_Item_Iface *iface);
};
/**
* Mass-register widgets implementing prefs @b pages interfaces.
*
* @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
* terminated.
*
* This will register all page interfaces declared on @a array in
* Elementary, so that the prefs widget will recognize them on @c .epc
* files @c 'widget:' (page) declarations.
*
* @see elm_prefs_page_iface_unregister()
*
* @since 1.8
*/
EAPI void elm_prefs_page_iface_register(const Elm_Prefs_Page_Iface_Info *array);
/**
* Mass-unregister widgets implementing prefs @b pages interfaces.
*
* @param array An array of #Elm_Prefs_Iface_Info structs, @c NULL
* terminated.
*
* This will unregister all page interfaces declared on @a array in
* Elementary, given they had been previously registered.
*
* @see elm_prefs_page_iface_register() for more details
*
* @since 1.8
*/
EAPI void elm_prefs_page_iface_unregister(const Elm_Prefs_Page_Iface_Info *array);
EAPI Eina_Bool elm_prefs_page_widget_common_add(Evas_Object *prefs,
Evas_Object *obj);
/**
* @}
*/
#endif