hugok
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

efl_model_base: convert docs

This commit is contained in:
Daniel Kolesa 2015-06-18 11:01:12 +01:00
parent bc4e4a69f8
commit c93de19e22
1 changed files with 158 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

336
src/lib/efl/interfaces/efl_model_base.eo
View File

@ -30,129 +30,85 @@ interface Efl.Model.Base ()
methods {
@property load_status {
get {
/*@
Get a load emodel current status.
[[Get a load emodel current status.
@return: @c Efl_Model_Load_Status
By convention this means get the current model status.
Possible values are defined Efl_Model_Load_Status enumerator.
By convention this means get the current model status.
Possible values are defined Efl_Model_Load_Status enumerator.
See also @Efl_Model_Load_Status, @efl_model_load
@see Efl_Model_Load_Status
@see efl_model_load
@since 1.14 */
return: Efl.Model.Load_Status;
@since 1.14
]]
return: Efl.Model.Load_Status;
}
}
@property properties {
get {
/*@
Get properties from model.
[[Get properties from model.
@return: @c Efl_Model_Load_Status
properties_get is due to provide callers a way the fetch the
current properties implemented/used by the model. The event
EFL_MODEL_EVENT_PROPERTIES_CHANGE will be raised to notify
listeners of any modifications in the properties.
properties_get is due to provide callers a way the fetch the current
properties implemented/used by the model.
The event EFL_MODEL_EVENT_PROPERTIES_CHANGE will be raised to notify listeners
of any modifications in the properties.
See also @EFL_MODEL_EVENT_PROPERTIES_CHANGE.
@see EFL_MODEL_EVENT_PROPERTIES_CHANGE
@since 1.14 */
return: Efl.Model.Load_Status;
@since 1.14
]]
return: Efl.Model.Load_Status;
}
values {
properties: const(array<const(char*)>*); /*@ array of current properties */
properties: const(array<const(char*)>*); [[array of current properties]]
}
}
@property property {
set {
/*@
Set a property value of a given property name.
[[Set a property value of a given property name.
@return: @c EINA_TRUE, on success, @c EINA_FALSE in readonly property or error
The caller must ensure to call at least efl_model_prop_list
before being able to see/set properties. This function sets
a new property value into given property name. Once the
operation is completed the concrete implementation should
raise EFL_MODEL_EVENT_PROPERTIES_CHANGE event in order to
notify listeners of the new value of the property.
The caller must ensure to call at least efl_model_prop_list before being
able to see/set properties.
This function sets a new property value into given property name. Once
the operation is completed the concrete implementation should raise
EFL_MODEL_EVENT_PROPERTIES_CHANGE event in order to notify listeners of the
new value of the property.
If the model doesn't have the property then there are two
possibilities, either raise an error or create the new
property in model
If the model doesn't have the property then there are two possibilities,
either raise an error or create the new property in model
See @efl_model_property_get, @EFL_MODEL_EVENT_PROPERTIES_CHANGE
@see efl_model_property_get
@see EFL_MODEL_EVENT_PROPERTIES_CHANGE
@since 1.14 */
return: Efl.Model.Load_Status;
@since 1.14
]]
return: Efl.Model.Load_Status;
}
get {
/*@
Retrieve the value of a given property name.
[[Retrieve the value of a given property name.
@return: @c Load Status, on success, @c EFL_MODEL_LOAD_STATUS_ERROR otherwise
property_get will only be available when load status is equal
to EFL_MODEL_LOAD_STATUS_LOADED.
property_get will only be available when load status is equal to
EFL_MODEL_LOAD_STATUS_LOADED.
At this point the caller is free to get values from properties.
The event EFL_MODEL_EVENT_PROPERTIES_CHANGE may be raised to
notify listeners of the property/value.
At this point the caller is free to get values from properties.
The event EFL_MODEL_EVENT_PROPERTIES_CHANGE may be raised to notify
listeners of the property/value.
See @efl_model_properties_get, @EFL_MODEL_EVENT_PROPERTIES_CHANGE
@see efl_model_properties_get
@see EFL_MODEL_EVENT_PROPERTIES_CHANGE
@since 1.14 */
return: Efl.Model.Load_Status;
@since 1.14
]]
return: Efl.Model.Load_Status;
}
keys {
property: const(char)*; /*@ Property name */
property: const(char)*; [[Property name]]
}
values {
value: const(generic_value)*; /*@ New value */
value: const(generic_value)*; [[New value]]
}
}
@property children_slice {
get {
/*@
Get children slice OR full range.
@return: @c Efl_Model_Load_Status. See below for more info.
Before being able to get the children list the model status must be
on loaded status (EFL_MODEL_LOAD_STATUS_LOADED).
However there may be circunstancies where the model could be
in a different state, in such cases it is advisable
to simply return: its current state, which will be
of course, different than @c EFL_MODEL_LOAD_STATUS_LOADED_CHILDREN.
When children accessor is return:ed as NULL one should then
test the current load status return:ed by @children_slice_get
in order to check against an empty list or real error.
children_slice_get behaves in two different ways, it may provide
the slice if both @c start AND @c count are non-zero OR full range otherwise.
The return:ed Eina_Accessor must be freed when it is no longer needed and
eo_unref() must be invoked for children if caller wants a copy.
Since 'slice' is a range, for example if we have 20 childs a slice could be
the range from 3(start) to 4(count), see:
child 0 [no]
child 1 [no]
child 2 [yes]
child 3 [yes]
child 4 [yes]
child 5 [yes]
child 6 [no]
child 7 [no]
Optionally the user can call children_count_get to know
the number of children so a valid range can be known in advance.
Below are examples of both usage types: slices and full ranges.
/* doc FIXME: example
Below are examples of both usage types: slices and full ranges.
@code
// Returns full list
@ -162,18 +118,55 @@ interface Efl.Model.Base ()
eo_do(obj, efl_model_children_slice_get(5, 5, &children_accessor));
@endcode
*/
[[Get children slice OR full range.
@see efl_model_children_get
@see efl_model_children_count_get
@see efl_model_load
@see efl_model_load_status_get
@since 1.14 */
Before being able to get the children list the model status
must be on loaded status (EFL_MODEL_LOAD_STATUS_LOADED).
However there may be circunstancies where the model could be
in a different state, in such cases it is advisable to simply
return: its current state, which will be of course, different
than EFL_MODEL_LOAD_STATUS_LOADED_CHILDREN.
When children accessor is returned as NULL one should then
test the current load status return:ed by @children_slice_get
in order to check against an empty list or real error.
children_slice_get behaves in two different ways, it may
provide the slice if both @c start AND @c count are non-zero
OR full range otherwise.
The return:ed Eina_Accessor must be freed when it is no longer
needed and eo_unref() must be invoked for children if caller
wants a copy.
Since 'slice' is a range, for example if we have 20 childs a
slice could be the range from 3(start) to 4(count), see:
child 0 [no]
child 1 [no]
child 2 [yes]
child 3 [yes]
child 4 [yes]
child 5 [yes]
child 6 [no]
child 7 [no]
Optionally the user can call children_count_get to know the
number of children so a valid range can be known in advance.
See @efl_model_children_get, @efl_model_children_count_get,
@efl_model_load, @efl_model_load_status_get
@since 1.14
]]
return: Efl.Model.Load_Status;
}
keys {
start: uint; /*@ Range begin - start from here. If start and count are 0 slice is ignored.*/
count: uint; /*@ Range size. If count and start are 0 slice is ignored.*/
start: uint; [[Range begin - start from here. If start and
count are 0 slice is ignored.]]
count: uint; [[Range size. If count and start are 0 slice is
ignored.]]
}
values {
children_accessor: accessor<list<Eo.Base*>*>*;
@ -181,22 +174,19 @@ interface Efl.Model.Base ()
}
@property children_count {
get {
/*@
Get children count.
[[Get children count.
@return: @c EINA_TRUE, on success, @c EINA_FALSE otherwise
When efl_model_load is completed efl_model_coildren_count_get
can be use to get the number of children. children_count_get
can also be used before calling children_slice_get so a valid
range is known. Event EFL_MODEL_CHILDREN_COUNT_CHANGED is
emitted when count is finished.
When efl_model_load is completed efl_model_coildren_count_get can be use
to get the number of children. children_count_get can also be used
before calling children_slice_get so a valid range is known.
Event EFL_MODEL_CHILDREN_COUNT_CHANGED is emitted when count is finished.
@see efl_model_children_get
@see efl_model_children_slice_get
@see efl_model_load
@see efl_model_load_status_get
@since 1.14 */
See also @efl_model_children_get, @efl_model_children_slice_get,
@efl_model_load, @efl_model_load_status_get.
@since 1.14
]]
return: Efl.Model.Load_Status;
}
values {
@ -204,108 +194,98 @@ interface Efl.Model.Base ()
}
}
load {
/*@
Load emodel.
[[Load emodel.
By convention this means loading data from an external source and populating
the models properties and children with it. For example in the case of file
system backed model, this means opening the relevant files and reading the
data from them(creating the properties and children from it).
the model emit EFL_MODEL_EVENT_LOAD_STATUS after end with Efl_Model_Load_Status
@warning This convention should be followed, but no guarantees of behaviour
By convention this means loading data from an external source and
populating the models properties and children with it. For example
in the case of file system backed model, this means opening the
relevant files and reading the data from them(creating the
properties and children from it). the model emit
EFL_MODEL_EVENT_LOAD_STATUS after end with Efl_Model_Load_Status
This convention should be followed, but no guarantees of behaviour
by user defined types can be given.
Alternatively is possible to use properties_load to load only properties
and children_load to load only children. If efl_model_load is called then
calling properties_load and/or children_load is not necessary.
Alternatively is possible to use properties_load to load only
properties and children_load to load only children. If
efl_model_load is called then calling properties_load
and/or children_load is not necessary.
@see Efl_Model_Load_Status
@see efl_model_properties_load
@see efl_model_children_load
@see efl_model_unload
@see efl_model_load_status_get
See also @Efl_Model_Load_Status, @efl_model_properties_load,
@efl_model_children_load, @efl_model_unload,
@efl_model_load_status_get
@since 1.14 */
@since 1.14
]]
}
unload {
/*@
Unload emodel.
[[Unload emodel.
By convention this means releasing data received/read from an external source. For
example of a database backed model this might mean releasing the iterator for
the currently loaded data or deleting a temporary table.
the model emit EFL_MODEL_EVENT_LOAD_STATUS after end with model load status
@warning This convention should be followed, but no guarantees of behaviour
By convention this means releasing data received/read from an
external source. For example of a database backed model this
might mean releasing the iterator for the currently loaded data
or deleting a temporary table. the model emit
EFL_MODEL_EVENT_LOAD_STATUS after end with model load status
This convention should be followed, but no guarantees of behaviour
by user defined types can be given.
@see Efl_Model_Load_Status
@see efl_model_load
@see efl_model_load_status_get
See also @Efl_Model_Load_Status, @efl_model_load,
@efl_model_load_status_get
@since 1.14 */
@since 1.14
]]
}
properties_load {
/*@
Properties emodel load.
[[Properties emodel load.
By convention this means loading data from an external source and populating
the models properties only. This method is a subset of efl_model_load, meaning that
it won't load children, it is a hint.
For loadind both properties and children use efl_model_load
instead.
By convention this means loading data from an external source and
populating the models properties only. This method is a subset
of @efl_model_load, meaning that it won't load children, it is
a hint. For loadind both properties and children use
efl_model_load instead.
@see efl_model_load
@since 1.14 */
@since 1.14
]]
}
children_load {
/*@
Children emodel load.
[[Children emodel load.
By convention this means loading data from an external source and populating
the models children only. This method is a subset of efl_model_load, meaning that
it won't load properties. For loadind both properties and children use efl_model_load
instead.
By convention this means loading data from an external source and
populating the models children only. This method is a subset of
@efl_model_load, meaning that it won't load properties. For
loadind both properties and children use efl_model_load instead.
@see efl_model_load
@since 1.14 */
@since 1.14
]]
}
child_add {
/*@
Add a new child.
@return: @c Emodel* on success, @c NULL otherwise
[[Add a new child.
Add a new child, possibly dummy, depending on the implementation,
of a internal keeping. When the child is effectively
added the event EFL_MODEL_EVENT_CHILD_ADD is then raised and the new child
is kept along with other children.
added the event @EFL_MODEL_EVENT_CHILD_ADD is then raised and the
new child is kept along with other children.
@see EFL_MODEL_EVENT_CHILD_ADD
@see load_status_get
@since 1.14 */
See also @load_status_get.
@since 1.14
]]
return: Eo.Base *;
}
child_del {
/*@
Remove a child.
@return: @c Efl_Model_Load_Status on success, @c EFL_MODEL_LOAD_STATUS_ERROR otherwise.
[[Remove a child.
Remove a child of a internal keeping. When the child is effectively
removed the event EFL_MODEL_EVENT_CHILD_REMOVED is then raised to give a
chance for listeners to perform any cleanup and/or update references.
@see EFL_MODEL_EVENT_CHILD_REMOVED
@since 1.14 */
return: Efl.Model.Load_Status;
removed the event @EFL_MODEL_EVENT_CHILD_REMOVED is then raised to
give a chance for listeners to perform any cleanup and/or update
references.
@since 1.14
]]
return: Efl.Model.Load_Status;
params {
@in child: Eo.Base*; /*@ Child to be removed */
@in child: Eo.Base*; [[Child to be removed]]
}
}
}