summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKai Huuhko <kai.huuhko@gmail.com>2015-03-09 17:40:34 +0200
committerKai Huuhko <kai.huuhko@gmail.com>2015-03-09 17:40:34 +0200
commit16f04ee2ec91c86dfcbd36c28d727ea4441958c2 (patch)
tree480023dc50dc38449d831a49ffc3ede61c8a2841
parent9dbff82aacc182bf66d9c799641d5b8c8707da4c (diff)
Evas.SmartObject: Move documentation to right places
-rw-r--r--doc/evas/module-evas.rst2
-rw-r--r--efl/evas/efl.evas_object_smart.pxi251
2 files changed, 141 insertions, 112 deletions
diff --git a/doc/evas/module-evas.rst b/doc/evas/module-evas.rst
index d45a78b..c892a33 100644
--- a/doc/evas/module-evas.rst
+++ b/doc/evas/module-evas.rst
@@ -26,4 +26,4 @@ Classes
26.. automodule:: efl.evas 26.. automodule:: efl.evas
27 :exclude-members: Box, Canvas, FilledImage, Grid, Image, Line, Map, Object, 27 :exclude-members: Box, Canvas, FilledImage, Grid, Image, Line, Map, Object,
28 Polygon, Rect, Rectangle, Table, Text, Textblock, 28 Polygon, Rect, Rectangle, Table, Text, Textblock,
29 Textgrid, TextgridCell, SmartObject, ClippedSmartObject 29 Textgrid, TextgridCell, SmartObject, Smart
diff --git a/efl/evas/efl.evas_object_smart.pxi b/efl/evas/efl.evas_object_smart.pxi
index e8127e5..4958a66 100644
--- a/efl/evas/efl.evas_object_smart.pxi
+++ b/efl/evas/efl.evas_object_smart.pxi
@@ -358,11 +358,34 @@ cdef void _smart_callback(void *data, Evas_Object *o, void *event_info) with gil
358 traceback.print_exc() 358 traceback.print_exc()
359 359
360 360
361cdef class Smart: 361cdef class Smart(object):
362
363 """
364 An abstract class with callback methods.
365
366 Use :meth:`free` to delete the instance.
367
368 :param clipped: Make this Smart use a clipped class, ignoring the provided
369 callback methods.
370 :type clipped: bool
371
372 ..
373 note::
374 You should never instantiate the Smart base class directly,
375 but inherit and implement methods, then instantiate this new subclass.
376
377 .. note::
378 Do not call your parent on methods you want to replace the behavior
379 instead of extending it. For example, some methods have default
380 implementation, you may want to remove and replace it with something
381 else.
382
383 .. versionadded:: 1.14
384 """
362 385
363 cdef Evas_Smart *cls 386 cdef Evas_Smart *cls
364 387
365 def __cinit__(self, clipped=False): 388 def __cinit__(self, bint clipped=False):
366 cdef Evas_Smart_Class *cls_def 389 cdef Evas_Smart_Class *cls_def
367 390
368 cls_def = <Evas_Smart_Class*>PyMem_Malloc(sizeof(Evas_Smart_Class)) 391 cls_def = <Evas_Smart_Class*>PyMem_Malloc(sizeof(Evas_Smart_Class))
@@ -399,67 +422,134 @@ cdef class Smart:
399 self.cls = evas_smart_class_new(cls_def) 422 self.cls = evas_smart_class_new(cls_def)
400 Py_INCREF(self) 423 Py_INCREF(self)
401 424
402 def delete(self): 425 def free(self):
426 """Deletes this Smart instance and frees the C resources."""
403 evas_smart_free(self.cls) 427 evas_smart_free(self.cls)
404 self.cls = NULL 428 self.cls = NULL
405 Py_DECREF(self) 429 Py_DECREF(self)
406 430
407 @staticmethod 431 @staticmethod
408 def delete(obj): 432 def delete(obj):
433 """
434 Called in order to remove object from canvas and deallocate its resources.
435
436 Usually you delete object's children here.
437
438 ..
439 *Default implementation deletes all registered children.*
440 """
409 pass 441 pass
410 442
411 @staticmethod 443 @staticmethod
412 def member_add(obj, Object child): 444 def member_add(obj, Object child):
445 """
446 Called when children is added to object.
447
448 ..
449 *Default implementation does nothing.*
450 """
413 pass 451 pass
414 452
415 @staticmethod 453 @staticmethod
416 def member_del(obj, Object child): 454 def member_del(obj, Object child):
455 """
456 Called when children is removed from object.
457
458 ..
459 *Default implementation does nothing.*
460 """
417 pass 461 pass
418 462
419 @staticmethod 463 @staticmethod
420 def move(obj, int x, int y): 464 def move(obj, int x, int y):
465 """
466 Called in order to move object to given position.
467
468 Usually you move children here.
469
470 ..
471 *Default implementation calculates offset and move registered children
472 by it.*
473 """
421 pass 474 pass
422 475
423 @staticmethod 476 @staticmethod
424 def resize(obj, int w, int h): 477 def resize(obj, int w, int h):
478 """
479 Called in order to resize object.
480
481 ..
482 *No default implementation.*
483 """
425 raise NotImplementedError("%s.resize(w, h) not implemented." % obj.__class__.__name__) 484 raise NotImplementedError("%s.resize(w, h) not implemented." % obj.__class__.__name__)
426 485
427 @staticmethod 486 @staticmethod
428 def show(obj): 487 def show(obj):
488 """
489 Called in order to show the given element.
490
491 Usually you call the same function on children.
492
493 ..
494 *No default implementation.*
495 """
429 raise NotImplementedError("%s.show() not implemented." % obj.__class__.__name__) 496 raise NotImplementedError("%s.show() not implemented." % obj.__class__.__name__)
430 497
431 @staticmethod 498 @staticmethod
432 def hide(obj): 499 def hide(obj):
500 """
501 Called in order to hide the given element.
502
503 Usually you call the same function on children.
504
505 ..
506 *No default implementation.*
507 """
433 raise NotImplementedError("%s.hide() not implemented." % obj.__class__.__name__) 508 raise NotImplementedError("%s.hide() not implemented." % obj.__class__.__name__)
434 509
435 @staticmethod 510 @staticmethod
436 def color_set(obj, int r, int g, int b, int a): 511 def color_set(obj, int r, int g, int b, int a):
512 """
513 Called in order to change object color.
514
515 ..
516 *No default implementation.*
517 """
437 raise NotImplementedError("%s.color_set(r, g, b, a) not implemented." % obj.__class__.__name__) 518 raise NotImplementedError("%s.color_set(r, g, b, a) not implemented." % obj.__class__.__name__)
438 519
439 @staticmethod 520 @staticmethod
440 def clip_set(obj, Object clip): 521 def clip_set(obj, Object clip):
522 """
523 Called in order to limit object's visible area.
524
525 ..
526 *No default implementation.*
527 """
441 raise NotImplementedError("%s.clip_set(object) not implemented." % obj.__class__.__name__) 528 raise NotImplementedError("%s.clip_set(object) not implemented." % obj.__class__.__name__)
442 529
443 @staticmethod 530 @staticmethod
444 def clip_unset(obj): 531 def clip_unset(obj):
532 """
533 Called in order to unlimit object's visible area.
534
535 ..
536 *No default implementation.*
537 """
445 raise NotImplementedError("%s.clip_unset() not implemented." % obj.__class__.__name__) 538 raise NotImplementedError("%s.clip_unset() not implemented." % obj.__class__.__name__)
446 539
447 @staticmethod 540 @staticmethod
448 def calculate(obj): 541 def calculate(obj):
542 """
543 Called before object is used for rendering and it is marked as dirty/changed with :py:func:`changed`.
544
545 ..
546 *Default implementation does nothing.*
547 """
449 pass 548 pass
450 549
451 550
452cdef class SmartObjectIterator: 551cdef class SmartObjectIterator:
453 552
454 """Retrieves an iterator of the member objects of a given Evas smart
455 object
456
457 :return: Returns the iterator of the member objects of @p obj.
458
459 .. versionadded:: 1.14
460
461 """
462
463 cdef Eina_Iterator *itr 553 cdef Eina_Iterator *itr
464 554
465 def __cinit__(self, SmartObject obj): 555 def __cinit__(self, SmartObject obj):
@@ -484,104 +574,57 @@ cdef class SmartObjectIterator:
484 574
485cdef class SmartObject(Object): 575cdef class SmartObject(Object):
486 576
487 """Smart Evas Objects. 577 """
578 Smart Evas Objects.
488 579
489 Smart objects are user-defined Evas components, often used to group 580 Smart objects are user-defined Evas components, often used to group
490 multiple basic elements, associate an object with a clip and deal with 581 multiple basic elements, associate an object with a clip and deal with
491 them as an unit. See evas documentation for more details. 582 them as an unit. See evas documentation for more details.
492 583
493 Recommended use is to create an **clipper** object and clip every other 584 ..
494 member to it, then you can have all your other members to be always 585 Recommended use is to create an **clipper** object and clip every other
495 visible and implement :py:func:`hide`, :py:func:`show`, 586 member to it, then you can have all your other members to be always
496 :py:func:`color_set`, :py:func:`clip_set` and :py:func:`clip_unset` to 587 visible and implement :py:func:`hide`, :py:func:`show`,
497 just affect the **clipper**. See :py:class:`ClippedSmartObject`. 588 :py:func:`color_set`, :py:func:`clip_set` and :py:func:`clip_unset` to
589 just affect the **clipper**. See :py:class:`ClippedSmartObject`.
498 590
499 **Pay attention that just creating an object within the SmartObject 591 **Pay attention that just creating an object within the SmartObject
500 doesn't make it a member!** You must do :py:func:`member_add` or use one of 592 doesn't make it a member!** You must do :py:func:`member_add` or use one of
501 the provided factories to ensure that. Failing to do so will leave 593 the provided factories to ensure that. Failing to do so will leave
502 created objects on different layer and no stacking will be done for you. 594 created objects on different layer and no stacking will be done for you.
503 595
504 Behavior is defined by defining the following methods:
505
506 :py:func:`delete`
507 called in order to remove object from canvas and deallocate its
508 resources. Usually you delete object's children here. *Default
509 implementation deletes all registered children.*
510
511 :py:func:`move`
512 called in order to move object to given position. Usually you move
513 children here. *Default implementation calculates offset and move
514 registered children by it.*
515
516 :py:func:`resize`
517 called in order to resize object. *No default implementation.*
518
519 :py:func:`show`
520 called in order to show the given element. Usually you call the same
521 function on children. *No default implementation.*
522
523 :py:func:`hide`
524 called in order to hide the given element. Usually you call the same
525 function on children. *No default implementation.*
526
527 :py:func:`color_set`
528 called in order to change object color. *No default implementation.*
529
530 :py:func:`clip_set`
531 called in order to limit object's visible area. *No default
532 implementation.*
533
534 :py:func:`clip_unset`
535 called in order to unlimit object's visible area. *No default
536 implementation.*
537
538 :py:func:`calculate`
539 called before object is used for rendering and it is marked as
540 dirty/changed with :py:func:`changed`. *Default implementation does
541 nothing.*
542
543 :py:func:`member_add`
544 called when children is added to object. *Default implementation
545 does nothing.*
546
547 :py:func:`member_del`
548 called when children is removed from object. *Default implementation
549 does nothing.*
550
551 .. note::
552 You should never instantiate the SmartObject base class directly,
553 but inherit and implement methods, then instantiate this new subclass.
554
555 .. note:: 596 .. note::
556 If you redefine object's __init__(), you MUST call your parent! 597 If you redefine object's __init__(), you MUST call your parent!
557 Failing to do so will result in objects that just work from Python 598 Failing to do so will result in objects that just work from Python
558 and not from C, for instance, adding your object to Edje swallow 599 and not from C, for instance, adding your object to Edje swallow
559 that clips or set color it will not behave as expected. 600 that clips or set color it will not behave as expected.
560 601
561 .. note::
562 Do not call your parent on methods you want to replace the behavior
563 instead of extending it. For example, some methods have default
564 implementation, you may want to remove and replace it with something
565 else.
566
567
568 :seealso: :py:class:`ClippedSmartObject`
569
570 :param canvas: Evas canvas for this object 602 :param canvas: Evas canvas for this object
571 :type canvas: Canvas 603 :type canvas: :class:`~efl.evas.Canvas`
572 :keyword size: Width and height 604 :param smart: Smart prototype
573 :type size: tuple of ints 605 :type smart: :class:`Smart`
574 :keyword pos: X and Y 606
575 :type pos: tuple of ints 607 ..
576 :keyword geometry: X, Y, width, height 608 :keyword size: Width and height
577 :type geometry: tuple of ints 609 :type size: tuple of ints
578 :keyword color: R, G, B, A 610 :keyword pos: X and Y
579 :type color: tuple of ints 611 :type pos: tuple of ints
580 :keyword name: Object name 612 :keyword geometry: X, Y, width, height
581 :type name: string 613 :type geometry: tuple of ints
582 614 :keyword color: R, G, B, A
615 :type color: tuple of ints
616 :keyword name: Object name
617 :type name: string
618
619 .. versionchanged:: 1.14
620 API was broken because this class had some "hackish" behavior which
621 could no longer be supported because of changes in Cython 0.21.1
622
623 The abstract methods are now in a separate class :class:`Smart` which
624 should be instantiated and passed to this classes constructor as
625 parameter ``smart``
583 """ 626 """
584 def __cinit__(self, *a, **ka): 627 def __cinit__(self):
585 self._smart_callbacks = dict() 628 self._smart_callbacks = dict()
586 629
587 def __dealloc__(self): 630 def __dealloc__(self):
@@ -615,9 +658,7 @@ cdef class SmartObject(Object):
615 # return object_from_instance(evas_object_parent_get(self.obj)) 658 # return object_from_instance(evas_object_parent_get(self.obj))
616 659
617 def member_add(self, Object child): 660 def member_add(self, Object child):
618 """ 661 """Set an evas object as a member of this object.
619
620 Set an evas object as a member of this object.
621 662
622 Members will automatically be stacked and layered with the smart 663 Members will automatically be stacked and layered with the smart
623 object. The various stacking function will operate on members relative 664 object. The various stacking function will operate on members relative
@@ -632,9 +673,7 @@ cdef class SmartObject(Object):
632 673
633 @staticmethod 674 @staticmethod
634 def member_del(Object child): 675 def member_del(Object child):
635 """ 676 """Removes a member object from a smart object.
636
637 Removes a member object from a smart object.
638 677
639 .. attention:: this will actually map to C API as 678 .. attention:: this will actually map to C API as
640 ``evas_object_smart_member_del(child)``, so the object will loose 679 ``evas_object_smart_member_del(child)``, so the object will loose
@@ -698,9 +737,7 @@ cdef class SmartObject(Object):
698 lst.append((func, args, kargs)) 737 lst.append((func, args, kargs))
699 738
700 def callback_del(self, name, func): 739 def callback_del(self, name, func):
701 """callback_del(event, func) 740 """Remove a smart callback.
702
703 Remove a smart callback.
704 741
705 Removes a callback that was added by :py:func:`callback_add()`. 742 Removes a callback that was added by :py:func:`callback_add()`.
706 743
@@ -736,9 +773,7 @@ cdef class SmartObject(Object):
736 evas_object_smart_callback_del(self.obj, name, _smart_callback) 773 evas_object_smart_callback_del(self.obj, name, _smart_callback)
737 774
738 def callback_call(self, name, event_info=None): 775 def callback_call(self, name, event_info=None):
739 """callback_call(event, event_info=None) 776 """Call any smart callbacks for event.
740
741 Call any smart callbacks for event.
742 777
743 :param name: the event name 778 :param name: the event name
744 :param event_info: an event specific info to pass to the callback. 779 :param event_info: an event specific info to pass to the callback.
@@ -755,17 +790,11 @@ cdef class SmartObject(Object):
755 evas_object_smart_callback_call(self.obj, name, <void*>event_info) 790 evas_object_smart_callback_call(self.obj, name, <void*>event_info)
756 791
757 def move_children_relative(self, int dx, int dy): 792 def move_children_relative(self, int dx, int dy):
758 """move_children_relative(int dx, int dy) 793 """Move all children relatively."""
759
760 Move all children relatively.
761
762 """
763 evas_object_smart_move_children_relative(self.obj, dx, dy) 794 evas_object_smart_move_children_relative(self.obj, dx, dy)
764 795
765 def changed(self): 796 def changed(self):
766 """changed() 797 """Mark object as changed, so it's :py:func:`calculate()` will be called.
767
768 Mark object as changed, so it's :py:func:`calculate()` will be called.
769 798
770 If an object is changed and it provides a calculate() method, 799 If an object is changed and it provides a calculate() method,
771 it will be called from :py:func:`Canvas.render()`, what we call pre-render 800 it will be called from :py:func:`Canvas.render()`, what we call pre-render