forked from enlightenment/efl
More documentation for eina_model.
Patch by: "Jonas M. Gastal" <jgastal@profusion.mobi> SVN revision: 67797
This commit is contained in:
parent
0bcae96ccb
commit
9f90af4dc7
|
@ -37,7 +37,9 @@ SRCS = \
|
||||||
eina_inlist_03.c \
|
eina_inlist_03.c \
|
||||||
eina_str_01.c \
|
eina_str_01.c \
|
||||||
eina_strbuf_01.c \
|
eina_strbuf_01.c \
|
||||||
eina_tiler_01.c
|
eina_tiler_01.c \
|
||||||
|
eina_model_01.c \
|
||||||
|
eina_model_02.c
|
||||||
|
|
||||||
examples_PROGRAMS =
|
examples_PROGRAMS =
|
||||||
|
|
||||||
|
@ -73,7 +75,9 @@ examples_PROGRAMS += \
|
||||||
eina_inlist_02 \
|
eina_inlist_02 \
|
||||||
eina_inlist_03 \
|
eina_inlist_03 \
|
||||||
eina_str_01 \
|
eina_str_01 \
|
||||||
eina_strbuf_01
|
eina_strbuf_01 \
|
||||||
|
eina_model_01 \
|
||||||
|
eina_model_02
|
||||||
|
|
||||||
if BUILD_TILER_EXAMPLE
|
if BUILD_TILER_EXAMPLE
|
||||||
AM_CPPFLAGS += @ECORE_EVAS_CFLAGS@
|
AM_CPPFLAGS += @ECORE_EVAS_CFLAGS@
|
||||||
|
|
|
@ -0,0 +1,57 @@
|
||||||
|
#include <Eina.h>
|
||||||
|
|
||||||
|
static void _cb_on_deleted(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info);
|
||||||
|
|
||||||
|
int main(void)
|
||||||
|
{
|
||||||
|
Eina_Model *m;
|
||||||
|
char *s;
|
||||||
|
int i;
|
||||||
|
|
||||||
|
eina_init();
|
||||||
|
|
||||||
|
m = eina_model_new(EINA_MODEL_TYPE_GENERIC);
|
||||||
|
|
||||||
|
eina_model_event_callback_add(m, "deleted", _cb_on_deleted, NULL);
|
||||||
|
|
||||||
|
//Adding properties to model
|
||||||
|
for (i = 0; i < 5; i++)
|
||||||
|
{
|
||||||
|
Eina_Value val;
|
||||||
|
char name[2] = {'a'+ i, 0};
|
||||||
|
eina_value_setup(&val, EINA_VALUE_TYPE_INT);
|
||||||
|
eina_value_set(&val, i);
|
||||||
|
eina_model_property_set(m, name, &val);
|
||||||
|
eina_value_flush(&val);
|
||||||
|
}
|
||||||
|
|
||||||
|
//Adding children to model
|
||||||
|
for (i = 0; i < 5; i++)
|
||||||
|
{
|
||||||
|
Eina_Value val;
|
||||||
|
Eina_Model *c = eina_model_new(EINA_MODEL_TYPE_GENERIC);
|
||||||
|
eina_value_setup(&val, EINA_VALUE_TYPE_INT);
|
||||||
|
eina_value_set(&val, i);
|
||||||
|
eina_model_property_set(c, "x", &val);
|
||||||
|
|
||||||
|
eina_model_event_callback_add(c, "deleted", _cb_on_deleted, NULL);
|
||||||
|
|
||||||
|
eina_model_child_append(m, c);
|
||||||
|
//Now that the child has been appended to a model, it's parent will manage it's lifecycle
|
||||||
|
eina_model_unref(c);
|
||||||
|
eina_value_flush(&val);
|
||||||
|
}
|
||||||
|
|
||||||
|
s = eina_model_to_string(m);
|
||||||
|
printf("model as string:\n%s\n", s);
|
||||||
|
|
||||||
|
free(s);
|
||||||
|
eina_model_unref(m);
|
||||||
|
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
static void _cb_on_deleted(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info)
|
||||||
|
{
|
||||||
|
printf("deleted %p\n", model);
|
||||||
|
}
|
|
@ -72,6 +72,7 @@
|
||||||
* @li @ref Eina_Stringshare_Group saves memory by sharing read-only string references.
|
* @li @ref Eina_Stringshare_Group saves memory by sharing read-only string references.
|
||||||
* @li @ref Eina_Tiler_Group split, merge and navigates into 2D tiled regions.
|
* @li @ref Eina_Tiler_Group split, merge and navigates into 2D tiled regions.
|
||||||
* @li @ref Eina_Trash_Group container of unused but allocated data.
|
* @li @ref Eina_Trash_Group container of unused but allocated data.
|
||||||
|
* @li @ref Eina_Model_Group container for data with user defined hierarchy/structure.
|
||||||
*
|
*
|
||||||
* The tools that are available are (see @ref Eina_Tools_Group):
|
* The tools that are available are (see @ref Eina_Tools_Group):
|
||||||
* @li @ref Eina_Benchmark_Group helper to write benchmarks.
|
* @li @ref Eina_Benchmark_Group helper to write benchmarks.
|
||||||
|
|
|
@ -28,6 +28,91 @@
|
||||||
* @include eina_model_01.c
|
* @include eina_model_01.c
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @page eina_model_02_example_page Creating a simple model
|
||||||
|
* @dontinclude eina_model_02.c
|
||||||
|
*
|
||||||
|
* This example shows the creation of a model with five properties, named:
|
||||||
|
* 'a', 'b', 'c', 'd' and 'e' with values 0, 1, 2, 3 and 4
|
||||||
|
* respectively. In addition to the 5 properties our model also add 5 children,
|
||||||
|
* and to each child we give a property named 'x' with a value of 1, 2, 3, 4 and
|
||||||
|
* 5.
|
||||||
|
*
|
||||||
|
* In other words this piece of code shows how to use eina_model to store a list
|
||||||
|
* of elements, given that the list itself has some properties.
|
||||||
|
*
|
||||||
|
* Now let's walk through the code and examine the interesting bits.
|
||||||
|
*
|
||||||
|
* This is some pretty standard initialization code.
|
||||||
|
* @until eina_init
|
||||||
|
*
|
||||||
|
* We now create our eina_model, the important detail here is the type of the
|
||||||
|
* model being created, for this example we use the generic type provided by
|
||||||
|
* eina:
|
||||||
|
* @until model_new
|
||||||
|
*
|
||||||
|
* Once our model has been created we can add callbacks to be notified of events
|
||||||
|
* that happen to our model, for this example we are just going to add a
|
||||||
|
* callback for the "delete" event. To get a list of events a given eina model
|
||||||
|
* can emit see @ref eina_model_event_names_list_get().
|
||||||
|
* @until callback_add
|
||||||
|
*
|
||||||
|
* Once we have a model, we need to populate it with information. There are two
|
||||||
|
* types of information we can store on an eina model: properties and eina
|
||||||
|
* models. We are going to start by looking at properties.
|
||||||
|
*
|
||||||
|
* Properties are, simply put, named values. They have a char* identifier and an
|
||||||
|
* Eina_Value value. This means you can store in a property almost any type of
|
||||||
|
* data. For this example we are going to add some very simple numeric
|
||||||
|
* properties which will have single letter identifiers.
|
||||||
|
* @until }
|
||||||
|
* @until }
|
||||||
|
*
|
||||||
|
* Despite being able to store almost any value properties the least flexible
|
||||||
|
* information unit we can put in an eina model. We can add eina models to our
|
||||||
|
* eina model, this allows us to represt complex information hierarchies. This
|
||||||
|
* example adds 5 models(with no children of their own) to our parent model @c
|
||||||
|
* m.
|
||||||
|
* @until }
|
||||||
|
* The code here should be pretty easy to understand, we create a model, much
|
||||||
|
* like we did before, and we then add a property to our model, again a task we
|
||||||
|
* have already done.
|
||||||
|
*
|
||||||
|
* The important issue to note here is that we could have given each of our @c c
|
||||||
|
* child models as complex an structure as we needed, they could each be a list
|
||||||
|
* or a tree on their own right.
|
||||||
|
*
|
||||||
|
* Now that we have a populated model we print a string representation of
|
||||||
|
* it(without forgetting to free the string):
|
||||||
|
* @until free
|
||||||
|
*
|
||||||
|
* And since we are done using our model we release our reference to it(and
|
||||||
|
* since no else holds references to it, it will be freed):
|
||||||
|
* @until }
|
||||||
|
*
|
||||||
|
* Note that we don't need to iterate over the children of @c m unrefing it,
|
||||||
|
* this is because we don't hold references to it, we freed our references right
|
||||||
|
* after we added them to their parent model, so when the parent model dies(and
|
||||||
|
* releases the references to it's children) they will be freed.
|
||||||
|
*
|
||||||
|
* The only thing we are going to look at is the callback we registered for
|
||||||
|
* whenever a model is deleted, since our models don't do anything fancy we are
|
||||||
|
* just going to print the memory address of the model being freed.
|
||||||
|
* @until }
|
||||||
|
*
|
||||||
|
* Note that this means the memory address is still valid, our callback is
|
||||||
|
* called just before the memory is freed so we could still access its
|
||||||
|
* information here.
|
||||||
|
*
|
||||||
|
* The full code can be seen in @ref eina_model_02_c
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @page eina_model_02_c eina_model_02.c
|
||||||
|
* @include eina_model_02.c
|
||||||
|
* @example eina_model_02.c
|
||||||
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @addtogroup Eina_Data_Types_Group Data Types
|
* @addtogroup Eina_Data_Types_Group Data Types
|
||||||
*
|
*
|
||||||
|
@ -58,70 +143,8 @@
|
||||||
* use it during development, get the logic right and just then
|
* use it during development, get the logic right and just then
|
||||||
* optimize what is needed (properties or children management).
|
* optimize what is needed (properties or children management).
|
||||||
*
|
*
|
||||||
* @code
|
* @ref eina_model_02_example_page contains an easy to follow example that
|
||||||
*
|
* demonstrates several of the important features of eina_model.
|
||||||
* static void _cb_on_deleted(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info)
|
|
||||||
* {
|
|
||||||
* printf("deleted %p\n", model);
|
|
||||||
* }
|
|
||||||
*
|
|
||||||
* int main(void)
|
|
||||||
* {
|
|
||||||
* Eina_Model *m;
|
|
||||||
* char *s;
|
|
||||||
* int i;
|
|
||||||
*
|
|
||||||
* eina_init();
|
|
||||||
*
|
|
||||||
* m = eina_model_new(EINA_MODEL_TYPE_GENERIC);
|
|
||||||
*
|
|
||||||
* eina_model_event_callback_add(m, "deleted", _cb_on_deleted, NULL);
|
|
||||||
*
|
|
||||||
* //Adding properties to model
|
|
||||||
* for (i = 0; i < 5; i++)
|
|
||||||
* {
|
|
||||||
* Eina_Value val;
|
|
||||||
* char name[2] = {'a'+ i, 0};
|
|
||||||
* eina_value_setup(&val, EINA_VALUE_TYPE_INT);
|
|
||||||
* eina_value_set(&val, i);
|
|
||||||
* eina_model_property_set(m, name, &val);
|
|
||||||
* eina_value_flush(&val);
|
|
||||||
* }
|
|
||||||
*
|
|
||||||
* //Adding children to model
|
|
||||||
* for (i = 0; i < 5; i++)
|
|
||||||
* {
|
|
||||||
* Eina_Value val;
|
|
||||||
* Eina_Model *c = eina_model_new(EINA_MODEL_TYPE_GENERIC);
|
|
||||||
* eina_value_setup(&val, EINA_VALUE_TYPE_INT);
|
|
||||||
* eina_value_set(&val, i);
|
|
||||||
* eina_model_property_set(c, "x", &val);
|
|
||||||
*
|
|
||||||
* eina_model_event_callback_add(c, "deleted", _cb_on_deleted, NULL);
|
|
||||||
*
|
|
||||||
* eina_model_child_append(m, c);
|
|
||||||
* //Now that the child has been appended to a model, it's parent will manage it's lifecycle
|
|
||||||
* eina_model_unref(c);
|
|
||||||
* eina_value_flush(&val);
|
|
||||||
* }
|
|
||||||
*
|
|
||||||
* s = eina_model_to_string(m);
|
|
||||||
* printf("model as string:\n%s\n", s);
|
|
||||||
*
|
|
||||||
* free(s);
|
|
||||||
* eina_model_unref(m);
|
|
||||||
*
|
|
||||||
* return 0;
|
|
||||||
* }
|
|
||||||
* @endcode
|
|
||||||
* This code exemplifies the creation of a model with five properties, named:
|
|
||||||
* 'a', 'b', 'c', 'd' and 'e' with values 0, 1, 2, 3 and 4
|
|
||||||
* respectively. In addition to the 5 properties our model also get 5 children,
|
|
||||||
* And to each child we give a property named 'x' with a value of 1, 2, 3, 4 and
|
|
||||||
* 5.
|
|
||||||
*
|
|
||||||
* In other words this piece of code shows how to use eina_model to store a list
|
|
||||||
* of elements, given that the list itself has some properties.
|
|
||||||
*
|
*
|
||||||
* An inheritance example: @ref eina_model_01_c
|
* An inheritance example: @ref eina_model_01_c
|
||||||
*
|
*
|
||||||
|
@ -181,27 +204,103 @@ typedef struct _Eina_Model_Event_Description Eina_Model_Event_Description;
|
||||||
*/
|
*/
|
||||||
typedef void (*Eina_Model_Event_Cb)(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info);
|
typedef void (*Eina_Model_Event_Cb)(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Creates a new model of type @a Type.
|
||||||
|
*
|
||||||
|
* @see _Eina_Model_Type
|
||||||
|
* @see eina_model_del()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI Eina_Model *eina_model_new(const Eina_Model_Type *type);
|
EAPI Eina_Model *eina_model_new(const Eina_Model_Type *type);
|
||||||
|
/**
|
||||||
|
* @brief Frees the memory associated with @a model
|
||||||
|
*
|
||||||
|
* @see eina_model_new()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI void eina_model_del(Eina_Model *model) EINA_ARG_NONNULL(1);
|
EAPI void eina_model_del(Eina_Model *model) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Returns the type of @a model.
|
||||||
|
*
|
||||||
|
* @see eina_model_new()
|
||||||
|
* @see _Eina_Model_Type
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI const Eina_Model_Type *eina_model_type_get(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
EAPI const Eina_Model_Type *eina_model_type_get(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Returns the interface named @a name of @a model.
|
||||||
|
*
|
||||||
|
* The name of every interface of @a model will be compared to @a name, the
|
||||||
|
* first one to match will be returned.
|
||||||
|
*
|
||||||
|
* @see eina_model_new()
|
||||||
|
* @see _Eina_Model_Interface
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI const Eina_Model_Interface *eina_model_interface_get(const Eina_Model *model,
|
EAPI const Eina_Model_Interface *eina_model_interface_get(const Eina_Model *model,
|
||||||
const char *name) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
const char *name) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Checks if @a model is an instance of @a type.
|
||||||
|
*
|
||||||
|
* @see eina_model_new()
|
||||||
|
* @see _Eina_Model_Type
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_model_instance_check(const Eina_Model *model,
|
EAPI Eina_Bool eina_model_instance_check(const Eina_Model *model,
|
||||||
const Eina_Model_Type *type) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
const Eina_Model_Type *type) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Checks if @a model implements @a iface.
|
||||||
|
*
|
||||||
|
* @see _Eina_Model_Interface
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_model_interface_implemented(const Eina_Model *model, const Eina_Model_Interface *iface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
EAPI Eina_Bool eina_model_interface_implemented(const Eina_Model *model, const Eina_Model_Interface *iface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Increases the refcount of @a model.
|
||||||
|
*
|
||||||
|
* @see eina_model_new()
|
||||||
|
* @see eina_model_unref()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI Eina_Model *eina_model_ref(Eina_Model *model) EINA_ARG_NONNULL(1);
|
EAPI Eina_Model *eina_model_ref(Eina_Model *model) EINA_ARG_NONNULL(1);
|
||||||
|
/**
|
||||||
|
* @brief Decreases the refcount of @a model.
|
||||||
|
*
|
||||||
|
* @see eina_model_ref()
|
||||||
|
* @see eina_model_del()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI void eina_model_unref(Eina_Model *model) EINA_ARG_NONNULL(1);
|
EAPI void eina_model_unref(Eina_Model *model) EINA_ARG_NONNULL(1);
|
||||||
|
/**
|
||||||
|
* @brief Returns the number of references to @a model.
|
||||||
|
*
|
||||||
|
* @see eina_model_ref()
|
||||||
|
* @see eina_model_unref()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI int eina_model_refcount(const Eina_Model *model) EINA_ARG_NONNULL(1);
|
EAPI int eina_model_refcount(const Eina_Model *model) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Add a callback to be called when @a event_name is emited.
|
||||||
|
*
|
||||||
|
* @see eina_model_event_callback_del()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_model_event_callback_add(Eina_Model *model,
|
EAPI Eina_Bool eina_model_event_callback_add(Eina_Model *model,
|
||||||
const char *event_name,
|
const char *event_name,
|
||||||
Eina_Model_Event_Cb cb,
|
Eina_Model_Event_Cb cb,
|
||||||
const void *data) EINA_ARG_NONNULL(1, 2, 3);
|
const void *data) EINA_ARG_NONNULL(1, 2, 3);
|
||||||
|
/**
|
||||||
|
* @brief Remove a callback that was to be called when @a event_name was emited.
|
||||||
|
*
|
||||||
|
* @see eina_model_event_callback_add()
|
||||||
|
* @since 1.2
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_model_event_callback_del(Eina_Model *model,
|
EAPI Eina_Bool eina_model_event_callback_del(Eina_Model *model,
|
||||||
const char *event_name,
|
const char *event_name,
|
||||||
Eina_Model_Event_Cb cb,
|
Eina_Model_Event_Cb cb,
|
||||||
|
@ -214,7 +313,7 @@ EAPI const Eina_Model_Event_Description *eina_model_event_description_get(const
|
||||||
* @brief Returns list of events this model may emit.
|
* @brief Returns list of events this model may emit.
|
||||||
* @param model The model whose events are to be listed.
|
* @param model The model whose events are to be listed.
|
||||||
* @return An Eina_List of stringshares with the name of every event. Free the
|
* @return An Eina_List of stringshares with the name of every event. Free the
|
||||||
* list with eina_model_event_names_list_free.
|
* list with eina_model_event_names_list_free().
|
||||||
*
|
*
|
||||||
* @since 1.2
|
* @since 1.2
|
||||||
*/
|
*/
|
||||||
|
@ -511,7 +610,7 @@ EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EIN
|
||||||
* @struct _Eina_Model_Type
|
* @struct _Eina_Model_Type
|
||||||
* API to access models.
|
* API to access models.
|
||||||
*
|
*
|
||||||
* The methods @c setup, @c flush, @c constructor, @c destructor and
|
* @warning The methods @c setup, @c flush, @c constructor, @c destructor and
|
||||||
* @c property_get are mandatory and must exist, otherwise type cannot
|
* @c property_get are mandatory and must exist, otherwise type cannot
|
||||||
* be used.
|
* be used.
|
||||||
*
|
*
|
||||||
|
@ -861,6 +960,9 @@ EAPI const void *eina_model_type_method_offset_resolve(const Eina_Model_Type *ty
|
||||||
/**
|
/**
|
||||||
* @struct _Eina_Model_Interface
|
* @struct _Eina_Model_Interface
|
||||||
*
|
*
|
||||||
|
* @warning The methods @c setup, @c flush, @c constructor and @c destructor are
|
||||||
|
* mandatory and must exist, otherwise type cannot be used.
|
||||||
|
*
|
||||||
* Interfaces are managed by name, then multiple Eina_Model_Interface
|
* Interfaces are managed by name, then multiple Eina_Model_Interface
|
||||||
* may have the same name meaning it implements that name.
|
* may have the same name meaning it implements that name.
|
||||||
*
|
*
|
||||||
|
|
Loading…
Reference in New Issue