\hypertarget{Eo_Tutorial_Purpose}{}\section{Purpose}\label{Eo_Tutorial_Purpose}
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.\hypertarget{Eo_Tutorial_Description}{}\section{Description}\label{Eo_Tutorial_Description}
Eo is an Object oriented infrastructure for the E\+F\+L. It is a A\+P\+I/\+A\+B\+I safe library.

It supports inheritance, mixins, interfaces and composite objects.~\newline
Every class can implement functions from every other class.~\newline
It supports event signals, function overrides, private/protected/public/etc. variables and functions.

At the creation of the class, a \char`\"{}virtual table\char`\"{} is filled with the needed functions.~\newline
The key of this table is a (class id, function id) tuple.

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.\hypertarget{Eo_Tutorial_howto}{}\section{How to use it?}\label{Eo_Tutorial_howto}

\begin{DoxyItemize}
\item Creation of an instance of a class
\begin{DoxyItemize}
\item Old way\+: 
\begin{DoxyCode}
\textcolor{keywordtype}{object} = evas\_object\_line\_add(canvas);
\end{DoxyCode}

\item Eo way\+: 
\begin{DoxyCode}
\textcolor{keywordtype}{object} = eo\_add(EVAS\_OBJ\_LINE\_CLASS, canvas);
\end{DoxyCode}

\end{DoxyItemize}
\item Call to function
\begin{DoxyItemize}
\item Old way\+: 
\begin{DoxyCode}
evas\_object\_move(obj, 120, 120);
evas\_object\_resize(obj, 200, 200);
\end{DoxyCode}

\item Eo way\+: 
\begin{DoxyCode}
eo\_do(obj,
      evas\_obj\_move(120, 120),
      evas\_obj\_resize(200, 200));
\end{DoxyCode}

\end{DoxyItemize}
\item Extract specific data
\begin{DoxyItemize}
\item Old way\+: 
\begin{DoxyCode}
Evas\_Object\_Line *o = (Evas\_Object\_Line *)(obj->object\_data);
MAGIC\_CHECK(o, Evas\_Object\_Line, MAGIC\_OBJ\_LINE);
\textcolor{keywordflow}{return};
MAGIC\_CHECK\_END();
\end{DoxyCode}

\item 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. This reference mechanism will be used in the future to detect bad usage of objects, defragment the memory space used by the objects... 
\begin{DoxyCode}
Evas\_Object\_Line *o = eo\_data\_scope\_get(obj, EVAS\_OBJ\_LINE\_CLASS);
\textcolor{keywordflow}{if} (!o) \textcolor{keywordflow}{return};
\end{DoxyCode}
 or 
\begin{DoxyCode}
Evas\_Object\_Line *o = eo\_data\_ref(obj, EVAS\_OBJ\_LINE\_CLASS);
\textcolor{keywordflow}{if} (!o) \textcolor{keywordflow}{return};
...
eo\_data\_unref(obj, o);
\end{DoxyCode}

\end{DoxyItemize}
\item Call function of parent
\begin{DoxyItemize}
\item Old way\+: 
\begin{DoxyCode}
ELM\_WIDGET\_CLASS(\_elm\_button\_parent\_sc)->theme(obj));
\end{DoxyCode}

\item New way\+: 
\begin{DoxyCode}
eo\_do\_super(obj, elm\_wdg\_theme(&int\_ret));
\end{DoxyCode}

\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{Eo_Tutorial_important}{}\section{Important to know}\label{Eo_Tutorial_important}

\begin{DoxyItemize}
\item eo\+\_\+do() is the function used to invoke functions of a specific class on an object.
\item 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.
\item eo\+\_\+data\+\_\+unref() receives an object and the data to unreference. The data M\+U\+S\+T belong to this object.
\item eo\+\_\+isa() indicates if a given object is of a given type.
\item 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.~\newline
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.
\item 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.
\item Don't do this\+: 
\begin{DoxyCode}
\textcolor{keywordtype}{int} w, h;
eo\_do(obj,
      evas\_obj\_size\_get(&w, &h),
      evas\_obj\_size\_set(w+10, h+20));
\end{DoxyCode}
 w+10 and h+20 are evaluated before the call to size\+\_\+get. Instead, separate it in two calls to eo\+\_\+do().
\item 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.~\newline
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 \char`\"{}disabled\char`\"{} 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 \hyperlink{group__Evas}{Evas} on the Evas objects and in \hyperlink{group__Ecore}{Ecore}.
\item When eo\+\_\+do() reaches a function of a class, it is the responsibility of the user to extract from the va\+\_\+list A\+L\+L the parameters needed for this function, N\+O M\+O\+R\+E, N\+O L\+E\+S\+S. 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.
\item Always pay attention to\+:
\begin{DoxyItemize}
\item the pairing between function id and the function itself. Using the same function for two ids occurs and is hard to debug.
\item the definition of the function macros in the H file and their parameters order/type
\item to extract all the parameters of a function from the va\+\_\+list
\end{DoxyItemize}
\item Enum of the op ids in H file and descriptions in C file must be synchronized, i.\+e same number of ids and same order. If you change the order by adding, removing or moving ids, you break A\+B\+I of your library.
\item Avoid exposing your class data to prevent A\+B\+I break. Supply access functions instead.
\end{DoxyItemize}\hypertarget{Eo_Tutorial_create_class_h_side}{}\section{How to create a class -\/ H side?}\label{Eo_Tutorial_create_class_h_side}

\begin{DoxyItemize}
\item If the object is new, establish the public A\+P\+Is
\item \#define \$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E) \$(class\+\_\+name)\+\_\+class\+\_\+get()\+: will be used to access data/inherit from this class...
\item const Eo\+\_\+\+Class $\ast$\$(class\+\_\+name)\+\_\+class\+\_\+get(void) E\+I\+N\+A\+\_\+\+C\+O\+N\+S\+T\+: declaration of the function that will create the class (not the instance), i.\+e virtual table...
\item extern E\+A\+P\+I Eo\+\_\+\+Op \$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E)\+\_\+\+B\+A\+S\+E\+\_\+\+I\+D\+: class id that will be essentially used to identify functions set of this class
\item enum of the function ids of the class in the form \$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E)\+\_\+\+S\+U\+B\+\_\+\+I\+D\+: used to identify the function inside the class; function id is unique per class but (class id, function id) is unique per system..
\item \#define \$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E)\+\_\+\+I\+D(sub\+\_\+id) (\$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E)\+\_\+\+B\+A\+S\+E\+\_\+\+I\+D + sub\+\_\+id)\+: formula to calculate the system function id
\item define of each function consists of\+:
\begin{DoxyItemize}
\item the name of the function that will be used in eo\+\_\+do
\item parameters without types
\item \$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E)\+\_\+\+I\+D(\$(C\+L\+A\+S\+S\+\_\+\+N\+A\+M\+E)\+\_\+\+S\+U\+B\+\_\+\+I\+D\+\_\+\+F\+U\+N\+C\+T\+I\+O\+N
\item E\+O\+\_\+\+T\+Y\+P\+E\+C\+H\+E\+C\+K for each parameter\+: type and variable name
\end{DoxyItemize}
\item And don't forget to document each function
\item Example (Evas Object Line)\+: 
\begin{DoxyCode}
\textcolor{preprocessor}{#define EVAS\_OBJ\_LINE\_CLASS evas\_object\_line\_class\_get()}

\textcolor{keyword}{const} \hyperlink{group__Eo_ga88d29df76a2921aa5478803156d83be5}{Eo\_Class} *evas\_object\_line\_class\_get(\textcolor{keywordtype}{void}) \hyperlink{group__Eina__Types__Group_ga04f4a207fcde054c818bace8af77dcd6}{EINA\_CONST};

extern \hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{EAPI} Eo\_Op EVAS\_OBJ\_LINE\_BASE\_ID;

enum
\{
   EVAS\_OBJ\_LINE\_SUB\_ID\_XY\_SET,
   EVAS\_OBJ\_LINE\_SUB\_ID\_XY\_GET,
   EVAS\_OBJ\_LINE\_SUB\_ID\_LAST
\}

\textcolor{preprocessor}{#define EVAS\_OBJ\_LINE\_ID(sub\_id) (EVAS\_OBJ\_LINE\_BASE\_ID + sub\_id)}

\textcolor{comment}{/*}
\textcolor{comment}{ * @def evas\_obj\_line\_xy\_set}
\textcolor{comment}{ * @since 1.8}
\textcolor{comment}{  }
\textcolor{comment}{ * Sets the coordinates of the end points of the given evas line object.}
\textcolor{comment}{  }
\textcolor{comment}{ * @param[in] x1}
\textcolor{comment}{ * @param[in] y1}
\textcolor{comment}{ * @param[in] x2}
\textcolor{comment}{ * @param[in] y2}
\textcolor{comment}{  }
\textcolor{comment}{ */}
\textcolor{preprocessor}{#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)}

\textcolor{comment}{/*}
\textcolor{comment}{ * @def evas\_obj\_line\_xy\_get}
\textcolor{comment}{ * @since 1.8}
\textcolor{comment}{  }
\textcolor{comment}{ * Retrieves the coordinates of the end points of the given evas line object.}
\textcolor{comment}{  }
\textcolor{comment}{ * @param[out] x1}
\textcolor{comment}{ * @param[out] y1}
\textcolor{comment}{ * @param[out] x2}
\textcolor{comment}{ * @param[out] y2}
\textcolor{comment}{  }
\textcolor{comment}{ */}
\textcolor{preprocessor}{#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)}
\end{DoxyCode}

\end{DoxyItemize}\hypertarget{Eo_Tutorial_create_class_c_size}{}\section{How to create a class -\/ C side?}\label{Eo_Tutorial_create_class_c_size}
Below, the object line as example.


\begin{DoxyCode}
\textcolor{preprocessor}{#include "Eo.h"}\(\backslash\)n
\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{EAPI} Eo\_Op \(\backslash\)$(CLASS\_NAME)\_BASE\_ID = EO\_NOOP; \textcolor{comment}{// Initialisation of the class id to 0. Will be set
       dynamically by Eo itself.\(\backslash\)n}
\textcolor{preprocessor}{#define MY\_CLASS \(\backslash\)$(CLASS\_NAME)}

...
\end{DoxyCode}


Example for a developer function called by Eo\+:~\newline
This function receives the Eo object, the data corresponding to this class and the list of parameters. 
\begin{DoxyCode}
\textcolor{keyword}{static} \textcolor{keywordtype}{void}
\_foo(\hyperlink{group__Eo_ga9f3010a50b61a892d41f4ec2bda73f4c}{Eo} *eo\_obj, \textcolor{keywordtype}{void} *\_pd, va\_list *list)
\{
   \textcolor{keywordtype}{int} param\_1 = va\_arg(*list, \textcolor{keywordtype}{int});
   \hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\_Bool} param\_2 = va\_arg(*list, \textcolor{keywordtype}{int});
   \hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\_Bool} ret = va\_arg(*list, \hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\_Bool} *);
   foo\_data obj = \_pd;

   \textcolor{keywordflow}{if} (ret) *ret = \hyperlink{group__Eina__Types__Group_ga1feb115f8e9913e806e090d9bd5a7301}{EINA\_FALSE};
   ...
\}
\end{DoxyCode}


You can (not a must) implement a constructor. This constructor M\+U\+S\+T call the parent constructor (eo\+\_\+do\+\_\+super()). It is the same for the destructor.~\newline
See eo\+\_\+constructor() and eo\+\_\+destructor().~\newline
If you don't have anything to do in constructor (like malloc, variables init...) or in destructor (free), don't implement them.

At the end of the file, you need to describe the class.~\newline
First, you need to supply the class constructor that sets the list of the functions that are implemented in this class. It includes functions overriden (constructor, destructor, member\+\_\+add...) and functions specific to this class. If there is no function implemented in this class, you don't need a class constructor.~\newline
Then, you need a list to describe the new functions. For each one, the op id and a description.~\newline
 Then, the class itself that consists in\+:
\begin{DoxyItemize}
\item the version of Eo, used for backward compatibility
\item the class name
\item the type of the class\+:
\begin{DoxyItemize}
\item regular\+: an object can be created from this type (mostly used)
\item regular non instant-\/iable\+: Same as previous, but objects can’t be created from this type (elm\+\_\+widget)
\item interface\+: used to extend classes, no implementations for functions and no internal data
\item mixin \+: interfaces with internal data and pre-\/made implementations for functions
\end{DoxyItemize}
\item the descriptions list described above and the number of ops for this class
\item events
\item size of the data of the class
\item the class constructor, if exists, else N\+U\+L\+L
\item the class destructor (N\+U\+L\+L most of the time)
\end{DoxyItemize}

Finally, we define the class with\+:
\begin{DoxyItemize}
\item the function name to give to the function that creates/returns the class
\item the class description explained above
\item the parent and the interfaces/mixins, finished by N\+U\+L\+L
\end{DoxyItemize}

Example (Evas Object Line)\+: 
\begin{DoxyCode}
\textcolor{preprocessor}{#include "Eo.h"}

\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{EAPI} Eo\_Op EVAS\_OBJ\_LINE\_BASE\_ID = EO\_NOOP;

\textcolor{preprocessor}{#define MY\_CLASS EVAS\_OBJ\_LINE\_CLASS}
\end{DoxyCode}


...


\begin{DoxyCode}
\textcolor{keyword}{static} \textcolor{keywordtype}{void}
\_line\_xy\_get(\hyperlink{group__Eo_ga9f3010a50b61a892d41f4ec2bda73f4c}{Eo} *eo\_obj, \textcolor{keywordtype}{void} *\_pd, va\_list *list)
\{
   \textcolor{keyword}{const} Evas\_Object\_Line *o = \_pd;

   \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *x1 = va\_arg(*list, \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *);
   \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *y1 = va\_arg(*list, \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *);
   \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *x2 = va\_arg(*list, \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *);
   \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *y2 = va\_arg(*list, \hyperlink{Evas__Common_8h_a2453e92182bad3b0e0d84e5aff433b07}{Evas\_Coord} *);

   Evas\_Object\_Protected\_Data *obj = eo\_data\_scope\_get(eo\_obj, EVAS\_OBJ\_CLASS);
   \textcolor{keywordflow}{if} (x1) *x1 = obj->cur.geometry.x + o->cur.x1;
   \textcolor{keywordflow}{if} (y1) *y1 = obj->cur.geometry.y + o->cur.y1;
   \textcolor{keywordflow}{if} (x2) *x2 = obj->cur.geometry.x + o->cur.x2;
   \textcolor{keywordflow}{if} (y2) *y2 = obj->cur.geometry.y + o->cur.y2;
\}

\textcolor{keyword}{static} \textcolor{keywordtype}{void}
\_constructor(\hyperlink{group__Eo_ga9f3010a50b61a892d41f4ec2bda73f4c}{Eo} *eo\_obj, \textcolor{keywordtype}{void} *class\_data, va\_list *list EINA\_UNUSED)
\{
   eo\_do\_super(eo\_obj, eo\_constructor());

   Evas\_Object\_Protected\_Data *obj = eo\_data\_scope\_get(eo\_obj, EVAS\_OBJ\_CLASS);
   evas\_object\_line\_init(eo\_obj);
\}

...

\textcolor{comment}{/* class constructor */}
static \textcolor{keywordtype}{void}
\_class\_constructor(\hyperlink{group__Eo_ga88d29df76a2921aa5478803156d83be5}{Eo\_Class} *klass)
\{
   \textcolor{keyword}{const} Eo\_Op\_Func\_Description func\_desc[] = \{
        \textcolor{comment}{/* 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\_DESTRUCTOR), \_destructor),
        \textcolor{comment}{/* 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\_GET), \_line\_xy\_get),
        EO\_OP\_FUNC\_SENTINEL
   \};

   eo\_class\_funcs\_set(klass, func\_desc);
\}

\textcolor{comment}{/* Descriptions for the functions specific to this class */}
\textcolor{keyword}{static} \textcolor{keyword}{const} Eo\_Op\_Description op\_desc[] = \{
     EO\_OP\_DESCRIPTION(EVAS\_OBJ\_LINE\_SUB\_ID\_XY\_SET, \textcolor{stringliteral}{"Sets the coordinates of the end points of the given
       evas line object."}),
     EO\_OP\_DESCRIPTION(EVAS\_OBJ\_LINE\_SUB\_ID\_XY\_GET, \textcolor{stringliteral}{"Retrieves the coordinates of the end points of the
       given evas line object."}),
     EO\_OP\_DESCRIPTION\_SENTINEL
\};

\textcolor{comment}{/* Description of the class */}
\textcolor{keyword}{static} \textcolor{keyword}{const} Eo\_Class\_Description class\_desc = \{
     EO\_VERSION,
     \textcolor{stringliteral}{"Evas\_Object\_Line"},
     EO\_CLASS\_TYPE\_REGULAR,
     EO\_CLASS\_DESCRIPTION\_OPS(&EVAS\_OBJ\_LINE\_BASE\_ID, op\_desc, EVAS\_OBJ\_LINE\_SUB\_ID\_LAST),
     NULL,
     \textcolor{keyword}{sizeof}(Evas\_Object\_Line),
     \_class\_constructor,
     NULL
\};

\textcolor{comment}{/* Definition of the class */}
EO\_DEFINE\_CLASS(evas\_object\_line\_class\_get, &class\_desc, EVAS\_OBJ\_CLASS, NULL);
\end{DoxyCode}
 