summaryrefslogtreecommitdiff
path: root/src/lib/evas/canvas/efl_canvas_object.eo
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2019-09-13 12:25:49 +0200
committerXavi Artigas <xavierartigas@yahoo.es>2019-09-13 12:30:03 +0200
commit8c09c1cae8b4368b88ec0b296f124d35e735dc7e (patch)
tree16548e1c5e3c8ac8b51398525da011ab555d4e29 /src/lib/evas/canvas/efl_canvas_object.eo
parent5e9b30153399014ff0aa52922f8460c7769eb741 (diff)
docs: Move property docs to property level instead of set/get
Eolian @properties should be documented at the property level, and documentation at the setter or getter level should be left to setter- or getter-specific comments. There is usually no need at all to have setter- or getter- specific comments. Also, a property is not a method so descriptions should match that. This patch removes lots of duplicated text, and will allow enabling by default the eolian check that ensures that properties have proper property-level docs. No functional changes.
Diffstat (limited to 'src/lib/evas/canvas/efl_canvas_object.eo')
-rw-r--r--src/lib/evas/canvas/efl_canvas_object.eo302
1 files changed, 135 insertions, 167 deletions
diff --git a/src/lib/evas/canvas/efl_canvas_object.eo b/src/lib/evas/canvas/efl_canvas_object.eo
index 103a267..509066c 100644
--- a/src/lib/evas/canvas/efl_canvas_object.eo
+++ b/src/lib/evas/canvas/efl_canvas_object.eo
@@ -84,55 +84,49 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
84 } 84 }
85 } 85 }
86 @property clipper { 86 @property clipper {
87 [[Clip one object to another.
88
89 This property will clip the object $obj to the area occupied
90 by the object $clip. This means the object $obj will only be
91 visible within the area occupied by the clipping object
92 ($clip).
93
94 The color of the object being clipped will be multiplied by
95 the color of the clipping one, so the resulting color for the
96 former will be "RESULT = (OBJ * CLIP) / (255 * 255)", per color
97 element (red, green, blue and alpha).
98
99 Clipping is recursive, so clipping objects may be clipped by
100 others, and their color will in term be multiplied. You may
101 not set up circular clipping lists (i.e. object 1 clips
102 object 2, which clips object 1): the behavior of Evas is
103 undefined in this case.
104
105 Objects which do not clip others are visible in the canvas as
106 normal; those that clip one or more objects become invisible
107 themselves, only affecting what they clip. If an object ceases
108 to have other objects being clipped by it, it will become
109 visible again.
110
111 The visibility of an object affects the objects that are
112 clipped by it, so if the object clipping others is not shown
113 (as in @Efl.Gfx.Entity.visible), the objects clipped by it will
114 not be shown either.
115
116 If $obj was being clipped by another object when this function
117 is called, it gets implicitly removed from the old clipper's
118 domain and is made now to be clipped by its new clipper.
119
120 If $clip is $null, this call will disable clipping for the object
121 i.e. its visibility and color get detached from the previous
122 clipper. If it wasn't, this has no effect.
123
124 Note: Only rectangle and image (masks) objects can be used
125 as clippers. Anything else will result in undefined behaviour.
126 ]]
87 set { 127 set {
88 [[Clip one object to another.
89
90 This function will clip the object $obj to the area occupied
91 by the object $clip. This means the object $obj will only be
92 visible within the area occupied by the clipping object
93 ($clip).
94
95 The color of the object being clipped will be multiplied by
96 the color of the clipping one, so the resulting color for the
97 former will be "RESULT = (OBJ * CLIP) / (255 * 255)", per color
98 element (red, green, blue and alpha).
99
100 Clipping is recursive, so clipping objects may be clipped by
101 others, and their color will in term be multiplied. You may
102 not set up circular clipping lists (i.e. object 1 clips
103 object 2, which clips object 1): the behavior of Evas is
104 undefined in this case.
105
106 Objects which do not clip others are visible in the canvas as
107 normal; those that clip one or more objects become invisible
108 themselves, only affecting what they clip. If an object ceases
109 to have other objects being clipped by it, it will become
110 visible again.
111
112 The visibility of an object affects the objects that are
113 clipped by it, so if the object clipping others is not shown
114 (as in @Efl.Gfx.Entity.visible), the objects clipped by it will
115 not be shown either.
116
117 If $obj was being clipped by another object when this function
118 is called, it gets implicitly removed from the old clipper's
119 domain and is made now to be clipped by its new clipper.
120
121 If $clip is $null, this call will disable clipping for the object
122 i.e. its visibility and color get detached from the previous
123 clipper. If it wasn't, this has no effect.
124
125 Note: Only rectangle and image (masks) objects can be used
126 as clippers. Anything else will result in undefined behaviour.
127 ]]
128 } 128 }
129 get { 129 get {
130 [[Get the object clipping $obj (if any).
131
132 This function returns the object clipping $obj. If $obj is
133 not being clipped at all, $null is returned. The object $obj
134 must be a valid Evas_Object.
135 ]]
136 } 130 }
137 values { 131 values {
138 clipper: Efl.Canvas.Object; [[The object to clip $obj by.]] 132 clipper: Efl.Canvas.Object; [[The object to clip $obj by.]]
@@ -156,27 +150,26 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
156 } 150 }
157 } 151 }
158 @property repeat_events { 152 @property repeat_events {
159 set { 153 [[Whether an Evas object is to repeat events to objects below it.
160 [[Set whether an Evas object is to repeat events.
161 154
162 If $repeat is $true, it will make events on $obj to also be 155 If $repeat is $true, it will make events on $obj to also be
163 repeated for the next lower object in the objects' stack (see 156 repeated for the next lower object in the objects' stack (see
164 see @Efl.Gfx.Stack.below). 157 see @Efl.Gfx.Stack.below).
165 158
166 If $repeat is $false, events occurring on $obj will be 159 If $repeat is $false, events occurring on $obj will be
167 processed only on it. 160 processed only on it.
168 ]] 161 ]]
169 /* FIXME-doc 162 /* FIXME-doc
170 Example: 163 Example:
171 @dontinclude evas-stacking.c 164 @dontinclude evas-stacking.c
172 @skip if (strcmp(ev->key, "r") == 0) 165 @skip if (strcmp(ev->key, "r") == 0)
173 @until } 166 @until }
174 167
175 See the full @ref Example_Evas_Stacking "example". 168 See the full @ref Example_Evas_Stacking "example".
176 */ 169 */
170 set {
177 } 171 }
178 get { 172 get {
179 [[Determine whether an object is set to repeat events.]]
180 } 173 }
181 values { 174 values {
182 repeat: bool; [[Whether $obj is to repeat events ($true) or 175 repeat: bool; [[Whether $obj is to repeat events ($true) or
@@ -248,31 +241,28 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
248 return: bool; [[$true if the seat was removed from the focus list or $false otherwise.]] 241 return: bool; [[$true if the seat was removed from the focus list or $false otherwise.]]
249 } 242 }
250 @property precise_is_inside { 243 @property precise_is_inside {
251 set { 244 [[Whether to use precise (usually expensive) point collision
252 [[Set whether to use precise (usually expensive) point collision 245 detection for a given Evas object.
253 detection for a given Evas object.
254 246
255 Use this function to make Evas treat objects' transparent 247 Use this property to make Evas treat objects' transparent
256 areas as not belonging to it with regard to mouse pointer 248 areas as not belonging to it with regard to mouse pointer
257 events. By default, all of the object's boundary rectangle 249 events. By default, all of the object's boundary rectangle
258 will be taken in account for them. 250 will be taken in account for them.
259
260 Warning: By using precise point collision detection you'll be
261 making Evas more resource intensive.
262 ]]
263 /* FIXME-doc
264 Example code follows.
265 @dontinclude evas-events.c
266 @skip if (strcmp(ev->key, "p") == 0)
267 @until }
268 251
269 See the full example @ref Example_Evas_Events "here". 252 Warning: By using precise point collision detection you'll be
270 */ 253 making Evas more resource intensive.
254 ]]
255 /* FIXME-doc
256 Example code follows.
257 @dontinclude evas-events.c
258 @skip if (strcmp(ev->key, "p") == 0)
259 @until }
260
261 See the full example @ref Example_Evas_Events "here".
262 */
263 set {
271 } 264 }
272 get { 265 get {
273 [[Determine whether an object is set to use precise point
274 collision detection.
275 ]]
276 } 266 }
277 values { 267 values {
278 precise: bool; [[Whether to use precise point collision 268 precise: bool; [[Whether to use precise point collision
@@ -280,27 +270,23 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
280 } 270 }
281 } 271 }
282 @property propagate_events { 272 @property propagate_events {
283 set { 273 [[Whether events on a smart object's member should be
284 [[Set whether events on a smart object's member should be 274 propagated up to its parent.
285 propagated up to its parent.
286 275
287 This function has no effect if $obj is not a member of a 276 This function has no effect if $obj is not a member of a
288 smart object. 277 smart object.
289 278
290 If $prop is $true, events occurring on this object will be 279 If $prop is $true, events occurring on this object will be
291 propagated on to the smart object of which $obj is a member. 280 propagated on to the smart object of which $obj is a member.
292 If $prop is $false, events occurring on this object will not 281 If $prop is $false, events occurring on this object will not
293 be propagated on to the smart object of which $obj is a 282 be propagated on to the smart object of which $obj is a
294 member. The default value is $true. 283 member. The default value is $true.
295 284
296 See also @.repeat_events.set, @.pass_events.set. 285 See also @.repeat_events.set, @.pass_events.set.
297 ]] 286 ]]
287 set {
298 } 288 }
299 get { 289 get {
300 [[Retrieve whether an Evas object is set to propagate events.
301
302 See also @.repeat_events.get, @.pass_events.get.
303 ]]
304 } 290 }
305 values { 291 values {
306 propagate: bool; [[Whether to propagate events ($true) or not 292 propagate: bool; [[Whether to propagate events ($true) or not
@@ -308,24 +294,20 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
308 } 294 }
309 } 295 }
310 @property pass_events { 296 @property pass_events {
311 set { 297 [[Whether an Evas object is to pass (ignore) events.
312 [[Set whether an Evas object is to pass (ignore) events.
313 298
314 If $pass is $true, it will make events on $obj to be ignored. 299 If $pass is $true, it will make events on $obj to be ignored.
315 They will be triggered on the next lower object (that is not 300 They will be triggered on the next lower object (that is not
316 set to pass events), instead (see @Efl.Gfx.Stack.below). 301 set to pass events), instead (see @Efl.Gfx.Stack.below).
317 302
318 If $pass is $false events will be processed on that object 303 If $pass is $false events will be processed on that object
319 as normal. 304 as normal.
320 305
321 See also @.repeat_events.set, @.propagate_events.set 306 See also @.repeat_events.set, @.propagate_events.set
322 ]] 307 ]]
308 set {
323 } 309 }
324 get { 310 get {
325 [[Determine whether an object is set to pass (ignore) events.
326
327 See also @.repeat_events.get, @.propagate_events.get.
328 ]]
329 /* FIXME-doc 311 /* FIXME-doc
330 Example: 312 Example:
331 @dontinclude evas-stacking.c 313 @dontinclude evas-stacking.c
@@ -341,15 +323,12 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
341 } 323 }
342 } 324 }
343 @property anti_alias { 325 @property anti_alias {
326 [[Whether or not the given Evas object is to be drawn
327 anti-aliased.
328 ]]
344 set { 329 set {
345 [[Sets whether or not the given Evas object is to be drawn
346 anti-aliased.
347 ]]
348 } 330 }
349 get { 331 get {
350 [[Retrieves whether or not the given Evas object is to be drawn
351 anti_aliased.
352 ]]
353 } 332 }
354 values { 333 values {
355 anti_alias: bool; [[$true if the object is to be anti_aliased, 334 anti_alias: bool; [[$true if the object is to be anti_aliased,
@@ -357,22 +336,22 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
357 } 336 }
358 } 337 }
359 @property clipped_objects { 338 @property clipped_objects {
339 [[List of objects currently clipped by $obj.
340
341 This returns the internal list handle containing all
342 objects clipped by the object $obj. If none are clipped by
343 it, the call returns $null. This list is only valid until
344 the clip list is changed and should be fetched again with
345 another call to this function if any objects being clipped
346 by this object are unclipped, clipped by a new object,
347 deleted or get the clipper deleted. These operations will
348 invalidate the list returned, so it should not be used
349 anymore after that point. Any use of the list after this
350 may have undefined results, possibly leading to crashes.
351
352 See also @.clipper.
353 ]]
360 get { 354 get {
361 [[Return a list of objects currently clipped by $obj.
362
363 This returns the internal list handle containing all
364 objects clipped by the object $obj. If none are clipped by
365 it, the call returns $null. This list is only valid until
366 the clip list is changed and should be fetched again with
367 another call to this function if any objects being clipped
368 by this object are unclipped, clipped by a new object,
369 deleted or get the clipper deleted. These operations will
370 invalidate the list returned, so it should not be used
371 anymore after that point. Any use of the list after this
372 may have undefined results, possibly leading to crashes.
373
374 See also @.clipper.
375 ]]
376 return: iterator<Efl.Canvas.Object> @no_unused; [[An iterator over the 355 return: iterator<Efl.Canvas.Object> @no_unused; [[An iterator over the
377 list of objects clipped by $obj.]] 356 list of objects clipped by $obj.]]
378 } 357 }
@@ -460,57 +439,46 @@ abstract Efl.Canvas.Object extends Efl.Loop_Consumer implements Efl.Gfx.Entity,
460 } 439 }
461 } 440 }
462 @property no_render { 441 @property no_render {
442 [[Disables all rendering on the canvas.
443
444 This flag will be used to indicate to Evas that this object
445 should never be rendered on the canvas under any
446 circumstances. In particular, this is useful to avoid
447 drawing clipper objects (or masks) even when they don't
448 clip any object. This can also be used to replace the old
449 source_visible flag with proxy objects.
450
451 This is different to the visible property, as even visible
452 objects marked as "no-render" will never appear on screen.
453 But those objects can still be used as proxy sources or
454 clippers. When hidden, all "no-render" objects will
455 completely disappear from the canvas, and hide their
456 clippees or be invisible when used as proxy sources.
457 ]]
463 get { 458 get {
464 [[Returns the state of the "no-render" flag, which means, when
465 true, that an object should never be rendered on the canvas.
466
467 This flag can be used to avoid rendering visible clippers on
468 the canvas, even if they currently don't clip any object.
469 ]]
470 } 459 }
471 set { 460 set {
472 [[Disable all rendering on the canvas.
473
474 This flag will be used to indicate to Evas that this object
475 should never be rendered on the canvas under any
476 circumstances. In particular, this is useful to avoid
477 drawing clipper objects (or masks) even when they don't
478 clip any object. This can also be used to replace the old
479 source_visible flag with proxy objects.
480
481 This is different to the visible property, as even visible
482 objects marked as "no-render" will never appear on screen.
483 But those objects can still be used as proxy sources or
484 clippers. When hidden, all "no-render" objects will
485 completely disappear from the canvas, and hide their
486 clippees or be invisible when used as proxy sources.
487 ]]
488 } 461 }
489 values { 462 values {
490 enable: bool; [[Enable "no-render" mode.]] 463 enable: bool; [[Enable "no-render" mode.]]
491 } 464 }
492 } 465 }
493 @property coords_inside { 466 @property coords_inside {
494 get { 467 [[Whether the coordinates are logically inside the object.
495 [[Returns whether the coords are logically inside the
496 object.
497
498 When this function is called it will return a value of either
499 $false or $true, depending on if the coords are inside the object's
500 current geometry.
501 468
502 A return value of $true indicates the position is logically 469 A value of $true indicates the position is logically
503 inside the object, and $false implies it is logically 470 inside the object, and $false implies it is logically
504 outside the object. 471 outside the object.
505 472
506 If $e is not a valid object, the return value is undefined. 473 If $obj is not a valid object, the return value is undefined.
507 ]] 474 ]]
475 get {
508 } 476 }
509 keys { 477 keys {
510 pos: Eina.Position2D; [[The position in pixels.]] 478 pos: Eina.Position2D; [[The coordinates in pixels.]]
511 } 479 }
512 values { 480 values {
513 return: bool; [[$true if the coords are inside the object, $false otherwise]] 481 return: bool; [[$true if the coordinates are inside the object, $false otherwise]]
514 } 482 }
515 } 483 }
516 gesture_manager_get @beta { 484 gesture_manager_get @beta {