tasn pushed a commit to branch master.
http://git.enlightenment.org/core/elementary.git/commit/?id=3816942bf7830bd2fb431b1498b53f9ed5946c77
commit 3816942bf7830bd2fb431b1498b53f9ed5946c77
Author: Tom Hacohen <t...@stosb.com>
Date: Mon Aug 10 15:00:27 2015 +0100
Prefs: migrate docs.
---
src/lib/elm_prefs.eo | 323 +++++++++++++++++----------------------------------
1 file changed, 109 insertions(+), 214 deletions(-)
diff --git a/src/lib/elm_prefs.eo b/src/lib/elm_prefs.eo
index 1a2f4ba..fa507a9 100644
--- a/src/lib/elm_prefs.eo
+++ b/src/lib/elm_prefs.eo
@@ -3,309 +3,204 @@ class Elm.Prefs (Elm.Widget, Efl.File)
eo_prefix: elm_obj_prefs;
methods {
@property data {
+ [[Set user data for a given prefs widget
+
+ 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 $prefs_data with keys matching the ones
+ present on the file passed on elm_prefs_file_set() to $obj will
+ have their values applied to the respective UI elements of the
+ widget.
+
+ When $obj dies, the values of the elements declared on its
+ .epb file (the one set on elm_prefs_file_set()) marked as permanent
+ will be written back to 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: $obj will keep a reference of its own for $prefs_data,
+ but you should still unreference it by yourself, after the widget
+ is gone.
+
+ @since 1.8]]
set {
- /*@
- Set user data for a given prefs widget
-
- @return $true, on success, $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 <b>prefs data</b> 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
- <b>will be written back</b> 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: bool;
+ return: bool; [[$true, on success, $false otherwise]]
}
get {
- /*@
- Get user data for a given prefs widget
-
- @return A pointer to the user data of a given prefs widget on
success.
- $NULL otherwise.
-
- @see elm_prefs_data_set() for more details
-
- @since 1.8 */
}
values {
- data: Elm_Prefs_Data * @nullable; /*@ A valid prefs_data handle */
+ data: Elm_Prefs_Data * @nullable; [[A valid prefs_data handle]]
}
}
@property autosave {
+ [[Control whether a given prefs widget should save its values back (on
+ the user data file, if set) automatically on every UI element
+ changes.
+
+ If $autosave is $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 $prefs, naturally nothing
+ will happen.
+
+ @since 1.8]]
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 $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 $true if @a prefs is saving automatically,
- $false otherwise.
-
- @see elm_prefs_autosave_set(), for more details
-
- @since 1.8 */
}
values {
- autosave: bool; /*@ $true to save automatically, $false
- otherwise. */
+ autosave: bool; [[$true to save automatically, $false otherwise.]]
}
}
reset {
- /*@
- Reset the values of a given prefs widget to a previous state.
+ [[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 $.epb file it is bound
- to) or to reset to the state they were before the last modification
- it got.
+ As can be seen on #Elm_Prefs_Reset_Mode, there are two possible
+ actions to be taken by this call -- either to reset $prefs'
+ values to the defaults (declared on the $.epb file it is bound
+ to) or to reset to the state they were before the last modification
+ it got.
- @since 1.8 */
+ @since 1.8]]
params {
- @in mode: Elm_Prefs_Reset_Mode; /*@ The reset mode to apply on @a
prefs */
+ @in mode: Elm_Prefs_Reset_Mode; [[The reset mode to apply on
$prefs]]
}
}
item_value_set {
- /*@
- Set the value on a given prefs widget's item.
-
- @return $true, on success, $false otherwise
+ [[Set the value on a given prefs widget's item.
- This will change the value of item named @a name programatically.
+ This will change the value of item named $name programatically.
- @see elm_prefs_item_value_get()
+ @since 1.8]]
- @since 1.8 */
-
- return: bool;
+ return: bool; [[$true, on success, $false otherwise]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) */
- @in value: const(Eina_Value)*; /*@ The value to set on the item.
It should be typed as
- the item expects, preferably, or a conversion will
- take place */
+ @in name: const(char)*; [[The name of the item (as declared in the
prefs collection)]]
+ @in value: const(Eina_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 @const {
- /*@
- Get the value of a given prefs widget's item.
-
- @return $true, on success, $false otherwise
+ [[Get the value of a given prefs widget's item.
- This will retrieve the value of item named @a name.
+ This will retrieve the value of item named $name.
- @see elm_prefs_item_value_set()
+ @since 1.8]]
+ return: bool; [[$true, on success, $false otherwise]]
- @since 1.8 */
- return: bool;
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to get value from */
- @out value: Eina_Value; /*@ Where to store the value of the item.
It will be
- overwritten and setup with the type the item
- is bound to */
+ @in name: const(char)*; [[The name of the item (as declared in the
prefs collection) to get value from]]
+ @out value: Eina_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 {
- /*@
- Get the Elementary widget bound to a given prefs widget's
- item.
+ [[Get the Elementary widget bound to a given prefs widget's item.
- @return A valid widget handle, on success, or $NULL, otherwise
+ This will retrieve a handle to the real widget implementing a given
+ item of $prefs, <b>for read-only</b> actions.
- This will retrieve a handle to the real widget implementing a given
- item of @a prefs, <b>for read-only</b> actions.
+ Warning: You should never modify the state of the returned
+ widget, because it's meant to be managed by $prefs, solely.
- @warning You should @b never modify the state of the returned
- widget, because it's meant to be managed by @a prefs, solely.
+ @since 1.8]]
- @see elm_prefs_item_value_set()
-
- @since 1.8 */
-
- return: const(Evas.Object)*;
+ return: const(Evas.Object)*; [[A valid widget handle, on success, or
$NULL, otherwise]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to get object from */
+ @in name: const(char)*; [[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.
+ [[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 */
+ @since 1.8]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to act on */
- @in disabled: bool; /*@ $true, to make it disabled, $false
- otherwise */
+ @in name: const(char)*; [[The name of the item (as declared in the
prefs collection) to act on]]
+ @in disabled: bool; [[$true, to make it disabled, $false
otherwise]]
}
}
item_disabled_get @const {
- /*@
- Get whether the widget bound to a given prefs widget's item is
- disabled or not.
-
- @return $true, if it is disabled, $false
- otherwise
+ [[Get whether the widget bound to a given prefs widget's item is
disabled or not.
- @see elm_prefs_item_disabled_set()
-
- @since 1.8 */
- return: bool;
+ @since 1.8]]
+ return: bool; [[$true, if it is disabled, $false otherwise]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to get disabled state from */
+ @in name: const(char)*; [[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 $true, on success, $false otherwise
+ [["Swallows" an object into a SWALLOW item of a prefs widget.
- @see elm_prefs_item_swallow() for more details
+ @since 1.8]]
- @since 1.8 */
-
- return: bool;
+ return: bool; [[$true, on success, $false otherwise]]
params {
- @in name: const(char)*; /*@ the name of the SWALLOW item (as
declared in the prefs
- collection) */
- @in child: Evas.Object *; /*@ The object to occupy the item */
+ @in name: const(char)*; [[the name of the SWALLOW item (as
declared in the prefs collection)]]
+ @in child: Evas.Object *; [[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 $TEXT or $TEXTAREA items' default widgets implement
- the 'editable' property. Custom registered widgets may as well
- implement them.
+ [[Set whether the widget bound to a given prefs widget's item is
editable or not.
- @see elm_prefs_item_editable_get()
+ Note: Only $TEXT or $TEXTAREA items' default widgets implement
+ the 'editable' property. Custom registered widgets may as well
+ implement them.
- @since 1.8 */
+ @since 1.8]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to act on */
- @in editable: bool; /*@ $true, to make it editable, $false
- otherwise */
+ @in name: const(char)*; [[The name of the item (as declared in the
prefs collection) to act on]]
+ @in editable: bool; [[$true, to make it editable, $false
otherwise]]
}
}
item_editable_get @const {
- /*@
- Get whether the widget bound to a given prefs widget's item is
- editable or not.
+ [[Get whether the widget bound to a given prefs widget's item is
editable or not.
- @return $true, if it is editable, $false
- otherwise
-
- @see elm_prefs_item_editable_set() for more details
-
- @since 1.8 */
- return: bool;
+ @since 1.8]]
+ return: bool; [[$true, if it is editable, $false otherwise]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to get editable state from */
+ @in name: const(char)*; [[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
+ [[Unswallow an object from a SWALLOW item of a prefs widget.
- @since 1.8 */
+ @since 1.8]]
- return: Evas.Object *;
+ return: Evas.Object *; [[The unswallowed object, or NULL on errors]]
params {
- @in name: const(char)*; /*@ the name of the SWALLOW item (as
declared in the prefs
- collection) */
+ @in name: const(char)*; [[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.
+ [[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 $.epb @a prefs it was loaded with. By this call one may alter
- that state, programatically.
+ Each prefs item may have a default visibility state, declared on
+ the $.epb $prefs it was loaded with. By this call one may alter
+ that state, programatically.
- @see elm_prefs_item_visible_get()
-
- @since 1.8 */
+ @since 1.8]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to change visibility of */
- @in visible: bool; /*@ $true, to make it visible, $false
- otherwise */
+ @in name: const(char)*; [[The name of the item (as declared in the
prefs collection) to change visibility of]]
+ @in visible: bool; [[$true, to make it visible, $false otherwise]]
}
}
item_visible_get @const {
- /*@
- Get whether the widget bound to a given prefs widget's item is
- visible or not.
-
- @return $true, if it is visible, $false
- otherwise
-
- @see elm_prefs_item_visible_set() for more details
+ [[Get whether the widget bound to a given prefs widget's item is
visible or not.
- @since 1.8 */
- return: bool;
+ @since 1.8]]
+ return: bool; [[$true, if it is visible, $false otherwise]]
params {
- @in name: const(char)*; /*@ The name of the item (as declared in
the prefs
- collection) to get visibility state from */
+ @in name: const(char)*; [[The name of the item (as declared in the
prefs collection) to get visibility state from]]
}
}
}
--
