From f5479c104d4817d799d2db414a88c607fa68060f Mon Sep 17 00:00:00 2001 From: Daniel Zaoui Date: Tue, 25 Mar 2014 14:27:37 +0200 Subject: Eolian: Integration of Prefs --- src/lib/elm_prefs.eo | 388 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 388 insertions(+) create mode 100644 src/lib/elm_prefs.eo (limited to 'src/lib/elm_prefs.eo') diff --git a/src/lib/elm_prefs.eo b/src/lib/elm_prefs.eo new file mode 100644 index 000000000..6be7d85e1 --- /dev/null +++ b/src/lib/elm_prefs.eo @@ -0,0 +1,388 @@ +class Elm_Prefs (Elm_Widget) +{ + eo_prefix: elm_obj_prefs; + properties { + data { + set { + /*@ + Set user data for a given prefs widget + + @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_get() + + @since 1.8 */ + return Eina_Bool; + } + get { + /*@ + Retrieve user data for a given prefs widget + + @return A pointer to the user data of a given prefs widget on success. + @c NULL otherwise. + + @see elm_prefs_data_set() for more details + + @since 1.8 */ + } + values { + Elm_Prefs_Data *data; /*@ A valid prefs_data handle */ + } + } + file { + set { + /*@ + Set file and page to populate a given prefs widget's interface. + + @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 */ + return Eina_Bool; + } + get { + /*@ + Retrieve file and page bound to a given prefs widget. + + @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 */ + return Eina_Bool; + } + values { + const char *file; /*@ The @b .epb (binary) file to get contents from */ + const char *page; /*@ The page, inside @a file, where to get item contents from */ + } + } + 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. + + 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 */ + } + get { + /*@ + Get whether a given prefs widget is saving its values back + automatically on changes. + + @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 */ + } + values { + Eina_Bool autosave; /*@ @c EINA_TRUE to save automatically, @c EINA_FALSE + otherwise. */ + } + } + } + methods { + reset { + /*@ + Reset the values of a given prefs widget to a previous state. + + 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 */ + + params { + @in Elm_Prefs_Reset_Mode mode; /*@ The reset mode to apply on @a prefs */ + } + } + item_value_set { + /*@ + Set the value on a given prefs widget's item. + + @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 */ + + return Eina_Bool; + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) */ + @in const Eina_Value *value; /*@ The value to set on the item. It should be typed as + the item expects, preferably, or a conversion will + take place */ + } + } + item_value_get { + /*@ + Retrieve the value of a given prefs widget's item. + + @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 */ + + const; + return Eina_Bool; + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to get value from */ + @out Eina_Value value; /*@ Where to store the value of the item. It will be + overwritten and setup with the type the item + is bound to */ + } + } + item_object_get { + /*@ + Retrieve the Elementary widget bound to a given prefs widget's + item. + + @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 */ + + return const Evas_Object *; + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to get object from */ + } + } + item_disabled_set { + /*@ + Set whether the widget bound to a given prefs widget's item is + disabled or not. + + @see elm_prefs_item_disabled_get() + + @since 1.8 */ + + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to act on */ + @in Eina_Bool disabled; /*@ @c EINA_TRUE, to make it disabled, @c EINA_FALSE + otherwise */ + } + } + item_disabled_get { + /*@ + Retrieve whether the widget bound to a given prefs widget's item is + disabled or not. + + @return @c EINA_TRUE, if it is disabled, @c EINA_FALSE + otherwise + + @see elm_prefs_item_disabled_set() + + @since 1.8 */ + + const; + return Eina_Bool; + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to get disabled state from */ + } + } + item_swallow { + /*@ + "Swallows" an object into a SWALLOW item of a prefs widget. + + @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise + + @see elm_prefs_item_swallow() for more details + + @since 1.8 */ + + return Eina_Bool; + params { + @in const char *name; /*@ the name of the SWALLOW item (as declared in the prefs + collection) */ + @in Evas_Object *child; /*@ The object to occupy the item */ + } + } + item_editable_set { + /*@ + Set whether the widget bound to a given prefs widget's item is + editable or not. + + @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 */ + + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to act on */ + @in Eina_Bool editable; /*@ @c EINA_TRUE, to make it editable, @c EINA_FALSE + otherwise */ + } + } + item_editable_get { + /*@ + Retrieve whether the widget bound to a given prefs widget's item is + editable or not. + + @return @c EINA_TRUE, if it is editable, @c EINA_FALSE + otherwise + + @see elm_prefs_item_editable_set() for more details + + @since 1.8 */ + + const; + return Eina_Bool; + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to get editable state from */ + } + } + item_unswallow { + /*@ + Unswallow an object from a SWALLOW item of a prefs widget. + + @return The unswallowed object, or NULL on errors + + @see elm_prefs_item_unswallow() for more details + + @since 1.8 */ + + return Evas_Object *; + params { + @in const char *name; /*@ the name of the SWALLOW item (as declared in the prefs + collection) */ + } + } + item_visible_set { + /*@ + Set whether the widget bound to given prefs widget's item should be + visible or not. + + 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 */ + + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to change visibility of */ + @in Eina_Bool visible; /*@ @c EINA_TRUE, to make it visible, @c EINA_FALSE + otherwise */ + } + } + item_visible_get { + /*@ + Retrieve whether the widget bound to a given prefs widget's item is + visible or not. + + @return @c EINA_TRUE, if it is visible, @c EINA_FALSE + otherwise + + @see elm_prefs_item_visible_set() for more details + + @since 1.8 */ + + const; + return Eina_Bool; + params { + @in const char *name; /*@ The name of the item (as declared in the prefs + collection) to get visibility state from */ + } + } + } + implements { + class::constructor; + Eo_Base::constructor; + Evas_Smart::del; + Evas_Smart::add; + Elm_Widget::focus_next; + } + events { + page,changed; /*@ s */ + page,saved; /*@ s */ + page,reset; /*@ s */ + page,loaded; /*@ s */ + item,changed; /*@ s */ + action; /*@ ss */ + } + +} -- cgit v1.2.1