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

doxygen: sanitize Eo Tutorial 

Summary: The Eo tutorial had a tough readability. It is better now: stars are not messing around with the code, plus code does not collide anymore with a bullet in a bullet list.

Reviewers: cedric, JackDanielZ, tasn

Reviewed By: tasn

Subscribers: cedric

Differential Revision: https://phab.enlightenment.org/D1230
This commit is contained in:
Jean Guyomarc'h 2014-08-04 11:34:51 +02:00 committed by Cedric BAIL
parent 23761ed627
commit e37ad31e58
2 changed files with 218 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/e.css
View File

@ -154,6 +154,11 @@ dl.el {
line-height: 0%; line-height: 0%;
} }
/* To avoid packed effect on bullet lists */
li .line:first-child {
margin-top: 10px;
}
pre.fragment { pre.fragment {
border: 1px solid #cccccc; border: 1px solid #cccccc;
background-color: #eeeeee; background-color: #eeeeee;

368
doc/eo_tutorial.dox
View File

@ -16,71 +16,71 @@
* *
* 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. * 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.
* *
* @section How to use it? * @section howto How to use it?
* - Creation of an instance of a class * - Creation of an instance of a class
* *
* - Old way: * - Old way:
* @code @code
* object = evas_object_line_add(canvas); object = evas_object_line_add(canvas);
* @endcode @endcode
* *
* - Eo way: * - Eo way:
* @code @code
* object = eo_add(EVAS_OBJ_LINE_CLASS, canvas); object = eo_add(EVAS_OBJ_LINE_CLASS, canvas);
* @endcode @endcode
* *
* - Call to function * - Call to function
* *
* - Old way: * - Old way:
* @code @code
* evas_object_move(obj, 120, 120); evas_object_move(obj, 120, 120);
* evas_object_resize(obj, 200, 200); evas_object_resize(obj, 200, 200);
* @endcode @endcode
* *
* - Eo way: * - Eo way:
* @code @code
* eo_do(obj, eo_do(obj,
* evas_obj_move(120, 120), evas_obj_move(120, 120),
* evas_obj_resize(200, 200)); evas_obj_resize(200, 200));
* @endcode @endcode
* *
* - Extract specific data * - Extract specific data
* *
* - Old way: * - Old way:
* @code @code
* Evas_Object_Line *o = (Evas_Object_Line *)(obj->object_data); Evas_Object_Line *o = (Evas_Object_Line *)(obj->object_data);
* MAGIC_CHECK(o, Evas_Object_Line, MAGIC_OBJ_LINE); MAGIC_CHECK(o, Evas_Object_Line, MAGIC_OBJ_LINE);
* return; return;
* MAGIC_CHECK_END(); MAGIC_CHECK_END();
* @endcode @endcode
* *
* - Eo way: * - Eo way:
* Two functions can be used to extract object data. The use depends if you want to store the data or not. If you just need to access data in the function (most of the time), just use eo_data_scope_get. If you need to store the data (for example in a list of objects data), you have to use eo_data_ref. This function references the data. If you don't need the referenced data anymore, call eo_data_unref. * Two functions can be used to extract object data. The use depends if you want to store the data or not. If you just need to access data in the function (most of the time), just use eo_data_scope_get. If you need to store the data (for example in a list of objects data), you have to use eo_data_ref. This function references the data. If you don't need the referenced data anymore, call eo_data_unref.
* This reference mechanism will be used in the future to detect bad usage of objects, defragment the memory space used by the objects... * This reference mechanism will be used in the future to detect bad usage of objects, defragment the memory space used by the objects...
* @code @code
* Evas_Object_Line *o = eo_data_scope_get(obj, EVAS_OBJ_LINE_CLASS); Evas_Object_Line *o = eo_data_scope_get(obj, EVAS_OBJ_LINE_CLASS);
* if (!o) return; if (!o) return;
* @endcode @endcode
* or * or
* @code @code
* Evas_Object_Line *o = eo_data_ref(obj, EVAS_OBJ_LINE_CLASS); Evas_Object_Line *o = eo_data_ref(obj, EVAS_OBJ_LINE_CLASS);
* if (!o) return; if (!o) return;
* ... ...
* eo_data_unref(obj, o); eo_data_unref(obj, o);
* @endcode @endcode
* *
* - Call function of parent * - Call function of parent
* - Old way: * - Old way:
* @code @code
* ELM_WIDGET_CLASS(_elm_button_parent_sc)->theme(obj)); ELM_WIDGET_CLASS(_elm_button_parent_sc)->theme(obj));
* @endcode @endcode
* *
* - New way: * - New way:
* @code @code
* eo_do_super(obj, elm_wdg_theme(&int_ret)); eo_do_super(obj, elm_wdg_theme(&int_ret));
* @endcode @endcode
* *
* @section Important to know * @section important Important to know
* - eo_do() is the function used to invoke functions of a specific class on an object. * - eo_do() is the function used to invoke functions of a specific class on an object.
* *
* - eo_data_scope_get() and eo_data_ref() 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. * - eo_data_scope_get() and eo_data_ref() 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.
@ -95,12 +95,12 @@
* - 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. * - 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.
* *
* - Don't do this: * - Don't do this:
* @code @code
* int w, h; int w, h;
* eo_do(obj, eo_do(obj,
* evas_obj_size_get(&w, &h), evas_obj_size_get(&w, &h),
* evas_obj_size_set(w+10, h+20)); evas_obj_size_set(w+10, h+20));
* @endcode @endcode
* w+10 and h+20 are evaluated before the call to size_get. * w+10 and h+20 are evaluated before the call to size_get.
* Instead, separate it in two calls to eo_do(). * Instead, separate it in two calls to eo_do().
* *
@ -118,7 +118,7 @@
* *
* - Avoid exposing your class data to prevent ABI break. Supply access functions instead. * - Avoid exposing your class data to prevent ABI break. Supply access functions instead.
* *
* @section How to create a class - H side? * @section create_class_h_side How to create a class - H side?
* - If the object is new, establish the public APIs * - If the object is new, establish the public APIs
* - #define \$(CLASS_NAME) \$(class_name)_class_get(): will be used to access data/inherit from this class... * - #define \$(CLASS_NAME) \$(class_name)_class_get(): will be used to access data/inherit from this class...
* - 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... * - 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...
@ -133,75 +133,77 @@
* - And don't forget to document each function * - And don't forget to document each function
* *
* - Example (Evas Object Line): * - Example (Evas Object Line):
* @code @code
* #define EVAS_OBJ_LINE_CLASS evas_object_line_class_get() #define EVAS_OBJ_LINE_CLASS evas_object_line_class_get()
*
* const Eo_Class *evas_object_line_class_get(void) EINA_CONST; const Eo_Class *evas_object_line_class_get(void) EINA_CONST;
*
* extern EAPI Eo_Op EVAS_OBJ_LINE_BASE_ID; extern EAPI Eo_Op EVAS_OBJ_LINE_BASE_ID;
*
* enum enum
* { {
* EVAS_OBJ_LINE_SUB_ID_XY_SET, EVAS_OBJ_LINE_SUB_ID_XY_SET,
* EVAS_OBJ_LINE_SUB_ID_XY_GET, EVAS_OBJ_LINE_SUB_ID_XY_GET,
* EVAS_OBJ_LINE_SUB_ID_LAST EVAS_OBJ_LINE_SUB_ID_LAST
* } }
*
* #define EVAS_OBJ_LINE_ID(sub_id) (EVAS_OBJ_LINE_BASE_ID + sub_id) #define EVAS_OBJ_LINE_ID(sub_id) (EVAS_OBJ_LINE_BASE_ID + sub_id)
*
* /* /*
* * @def evas_obj_line_xy_set * @def evas_obj_line_xy_set
* * @since 1.8 * @since 1.8
* * *
* * Sets the coordinates of the end points of the given evas line object. * Sets the coordinates of the end points of the given evas line object.
* * *
* * @param[in] x1 * @param[in] x1
* * @param[in] y1 * @param[in] y1
* * @param[in] x2 * @param[in] x2
* * @param[in] y2 * @param[in] y2
* * *
* */ */
* #define evas_obj_line_xy_set(x1, y1, x2, y2) EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_SET), EO_TYPECHECK(Evas_Coord, x1), EO_TYPECHECK(Evas_Coord, y1), EO_TYPECHECK(Evas_Coord, x2), EO_TYPECHECK(Evas_Coord, y2) #define evas_obj_line_xy_set(x1, y1, x2, y2) EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_SET), EO_TYPECHECK(Evas_Coord, x1), EO_TYPECHECK(Evas_Coord, y1), EO_TYPECHECK(Evas_Coord, x2), EO_TYPECHECK(Evas_Coord, y2)
*
* /* /*
* * @def evas_obj_line_xy_get * @def evas_obj_line_xy_get
* * @since 1.8 * @since 1.8
* * *
* * Retrieves the coordinates of the end points of the given evas line object. * Retrieves the coordinates of the end points of the given evas line object.
* * *
* * @param[out] x1 * @param[out] x1
* * @param[out] y1 * @param[out] y1
* * @param[out] x2 * @param[out] x2
* * @param[out] y2 * @param[out] y2
* * *
* */ */
* #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) #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)
@endcode @endcode
* *
* @section How to create a class - C side? * @section create_class_c_size How to create a class - C side?
* Below, the object line as example. * Below, the object line as example.
* *
* #include "Eo.h"\n @code
* EAPI Eo_Op \$(CLASS_NAME)_BASE_ID = EO_NOOP; // Initialisation of the class id to 0. Will be set dynamically by Eo itself.\n #include "Eo.h"\n
* #define MY_CLASS \$(CLASS_NAME) EAPI Eo_Op \$(CLASS_NAME)_BASE_ID = EO_NOOP; // Initialisation of the class id to 0. Will be set dynamically by Eo itself.\n
* #define MY_CLASS \$(CLASS_NAME)
* ...
...
@endcode
* *
* Example for a developer function called by Eo:\n * Example for a developer function called by Eo:\n
* This function receives the Eo object, the data corresponding to this class and the list of parameters. * This function receives the Eo object, the data corresponding to this class and the list of parameters.
* @code @code
* static void static void
* _foo(Eo *eo_obj, void *_pd, va_list *list) _foo(Eo *eo_obj, void *_pd, va_list *list)
* { {
* int param_1 = va_arg(*list, int); int param_1 = va_arg(*list, int);
* Eina_Bool param_2 = va_arg(*list, int); Eina_Bool param_2 = va_arg(*list, int);
* Eina_Bool ret = va_arg(*list, Eina_Bool *); Eina_Bool ret = va_arg(*list, Eina_Bool *);
* foo_data obj = _pd; foo_data obj = _pd;
*
* if (ret) *ret = EINA_FALSE; if (ret) *ret = EINA_FALSE;
* ... ...
* } }
* @endcode @endcode
* *
* 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 * 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
* See eo_constructor() and eo_destructor().\n * See eo_constructor() and eo_destructor().\n
@ -232,83 +234,83 @@
* *
* *
* Example (Evas Object Line): * Example (Evas Object Line):
* @code @code
* #include "Eo.h" #include "Eo.h"
*
* EAPI Eo_Op EVAS_OBJ_LINE_BASE_ID = EO_NOOP; EAPI Eo_Op EVAS_OBJ_LINE_BASE_ID = EO_NOOP;
*
* #define MY_CLASS EVAS_OBJ_LINE_CLASS #define MY_CLASS EVAS_OBJ_LINE_CLASS
* @endcode @endcode
* *
* ... * ...
* *
* @code @code
* static void static void
* _line_xy_get(Eo *eo_obj, void *_pd, va_list *list) _line_xy_get(Eo *eo_obj, void *_pd, va_list *list)
* { {
* const Evas_Object_Line *o = _pd; const Evas_Object_Line *o = _pd;
*
* Evas_Coord *x1 = va_arg(*list, Evas_Coord *); Evas_Coord *x1 = va_arg(*list, Evas_Coord *);
* Evas_Coord *y1 = va_arg(*list, Evas_Coord *); Evas_Coord *y1 = va_arg(*list, Evas_Coord *);
* Evas_Coord *x2 = va_arg(*list, Evas_Coord *); Evas_Coord *x2 = va_arg(*list, Evas_Coord *);
* Evas_Coord *y2 = va_arg(*list, Evas_Coord *); Evas_Coord *y2 = va_arg(*list, Evas_Coord *);
*
* Evas_Object_Protected_Data *obj = eo_data_scope_get(eo_obj, EVAS_OBJ_CLASS); Evas_Object_Protected_Data *obj = eo_data_scope_get(eo_obj, EVAS_OBJ_CLASS);
* if (x1) *x1 = obj->cur.geometry.x + o->cur.x1; if (x1) *x1 = obj->cur.geometry.x + o->cur.x1;
* if (y1) *y1 = obj->cur.geometry.y + o->cur.y1; if (y1) *y1 = obj->cur.geometry.y + o->cur.y1;
* if (x2) *x2 = obj->cur.geometry.x + o->cur.x2; if (x2) *x2 = obj->cur.geometry.x + o->cur.x2;
* if (y2) *y2 = obj->cur.geometry.y + o->cur.y2; if (y2) *y2 = obj->cur.geometry.y + o->cur.y2;
* } }
*
* static void static void
* _constructor(Eo *eo_obj, void *class_data, va_list *list EINA_UNUSED) _constructor(Eo *eo_obj, void *class_data, va_list *list EINA_UNUSED)
* { {
* eo_do_super(eo_obj, eo_constructor()); eo_do_super(eo_obj, eo_constructor());
*
* Evas_Object_Protected_Data *obj = eo_data_scope_get(eo_obj, EVAS_OBJ_CLASS); Evas_Object_Protected_Data *obj = eo_data_scope_get(eo_obj, EVAS_OBJ_CLASS);
* evas_object_line_init(eo_obj); evas_object_line_init(eo_obj);
* } }
*
* ... ...
*
* /* class constructor */ /* class constructor */
* static void static void
* _class_constructor(Eo_Class *klass) _class_constructor(Eo_Class *klass)
* { {
* const Eo_Op_Func_Description func_desc[] = { const Eo_Op_Func_Description func_desc[] = {
* /* Virtual functions of parent class implemented in this class */ /* Virtual functions of parent class implemented in this class */
* EO_OP_FUNC(EO_BASE_ID(EO_BASE_SUB_ID_CONSTRUCTOR), _constructor), EO_OP_FUNC(EO_BASE_ID(EO_BASE_SUB_ID_CONSTRUCTOR), _constructor),
* EO_OP_FUNC(EO_BASE_ID(EO_BASE_SUB_ID_DESTRUCTOR), _destructor), EO_OP_FUNC(EO_BASE_ID(EO_BASE_SUB_ID_DESTRUCTOR), _destructor),
* /* Specific functions to this class */ /* Specific functions to this class */
* EO_OP_FUNC(EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_SET), _line_xy_set), EO_OP_FUNC(EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_SET), _line_xy_set),
* EO_OP_FUNC(EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_GET), _line_xy_get), EO_OP_FUNC(EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_GET), _line_xy_get),
* EO_OP_FUNC_SENTINEL EO_OP_FUNC_SENTINEL
* }; };
*
* eo_class_funcs_set(klass, func_desc); eo_class_funcs_set(klass, func_desc);
* } }
*
* /* Descriptions for the functions specific to this class */ /* Descriptions for the functions specific to this class */
* static const Eo_Op_Description op_desc[] = { static const Eo_Op_Description op_desc[] = {
* EO_OP_DESCRIPTION(EVAS_OBJ_LINE_SUB_ID_XY_SET, "Sets the coordinates of the end points of the given evas line object."), EO_OP_DESCRIPTION(EVAS_OBJ_LINE_SUB_ID_XY_SET, "Sets the coordinates of the end points of the given evas line object."),
* EO_OP_DESCRIPTION(EVAS_OBJ_LINE_SUB_ID_XY_GET, "Retrieves the coordinates of the end points of the given evas line object."), EO_OP_DESCRIPTION(EVAS_OBJ_LINE_SUB_ID_XY_GET, "Retrieves the coordinates of the end points of the given evas line object."),
* EO_OP_DESCRIPTION_SENTINEL EO_OP_DESCRIPTION_SENTINEL
* }; };
*
* /* Description of the class */ /* Description of the class */
* static const Eo_Class_Description class_desc = { static const Eo_Class_Description class_desc = {
* EO_VERSION, EO_VERSION,
* "Evas_Object_Line", "Evas_Object_Line",
* EO_CLASS_TYPE_REGULAR, EO_CLASS_TYPE_REGULAR,
* EO_CLASS_DESCRIPTION_OPS(&EVAS_OBJ_LINE_BASE_ID, op_desc, EVAS_OBJ_LINE_SUB_ID_LAST), EO_CLASS_DESCRIPTION_OPS(&EVAS_OBJ_LINE_BASE_ID, op_desc, EVAS_OBJ_LINE_SUB_ID_LAST),
* NULL, NULL,
* sizeof(Evas_Object_Line), sizeof(Evas_Object_Line),
* _class_constructor, _class_constructor,
* NULL NULL
* }; };
*
* /* Definition of the class */ /* Definition of the class */
* EO_DEFINE_CLASS(evas_object_line_class_get, &class_desc, EVAS_OBJ_CLASS, NULL); EO_DEFINE_CLASS(evas_object_line_class_get, &class_desc, EVAS_OBJ_CLASS, NULL);
* @endcode @endcode
*/ */