aboutsummaryrefslogtreecommitdiffstats
path: root/DEV_README
blob: ccd06bb482f546fa6ea2d1c72540549862733c93 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

Yakov Goldberg <yakov.g@samsung.com>

EO introspection is set of tools to generate high-level
language bindings for C libraries based on Eo (E Object) library,
     Usual workflow:
     - parsing C-sources and generating XML
     - generating source files, makefiles
       < include additional modules 
     - compile module

  This document describes current development issues,
    and supposes that reader has some knowledge
    about Eo, Elementary, Python and JS bindings


* Generating function names

  Issues:
     Names of funcs to be generated, name clashes.

     In the beginning there was idea to cut func name from OP_ID.

     There is OP_ID 'SOME_CLASS_SUB_ID_COLOR_GET' and public function
     'some_class_color_get()' which connected with OP_ID,
     so 'color_get()' will be generated.

     If there is another class ANOTHER_CLASS(SOME_CLASS) with
     'ANOTHER_CLASS_SUB_ID_COLOR_GET' and 'another_class_color_get()'
     public function, another 'color_get()' func will be generated.

     I don't check for names clash.
     There won't be an error and function will be simply overloaded, 
     but it will be completely wrong.

     There shouldn't be function overloading at all, that's all done
     in library itself, in bindings I call only for most base func.

     Conflict should be resolved in library itself. If we want single
     'color_set()' for all classes, they need to be overloaded 
     in proper way.

     At the moment full names like some_class_color_set() and 
     another_class_color_set() will be generated.

* Properties names parsing
    If func name ends with '_set'/'_get'
    parameters are checked on direction 'in' for 'set' prop 
    and on 'out' for 'get' prop.
    If it's wrong, this function will be generated as a method.

    Too common implementation. Need to provide descriptions(comments).



* Parameter's Types;
    Basic types can be detected; 
    also "types" file can be provided which says how to cast to basic types:
       <type from="Evas_Font_Size" to="int"/>
       <type from="Eo_Callback_Priority" to="short"/>
       <type from="Evas_Smart" to="Eo"/>

    if some type wasn't found, function will not be generated.

    Issues:
       Types like Eina_List, arrays, structs need wrapping to Python types
         can be done by providing descriptions(comments), but requires work.

       Returning existing Object or new one.
         Need to check returning instance with eo_base_data_get("Python instance");
         if o != NULL: 
           return o
         else: ( need to create one:)
           get class name,
           find constructor
           create object
       
           Requires work.


* Constructing object:
    Now objects are constructed with default constuctor.
    Some classes provide custom constructors and some ONLY custom constructors.

    example for window:
    eo_add_custom(eo, elm_win_constructor("my win", ELM_WIN_BASIC))

    in Python:
      can be called like this
      win = ElmWin("my win", ELM_WIN_BASIC)

    in JS??
      in elev8 - this is hardcoded, ("main" ELM_WIN_BASIC) is created

    Issues: 
       How to fetch custom constructors from source?
          Add decorators to comments. Looks like fine.

       How to call custom constructors with same signature, but with different name?
          eo_add_custom(eo, elm_win_constructor_one("my win", ELM_WIN_BASIC))
          eo_add_custom(eo, elm_win_constructor_two("my win", ELM_WIN_BASIC))

          What to do in Python?
            Define additional variable?
            win = ElmWin(win.CONSTR1, "my win", ELM_WIN_BASIC)

            and provide the way to parse argv[] in __init__ func?


* Callbacks in Python.
    Issues:
      Pass data to callback.
      Add callback to Evas_Object
  
    Description:
      All callbacks are added to Eo object on registered event in this/parent class.
      To add callback EoBase.event_callback_priority_add() is used.
      Callback can be added for introspected events.
  
      Adding callback:
  
        func(obj, data)
  
        cb_obj = (func, data)
        py_obj.event_callback_priority_add(class.EVENT_ID, 0, cb_obj)
        py_obj.event_callback_del(class.EVENT_ID, cb_obj)
  
        it's also possible to add callback like this:
      
          py_obj.event_callback_priority_add(class.EVENT_ID, 0, (func, data))
  
        reference of (func, data) object is incremented,
        so callback will be called properly.
        But it won't be possible to delete it.
     
      What's going on inside:
        Proxy _callback() function(eo signature) is added to real C
        object for desired event; Py cb_obj is set as data.
        When event occurs, _callback() is called with data; Py func and data are fetched
        and Py cb is called.
  
        Maybe it's not the best idea to add data like this, but the idea
        is to give Eo as much work as possible.
        So no internal lists are managed to pass and keep
        callback data as (*args **kwargs).
  
  
      Adding callbacks to Evas_Object:
        In C, callbacks are added with evas_object_event_callback_add(),
        which is not in eo indrospection at all.
        Evas Events are also not in introspection scope,
        because they are not added to Eo objects.
   
      Issue:
        What to do with Evas events?
        It's possible to add stuff manually:
          - define extern evas_object_event_callback_add()
          - define extern event's enum
          - define public event_add/del funcs for class
   
* Callbacks in JS:
    In elev8 one callback per event was implemented, without adding cb data.

    There are some ideas how to put several callbacks and data if needed, but it must be checked.


* Adding elm_init() and other additional funcs
        
    Sometimes some additional functions like elm_init(), elm_run()
    are needed. These functions are not introspectable,
    they must be added manually.
    
    Example for python:
    To do this, the user must provide definitions in *.pxd, *.pxi files,
     include *.pxi into generated 'module_name.pyx' file and compile.

     Usual workflow:
     - generating XML
     - generating source files, makefiles
                          < add files manually 
     - compile module


* Enums from headers.
    Need to provide descriptions(comments), to understand how to fetch it

* Issues about elementary:
   After parsing sources, found headers are included 
   into generated files.

   All include error must be fixed manually, t.e. issues with
   including elm_*.h and Elementary.h and compilation flags like
   -DELM_INTERNAL_API_ARGESFSDFEFC=1