summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2019-02-11 14:00:04 +0100
committerXavi Artigas <xavierartigas@yahoo.es>2019-02-11 14:16:48 +0100
commit8985222f4798c320e1252e8c59d29169aeb9771f (patch)
tree9441ef378af7c8146155b9c838a2280440847e59
parent1b568327c4feca6ac79863551abf1507bb090c55 (diff)
docs: Update efl_object lifecycle docs
Summary: Explained the different phases, added method refs and removed outdated links. Ref T7557 Reviewers: zmike, bu5hm4n Reviewed By: bu5hm4n Subscribers: cedric, #reviewers, #committers Tags: #efl Maniphest Tasks: T7557 Differential Revision: https://phab.enlightenment.org/D7903
-rw-r--r--src/lib/eo/efl_object.eo163
1 files changed, 108 insertions, 55 deletions
diff --git a/src/lib/eo/efl_object.eo b/src/lib/eo/efl_object.eo
index 5aa1c846d8..a9ac302eee 100644
--- a/src/lib/eo/efl_object.eo
+++ b/src/lib/eo/efl_object.eo
@@ -29,25 +29,54 @@ const Efl.Callback_Priority_After : Efl.Callback_Priority = 100;
29 29
30abstract Efl.Object 30abstract Efl.Object
31{ 31{
32 [[Abstract Efl object class]] 32 [[Abstract EFL object class.
33
34 All EFL objects inherit from this class, which provides basic functionality
35 like naming, debugging, hierarchy traversal, event emission and life cycle
36 management.
37
38 Life Cycle
39 Objects are created with efl_add() and mostly disposed of with efl_del().
40 As an optimization, efl_add() accepts a list of initialization functions
41 which the programmer can use to further customize the object before it is
42 fully constructed.
43 Also, objects can have a parent which will keep them alive as long as the
44 parent is alive, so the programmer does not need to keep track of references.
45 (See the @.parent property for details).
46 Due to the above characteristics, EFL objects undergo the following phases
47 during their Life Cycle:
48 - Construction: The @.constructor method is called. Afterwards, any
49 user-supplied initialization methods are called.
50 - Finalization: The @.finalize method is called and @.finalized is set to
51 $true when it returns. Object is usable at this point.
52 - Invalidation: The object has lost its parent. The @.invalidate method is
53 called so all the object's relationships can be terminated. @.invalidated
54 is set to $true.
55 - Destruction: The object has no parent and it can be destroyed. The
56 @.destructor method is called, use it to return any resources the object
57 might have gathered during its life.
58 ]]
33 eo_prefix: efl; 59 eo_prefix: efl;
34 60
35 methods { 61 methods {
36 @property parent { 62 @property parent {
37 [[The parent of an object. 63 [[The parent of an object.
38 64
39 Parents keep references to their children. In order to 65 Parents keep references to their children and will release these
40 delete objects which have parents you need to set parent to 66 references when destroyed. In this way, objects can be assigned to
41 NULL or use efl_del(). This will both delete & unref 67 a parent upon creation, tying their life cycle so the programmer
42 the object). 68 does not need to worry about destroying the child object.
69 In order to destroy an object before its parent, set the parent to
70 $NULL and use efl_unref(), or use efl_del() directly.
43 71
44 The Eo parent is conceptually user set. That means that a parent 72 The Eo parent is conceptually user set. That means that a parent
45 should not be changed behind the scenes in an unexpected way. 73 should not be changed behind the scenes in an unexpected way.
46 74
47 For example: 75 For example:
48 If you have a widget that has a box internally and 76 If you have a widget which can swallow objects into an internal
49 when you 'swallow' a widget and the swallowed object ends up in 77 box, the parent of the swallowed objects should be the widget, not
50 the box, the parent should be the widget, not the box. 78 the internal box. The user is not even aware of the existence of
79 the internal box.
51 ]] 80 ]]
52 81
53 set { 82 set {
@@ -55,32 +84,31 @@ abstract Efl.Object
55 get { 84 get {
56 } 85 }
57 values { 86 values {
58 parent: Efl.Object @nullable; [[The new parent]] 87 parent: Efl.Object @nullable; [[The new parent.]]
59 } 88 }
60 } 89 }
61 @property name { 90 @property name {
62 [[ The name of the object. 91 [[The name of the object.
63 92
64 Every object can have a string name. Names may not contain 93 Every EFL object can have a name. Names may not contain the
65 the following characters: 94 following characters: / ? * [ ] ! \ :
66 / ? * [ ] ! \ : 95 Using any of these in a name will result in undefined behavior
67 Using any of these in a name will result in undefined 96 later on. An empty string is considered the same as a $NULL string
68 behavior later on. An empty string is considered the same as a 97 or no string for the name.
69 NULL string or no string for the name.
70 ]] 98 ]]
71 set { 99 set {
72 } 100 }
73 get { 101 get {
74 } 102 }
75 values { 103 values {
76 name: string @nullable; [[The name]] 104 name: string @nullable; [[The name.]]
77 } 105 }
78 } 106 }
79 @property comment { 107 @property comment {
80 [[ A human readable comment for the object 108 [[A human readable comment for the object.
81 109
82 Every object can have a string comment. This is intended for developers 110 Every EFL object can have a comment. This is intended for developers
83 and debugging. An empty string is considered the same as a NULL 111 and debugging. An empty string is considered the same as a $NULL
84 string or no string for the comment. 112 string or no string for the comment.
85 ]] 113 ]]
86 set { 114 set {
@@ -88,11 +116,11 @@ abstract Efl.Object
88 get { 116 get {
89 } 117 }
90 values { 118 values {
91 comment: string @nullable; [[The comment]] 119 comment: string @nullable; [[The comment.]]
92 } 120 }
93 } 121 }
94 debug_name_override { 122 debug_name_override {
95 [[ Build a read-only name for this object used for debugging. 123 [[Build a read-only name for this object used for debugging.
96 124
97 Multiple calls using efl_super() can be chained in order to build 125 Multiple calls using efl_super() can be chained in order to build
98 the entire debug name, from parent to child classes. In C the usual 126 the entire debug name, from parent to child classes. In C the usual
@@ -121,7 +149,7 @@ abstract Efl.Object
121 ]] 149 ]]
122 } 150 }
123 values { 151 values {
124 fcount: int; [[The global event freeze count]] 152 fcount: int; [[The global event freeze count.]]
125 } 153 }
126 } 154 }
127 @property event_freeze_count { 155 @property event_freeze_count {
@@ -135,34 +163,36 @@ abstract Efl.Object
135 ]] 163 ]]
136 } 164 }
137 values { 165 values {
138 fcount: int; [[The event freeze count of this object]] 166 fcount: int; [[The event freeze count of this object.]]
139 } 167 }
140 } 168 }
141 @property finalized { 169 @property finalized {
142 [[True if the object is already finalized, otherwise false.]] 170 [[$true if the object has been finalized, i.e. construction has finished.
171 See the Life Cycle section in this class' description.]]
143 get { 172 get {
144 } 173 }
145 values { 174 values {
146 finalized: bool; [[$true if the object is finalized, $false otherwise]] 175 finalized: bool; [[$true if the object is finalized, $false otherwise.]]
147 } 176 }
148 } 177 }
149 @property invalidated { 178 @property invalidated {
150 [[True if the object is already invalidated, otherwise false.]] 179 [[$true if the object has been invalidated, i.e. it has no parent.
180 See the Life Cycle section in this class' description.]]
151 get { 181 get {
152 } 182 }
153 values { 183 values {
154 finalized: bool; [[$true if the object is invalidated, $false otherwise]] 184 finalized: bool; [[$true if the object is invalidated, $false otherwise.]]
155 } 185 }
156 } 186 }
157 @property invalidating { 187 @property invalidating {
158 [[True if the object is about to be invalidated, and the invalidation of the children is already happening. 188 [[$true if the object has started the invalidation phase, but has not
159 189 finished it yet.
160 Note this is true before the invalidate call on the object. 190 Note: This might become $true before @.invalidate is called.
161 ]] 191 See the Life Cycle section in this class' description.]]
162 get { 192 get {
163 } 193 }
164 values { 194 values {
165 invalidating: bool; [[$true if the object is invalidating, $false otherwise]] 195 invalidating: bool; [[$true if the object is invalidating, $false otherwise.]]
166 } 196 }
167 } 197 }
168 provider_find @const { 198 provider_find @const {
@@ -176,30 +206,53 @@ abstract Efl.Object
176 If this is not done the class cannot be found up in the object tree. 206 If this is not done the class cannot be found up in the object tree.
177 ]] 207 ]]
178 params { 208 params {
179 klass : const(Efl.Class); [[The class identifier to search for]] 209 klass : const(Efl.Class); [[The class identifier to search for.]]
180 } 210 }
181 return : Efl.Object; [[Object from the provider list]] 211 return : Efl.Object; [[Object from the provider list.]]
182 } 212 }
183 constructor { 213 constructor {
184 [[Call the object's constructor. 214 [[Implement this method to provide optional initialization code for your object.
185 215
186 Should not be used with #eo_do. Only use it with #eo_do_super. 216 See the Life Cycle section in this class' description.]]
187 ]] 217 return: Efl.Object; [[The new object, can be $NULL if aborted.]]
188 return: Efl.Object; [[The new object created, can be NULL if aborting]]
189 } 218 }
190 destructor { 219 destructor {
191 [[Call the object's destructor. 220 [[Implement this method to provide deinitialization code for your object if you need it.
192 221
193 Should not be used with #efl_do. Only use it with #efl_do_super. 222 Will be called once @.invalidate has returned.
194 Will be triggered once #invalidate and #noref have been triggered. 223 See the Life Cycle section in this class' description.]]
195 ]]
196 } 224 }
197 finalize { 225 finalize {
198 [[Called at the end of efl_add. Should not be called, just overridden.]] 226 [[Implement this method to finish the initialization of your object
199 return: Efl.Object; [[The new object created, can be NULL if aborting]] 227 after all (if any) user-provided configuration methods have been
228 executed.
229
230 Use this method to delay expensive operations until user configuration
231 has finished, to avoid building the object in a "default" state in the
232 constructor, just to have to throw it all away because a user
233 configuration (a property being set, for example) requires a diferent
234 state.
235 This is the last call inside efl_add() and will set @.finalized to $true
236 once it returns.
237 This is an optimization and implementing this method is optional if you
238 already perform all your initialization in the @.constructor method.
239 See the Life Cycle section in this class' description.]]
240 return: Efl.Object; [[The new object. Return $NULL to abort object creation.]]
200 } 241 }
201 invalidate { 242 invalidate {
202 [[Called when parent reference is lost/set to $NULL and switch the state of the object to invalidate.]] 243 [[Implement this method to perform special actions when your object loses
244 its parent, if you need to.
245
246 It is called when the parent reference is lost or set to $NULL. After this
247 call returns, @.invalidated is set to $true.
248 This allows a simpler tear down of complex hierarchies, by performing
249 object destruction in two steps, first all object relationships are
250 broken and then the isolated objects are destroyed. Performing everything
251 in the @.destructor can sometimes lead to deadlocks, but implementing
252 this method is optional if this is not your case.
253 When an object with a parent is destroyed, it first receives a call to
254 @.invalidate and then to @.destructor.
255 See the Life Cycle section in this class' description.]]
203 } 256 }
204 name_find @const { 257 name_find @const {
205 [[Find a child object with the given name and return it. 258 [[Find a child object with the given name and return it.
@@ -211,9 +264,9 @@ abstract Efl.Object
211 the search will match any object of that class. 264 the search will match any object of that class.
212 ]] 265 ]]
213 params { 266 params {
214 @in search: string; [[The name search string]] 267 @in search: string; [[The name search string.]]
215 } 268 }
216 return: Efl.Object; [[The first object found]] 269 return: Efl.Object; [[The first object found.]]
217 } 270 }
218 event_thaw { 271 event_thaw {
219 [[Thaw events of object. 272 [[Thaw events of object.
@@ -334,13 +387,13 @@ abstract Efl.Object
334 In a normal object use case, when ownership of an object is given 387 In a normal object use case, when ownership of an object is given
335 to a caller, said ownership should be released with efl_unref(). 388 to a caller, said ownership should be released with efl_unref().
336 If the object has a parent, this will print error messages, as 389 If the object has a parent, this will print error messages, as
337 $efl_unref() is stealing the ref from the parent. 390 efl_unref() is stealing the ref from the parent.
338 391
339 Warning: Use this function very carefully, unless you're absolutely 392 Warning: Use this function very carefully, unless you're absolutely
340 sure of what you are doing. 393 sure of what you are doing.
341 ]] 394 ]]
342 values { 395 values {
343 allow: bool(false); [[Whether to allow $efl_unref() to zero 396 allow: bool(false); [[Whether to allow efl_unref() to zero
344 even if @.parent is not $null.]] 397 even if @.parent is not $null.]]
345 } 398 }
346 } 399 }
@@ -350,12 +403,12 @@ abstract Efl.Object
350 class.destructor; 403 class.destructor;
351 } 404 }
352 events { 405 events {
353 del @hot: void; [[Object is being deleted.]] 406 del @hot: void; [[Object is being deleted. See @.destructor.]]
354 invalidate @hot: void; [[Object is being invalidated and loosing its parent.]] 407 invalidate @hot: void; [[Object is being invalidated and losing its parent. See @.invalidate.]]
355 noref @hot: void; [[Object has lost its last reference, only parent relationship is keeping it alive.]] 408 noref @hot: void; [[Object has lost its last reference, only parent relationship is keeping it alive. Advanced usage.]]
356 destruct @hot: void; [[Object has been fully destroyed. It can not be used 409 destruct @hot: void; [[Object has been fully destroyed. It can not be used
357 beyond this point. This event should only serve to clean up any 410 beyond this point. This event should only serve to clean up any
358 dangling pointer.]] 411 reference you keep to the object.]]
359 } 412 }
360} 413}
361 414