summaryrefslogtreecommitdiff
path: root/doc/eo_tutorial.dox
diff options
context:
space:
mode:
authorGustavo Sverzut Barbieri <barbieri@gmail.com>2012-12-28 23:26:05 +0000
committerGustavo Sverzut Barbieri <barbieri@gmail.com>2012-12-28 23:26:05 +0000
commit2608f68571b277967b2e27d6136c95f03befd183 (patch)
tree24a3b2764432b9fbde980aabf6bc40e7c74b1610 /doc/eo_tutorial.dox
parent4f6a4e59a4e7774fe55ae3ecf37d42faabec07e4 (diff)
efl/docs: clean-up and make it more uniform.
now unified docs are bit more uniform in their start pages, overall improved but much to do :-( SVN revision: 81851
Diffstat (limited to 'doc/eo_tutorial.dox')
-rw-r--r--doc/eo_tutorial.dox42
1 files changed, 18 insertions, 24 deletions
diff --git a/doc/eo_tutorial.dox b/doc/eo_tutorial.dox
index c30da62..364ff54 100644
--- a/doc/eo_tutorial.dox
+++ b/doc/eo_tutorial.dox
@@ -1,12 +1,10 @@
1/** 1/**
2 * @page Eo_Tutorial Eo Tutorial 2 * @page Eo_Tutorial Eo Tutorial
3 * 3 *
4 * Purpose: 4 * @section Purpose
5 * -------
6 * The purpose of this document is to explain how to work with Eo, how to port your code to Eo and what are the common pitfalls. It doesn't explain how it works inside. 5 * The purpose of this document is to explain how to work with Eo, how to port your code to Eo and what are the common pitfalls. It doesn't explain how it works inside.
7 * 6 *
8 * Description: 7 * @section Description
9 * -----------
10 * Eo is an Object oriented infrastructure for the EFL. It is a API/ABI safe library. 8 * Eo is an Object oriented infrastructure for the EFL. It is a API/ABI safe library.
11 * 9 *
12 * It supports inheritance, mixins, interfaces and composite objects.\n 10 * It supports inheritance, mixins, interfaces and composite objects.\n
@@ -16,10 +14,9 @@
16 * At the creation of the class, a "virtual table" is filled with the needed functions.\n 14 * At the creation of the class, a "virtual table" is filled with the needed functions.\n
17 * The key of this table is a (class id, function id) tuple. 15 * The key of this table is a (class id, function id) tuple.
18 * 16 *
19 * eo_do is invoked with a list of op ids and their parameters and is in charge to dispatch the relevant functions. Finding the correct function is fast because it is just a lookup table. 17 * eo_do() is invoked with a list of op ids and their parameters and is in charge to dispatch the relevant functions. Finding the correct function is fast because it is just a lookup table.
20 * 18 *
21 * How to use it? 19 * @section How to use it?
22 * -------------
23 * - Creation of an instance of a class 20 * - Creation of an instance of a class
24 * 21 *
25 * - Old way: 22 * - Old way:
@@ -74,18 +71,17 @@
74 * eo_do_super(obj, elm_wdg_theme(&int_ret)); 71 * eo_do_super(obj, elm_wdg_theme(&int_ret));
75 * @endcode 72 * @endcode
76 * 73 *
77 * Important to know: 74 * @section Important to know
78 * ----------------- 75 * - eo_do() is the function used to invoke functions of a specific class on an object.
79 * - eo_do is the function used to invoke functions of a specific class on an object.
80 * 76 *
81 * - eo_data_get receives an object and a class and returns the data of the given class for the object. The class must belong to the object class hierarchy. 77 * - eo_data_get() receives an object and a class and returns the data of the given class for the object. The class must belong to the object class hierarchy.
82 * 78 *
83 * - eo_isa indicates if a given object is of a given type. 79 * - eo_isa() indicates if a given object is of a given type.
84 * 80 *
85 * - eo_do_super is in charge to invoke a function in the next parents that implement it. It is recommended to use eo_do_super only from a function with the same op id.\n 81 * - eo_do_super() is in charge to invoke a function in the next parents that implement it. It is recommended to use eo_do_super() only from a function with the same op id.\n
86 * In addition, there is no way to jump over classes who implement the function. If A inherits from B, B from C and A, B and C implement a virtual function defined in C, the function calls order will be A, then B and finally C. It is impossible to pass over B. 82 * In addition, there is no way to jump over classes who implement the function. If A inherits from B, B from C and A, B and C implement a virtual function defined in C, the function calls order will be A, then B and finally C. It is impossible to pass over B.
87 * 83 *
88 * - eo_do returns if the operation succeeded or failed (function found, object deleted...), not the result of the called function. Pay attention to this detail when you call eo_do. The return value needs to be an additional parameter which will hold a return value. 84 * - eo_do() returns if the operation succeeded or failed (function found, object deleted...), not the result of the called function. Pay attention to this detail when you call eo_do(). The return value needs to be an additional parameter which will hold a return value.
89 * 85 *
90 * - Don't do this: 86 * - Don't do this:
91 * @code 87 * @code
@@ -95,12 +91,12 @@
95 * evas_obj_size_set(w+10, h+20)); 91 * evas_obj_size_set(w+10, h+20));
96 * @endcode 92 * @endcode
97 * w+10 and h+20 are evaluated before the call to size_get. 93 * w+10 and h+20 are evaluated before the call to size_get.
98 * Instead, separate it in two calls to eo_do. 94 * Instead, separate it in two calls to eo_do().
99 * 95 *
100 * - When creating an object with eo_add, the reference counter of this one is incremented. If it is called with a parent, two references are on the object. eo_del removes both of these references.\n 96 * - When creating an object with eo_add(), the reference counter of this one is incremented. If it is called with a parent, two references are on the object. eo_del() removes both of these references.\n
101 * When there is no more references on an object, this one is deleted and then can be freed. The deletion calls to the destructor (see eo_destructor). When done, Eo checks if the object can be freed. The free mechanism can be "disabled" through eo_manual_free_set. If this is the case, it is the responsibility of the developer to call eo_manual_free on the object in order to free it. This mechanism has been used for example in Evas on the Evas objects and in Ecore. 97 * When there is no more references on an object, this one is deleted and then can be freed. The deletion calls to the destructor (see eo_destructor()). When done, Eo checks if the object can be freed. The free mechanism can be "disabled" through eo_manual_free_set(). If this is the case, it is the responsibility of the developer to call eo_manual_free() on the object in order to free it. This mechanism has been used for example in @ref Evas on the Evas objects and in @ref Ecore.
102 * 98 *
103 * - When eo_do reaches a function of a class, it is the responsibility of the user to extract from the va_list ALL the parameters needed for this function, NO MORE, NO LESS. Otherwise, unknown behavior can occur. eo_do is called with a list of op id, params, op id, params... A bad extraction of parameters can bring to the parsing of a wrong op id and so in the best case, to an error, in the worst case, to another function not in relation with the actual use case. 99 * - When eo_do() reaches a function of a class, it is the responsibility of the user to extract from the va_list ALL the parameters needed for this function, NO MORE, NO LESS. Otherwise, unknown behavior can occur. eo_do() is called with a list of op id, params, op id, params... A bad extraction of parameters can bring to the parsing of a wrong op id and so in the best case, to an error, in the worst case, to another function not in relation with the actual use case.
104 * 100 *
105 * - Always pay attention to: 101 * - Always pay attention to:
106 * - the pairing between function id and the function itself. Using the same function for two ids occurs and is hard to debug. 102 * - the pairing between function id and the function itself. Using the same function for two ids occurs and is hard to debug.
@@ -111,8 +107,7 @@
111 * 107 *
112 * - Avoid exposing your class data to prevent ABI break. Supply access functions instead. 108 * - Avoid exposing your class data to prevent ABI break. Supply access functions instead.
113 * 109 *
114 * How to create a class - H side? 110 * @section How to create a class - H side?
115 * ------------------------------
116 * - If the object is new, establish the public APIs 111 * - If the object is new, establish the public APIs
117 * - #define \$(CLASS_NAME) \$(class_name)_class_get(): will be used to access data/inherit from this class... 112 * - #define \$(CLASS_NAME) \$(class_name)_class_get(): will be used to access data/inherit from this class...
118 * - const Eo_Class *\$(class_name)_class_get(void) EINA_CONST: declaration of the function that will create the class (not the instance), i.e virtual table... 113 * - const Eo_Class *\$(class_name)_class_get(void) EINA_CONST: declaration of the function that will create the class (not the instance), i.e virtual table...
@@ -172,8 +167,7 @@
172 * #define evas_obj_line_xy_get(x1, y1, x2, y2) EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_GET), EO_TYPECHECK(Evas_Coord *, x1), EO_TYPECHECK(Evas_Coord *, y1), EO_TYPECHECK(Evas_Coord *, x2), EO_TYPECHECK(Evas_Coord *, y2) 167 * #define evas_obj_line_xy_get(x1, y1, x2, y2) EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_GET), EO_TYPECHECK(Evas_Coord *, x1), EO_TYPECHECK(Evas_Coord *, y1), EO_TYPECHECK(Evas_Coord *, x2), EO_TYPECHECK(Evas_Coord *, y2)
173 @endcode 168 @endcode
174 * 169 *
175 * How to create a class - C side? 170 * @section How to create a class - C side?
176 * ------------------------------
177 * Below, the object line as example. 171 * Below, the object line as example.
178 * 172 *
179 * #include "Eo.h"\n 173 * #include "Eo.h"\n
@@ -198,8 +192,8 @@
198 * } 192 * }
199 * @endcode 193 * @endcode
200 * 194 *
201 * You can (not a must) implement a constructor. This constructor MUST call the parent constructor (eo_do_super). It is the same for the destructor.\n 195 * You can (not a must) implement a constructor. This constructor MUST call the parent constructor (eo_do_super()). It is the same for the destructor.\n
202 * See eo_constructor and eo_destructor.\n 196 * See eo_constructor() and eo_destructor().\n
203 * If you don't have anything to do in constructor (like malloc, variables init...) or in destructor (free), don't implement them. 197 * If you don't have anything to do in constructor (like malloc, variables init...) or in destructor (free), don't implement them.
204 * 198 *
205 * At the end of the file, you need to describe the class.\n 199 * At the end of the file, you need to describe the class.\n