summaryrefslogtreecommitdiff
path: root/src/lib/eo/efl_object.eo
blob: 68d0d197703228a257f39ead8f5ce111e2c8153e (plain)
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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
import eina_types;

struct Efl.Event.Description {
    [[This struct holds the description of a specific event.]]
    name: string; [[name of the event.]]
    unfreezable: bool; [[$true if the event cannot be frozen.]]
    legacy_is: bool; [[Internal use: $true if a legacy event.]]
    restart: bool; [[$true if when the event is triggered again from a callback, it should start from where it was]]
}

abstract Efl.Object ()
{
   [[Abstract Efl object class]]
   eo_prefix: efl;

   methods {
      @property parent {
         [[The parent of an object.

           Parents keep references to their children so in order to
           delete objects that have parents you need to set parent to
           NULL or use efl_del() that does that for you (and also unrefs
           the object).

           The Eo parent is conceptually user set. That means that a parent
           should not be changed behind the scenes in a surprising manner.

           For example:
           if you have a widget that has a box internally, and
           when you swallow into that widget the object you swallow ends up in
           the box, the parent should be the widget, and not the box.
         ]]

         set {
         }
         get {
         }
         values {
            parent: Efl.Object @nullable; [[The new parent]]
         }
      }
      del @const {
         [[Unrefs the object and reparents it to NULL.

           Because efl_del() unrefs and reparents to NULL, it doesn't really delete the object.

           This method accepts a const object for convenience, so all objects
           could be passed to it easily.
         ]]
      }
      @property name {
         [[ The name of the object.

           Every object can have a string name. Names may not contain
           the following charactors:
             / ? * [ ] ! \ :
           They are illegal. Using it in a name will result in undefined
           behavior later on. An empty string is considered the same as a
           NULL string or no string for the name at all.
         ]]
         set {
         }
         get {
         }
         values {
           name: string @nullable; [[The name]]
         }
      }
      @property comment {
         [[ A human readable comment for the object

           Every object can have a string comment intended for developers
           and debugging. An empty string is considered the same as a NULL
           string or no string for the comment at all.
         ]]
         set {
         }
         get {
         }
         values {
           comment: string @nullable; [[The comment]]
         }
      }
      debug_name_override {
         [[ Build a read-only name for this object used for debugging.

            Multiple calls using efl_super() can be chained in order to build
            the entire debug name, from parent to child classes. In C the usual
            way to build the string is as follows:

            sb = efl_debug_name_override(efl_super(obj, MY_CLASS), sb);
            eina_strbuf_append_printf(sb, "new_information");
            return sb;

            The receiving function should always either free the strbuf or
            returning it back to the caller, as ownership is transferred.

            @since 1.21
         ]]
         params {
            @in sb: ptr(Eina.Strbuf) @owned; [[A string buffer, must not be $null.]]
         }
         return: ptr(Eina.Strbuf) @owned; [[Should not be $null, may be $sb.]]
      }
      @property event_global_freeze_count @class {
         get {
            [[Return freeze events of object.

              Return event freeze count.
            ]]
         }
         values {
            fcount: int; [[The event freeze count of the object]]
         }
      }
      @property event_freeze_count {
         get {
            [[Return freeze events of object.

              Return event freeze count.
            ]]
         }
         values {
            fcount: int; [[The event freeze count of the object]]
         }
      }
      @property finalized {
         [[True if the object is already finalized, false otherwise.]]
         get {
         }
         values {
            finalized: bool; [[$true if the object is finalized, $false otherwise]]
         }
      }
      provider_find {
        [[Searches up in the object tree for a provider which knows the given class/interface.

          The object from the provider will then be returned.
          The base implementation calls the provider_find function on the object parent,
          and returns its result. If no parent is present NULL is returned.
          Each implementation has to support this function by overriding
          it and returning itself if the interface matches the parameter.
          If this is not done the class cannot be found up in the object tree.
        ]]
        params {
          klass : const(Efl.Object); [[The class identifier to search for]]
        }
        return : Efl.Object; [[Object from the provider list]]
      }
      constructor {
         [[Call the object's constructor.

           Should not be used with #eo_do. Only use it with #eo_do_super.
         ]]
         return: Efl.Object; [[The new object created, can be NULL if aborting]]
      }
      destructor {
         [[Call the object's destructor.

           Should not be used with #eo_do. Only use it with #eo_do_super.
         ]]
      }
      finalize {
         [[Called at the end of #eo_add. Should not be called, just overridden.]]
         return: Efl.Object; [[The new object created, can be NULL if aborting]]
      }
      name_find @const {
         [[Find a child object with the given name and return it.

           The search string can be a glob (shell style, using *). It can also
           specify class name in the format of "class:name" where ":"
           separates class and name. Both class and name can be globs.
           If class is specified, and name is empty like "class:" then
           the search will match any object of that class.
         ]]
         params {
            @in search: string; [[The name search string]]
         }
         return: Efl.Object; [[The first object found]]
      }
      event_thaw {
         [[Thaw events of object.

           Lets event callbacks be called for the object.
         ]]
      }
      event_freeze {
         [[Freeze events of object.

           Prevents event callbacks from being called for the object.
         ]]
      }
      event_global_thaw @class {
         [[Thaw events of object.

           Lets event callbacks be called for the object.
         ]]
      }
      event_global_freeze @class {
         [[Freeze events of object.

           Prevents event callbacks from being called for the object.
         ]]
      }
      event_callback_stop {
         [[Stop the current callback call.

           This stops the current callback call. Any other callbacks for the
           current event will not be called. This is useful when you want to
           filter out events. You just add higher priority events and call this
           on certain conditions to block a certain event.
         ]]
      }
      event_callback_forwarder_add {
         [[Add an event callback forwarder for an event and an object.]]
         params {
            @in desc: ptr(const(Efl.Event.Description)); [[The description of the event to listen to]]
            @in new_obj: Efl.Object; [[The object to emit events from]]
         }
      }
      event_callback_forwarder_del {
         [[Remove an event callback forwarder for an event and an object.]]
         params {
            @in desc: ptr(const(Efl.Event.Description)); [[The description of the event to listen to]]
            @in new_obj: Efl.Object; [[The object to emit events from]]
         }
      }
      children_iterator_new {
         [[Get an iterator on all childrens]]
         return: iterator<Efl.Object> @owned @warn_unused; [[Children iterator]]
      }
      composite_attach {
           [[Make an object a composite object of another.

             The class of comp_obj must be part of the extensions of the class of the parent.
             It is not possible to attach more then 1 composite of the same class.
             This functions also sets the parent of comp_obj to parent.

             See @.composite_detach, @.composite_part_is.
           ]]
           params {
                @in comp_obj: Efl.Object; [[the object that will be used to composite the parent.]]
           }
           return: bool; [[$true if successful. $false otherwise.]]
      }
      composite_detach {
           [[Detach a composite object from another object.

             This functions also sets the parent of comp_obj to $null.

             See @.composite_attach, @.composite_part_is.
           ]]
           params {
                @in comp_obj: Efl.Object; [[The object that will be removed from the parent.]]
           }
           return: bool; [[$true if successful. $false otherwise.]]
      }
      composite_part_is {
           [[Check if an object is part of a composite object.

             See @.composite_attach, @.composite_part_is.
           ]]
           return: bool; [[$true if it is. $false otherwise.]]
      }
   }
   implements {
        class.constructor;
        class.destructor;
   }
   events {
      callback,add @hot; [[A callback was added.]]
      callback,del @hot; [[A callback was deleted.]]
      del @hot; [[Object is being deleted.]]
   }
}

struct Efl.Event {
    [[A parameter passed in event callbacks holding extra event parameters.

      This is the full event information passed to callbacks in C.
    ]]
    object: Efl.Object; [[The object the callback was called on.]]
    desc: const(ptr(Efl.Event.Description)); [[The event description.]]
    info: void_ptr; [[Extra event information passed by the event caller]]
}