efl.evas.SmartObject Class

class efl.evas.SmartObject

Bases: efl.evas.Object

Smart Evas Objects.

Smart objects are user-defined Evas components, often used to group multiple basic elements, associate an object with a clip and deal with them as an unit. See evas documentation for more details.

Recommended use is to create an clipper object and clip every other member to it, then you can have all your other members to be always visible and implement hide(), show(), color_set(), clip_set() and clip_unset() to just affect the clipper. See ClippedSmartObject.

Pay attention that just creating an object within the SmartObject doesn’t make it a member! You must do member_add() or use one of the provided factories to ensure that. Failing to do so will leave created objects on different layer and no stacking will be done for you.

Behavior is defined by defining the following methods:

delete()

called in order to remove object from canvas and deallocate its resources. Usually you delete object’s children here. Default implementation deletes all registered children.

move()

called in order to move object to given position. Usually you move children here. Default implementation calculates offset and move registered children by it.

resize()

called in order to resize object. No default implementation.

show()

called in order to show the given element. Usually you call the same function on children. No default implementation.

hide()

called in order to hide the given element. Usually you call the same function on children. No default implementation.

color_set()

called in order to change object color. No default implementation.

clip_set()

called in order to limit object’s visible area. No default implementation.

clip_unset()

called in order to unlimit object’s visible area. No default implementation.

calculate()

called before object is used for rendering and it is marked as dirty/changed with changed(). Default implementation does nothing.

member_add()

called when children is added to object. Default implementation does nothing.

member_del()

called when children is removed from object. Default implementation does nothing.

Note

You should never instantiate the SmartObject base class directly, but inherit and implement methods, then instantiate this new subclass.

Note

If you redefine object’s __init__(), you MUST call your parent! Failing to do so will result in objects that just work from Python and not from C, for instance, adding your object to Edje swallow that clips or set color it will not behave as expected.

Note

Do not call your parent on methods you want to replace the behavior instead of extending it. For example, some methods have default implementation, you may want to remove and replace it with something else.

Seealso :

ClippedSmartObject

Parameters:

• canvas (Canvas) – Evas canvas for this object
• size (tuple of ints) – Width and height
• pos (tuple of ints) – X and Y
• geometry (tuple of ints) – X, Y, width, height
• color (tuple of ints) – R, G, B, A
• name (string) – Object name

Line()

Factory of children Line.

Return type:Line

Rectangle()

Factory of children Rectangle.

Return type:Rectangle

calculate()

Request object to recalculate it’s internal state.

callback_add(event, func, *args, **kargs)

Add a callback for the smart event specified by event.

Parameters:

• event – Event name
• func –

  What to callback. Should have the signature:

  function(object, event_info, *args, **kargs)
  

Raises TypeError:  

if func is not callable.

Warning

event_info will always be a python object, if the signal is provided by a C-only class, it will crash.

callback_call(event, event_info=None)

Call any smart callbacks for event.

Parameters:

• event – the event name
• event_info – an event specific info to pass to the callback.

This should be called internally in the smart object when some specific event has occurred. The documentation for the smart object should include a list of possible events and what type of event_info to expect.

Attention

event_info will always be a python object.

callback_del(event, func)

Remove a smart callback.

Removes a callback that was added by callback_add().

Parameters:

• event – event name
• func – what to callback, should have be previously registered.

Precond :

event and func must be used as parameter for callback_add().

Raises ValueError:  

if there was no func connected with this event.

changed()

Mark object as changed, so it’s calculate() will be called.

If an object is changed and it provides a calculate() method, it will be called from Canvas.render(), what we call pre-render calculate.

This can be used to postpone heavy calculations until you need to display the object, example: layout calculations.

clip_set(Object clip)

Abstract method.

clip_unset()

Abstract method.

color_set(int r, int g, int b, int a)

Abstract method.

delete()

Default implementation to delete all children.

hide()

Abstract method.

member_add(Object child)

Set an evas object as a member of this object.

Members will automatically be stacked and layered with the smart object. The various stacking function will operate on members relative to the other members instead of the entire canvas.

Non-member objects can not interleave a smart object’s members.

Note :if child is already member of another SmartObject, it will be deleted from that membership and added to this object.

member_del(Object child)

Removes a member object from a smart object.

Attention

this will actually map to C API as evas_object_smart_member_del(child), so the object will loose it’s parent event if the object is not part of this object.

members_get() → tuple

Return type:tuple of Object

move(int x, int y)

Default implementation to move all children.

move_children_relative(int dx, int dy)

Move all children relatively.

need_recalculate_get()

Get the current value of need_recalculate flag.

Note

This flag will be unset during the render phase, after calculate() is called if one is provided. If no calculate() is provided, then the flag will be left unchanged after render phase.

need_recalculate_set()

Set need_recalculate flag.

Set the need_recalculate flag of given smart object.

If this flag is set then calculate() callback (method) of the given smart object will be called, if one is provided, during render phase usually evas_render(). After this step, this flag will be automatically unset.

If no calculate() is provided, this flag will be left unchanged.

Note

Just setting this flag will not make scene dirty and evas_render() will have no effect. To do that, use evas_object_smart_changed(), that will automatically call this function with 1 as parameter.

resize(int w, int h)

Abstract method.

show()

Abstract method.

efl.evas.ClippedSmartObject Class

class efl.evas.ClippedSmartObject

Bases: efl.evas.SmartObject

SmartObject subclass that automatically handles an internal clipper.

This class is optimized for the recommended SmartObject usage of having an internal clipper, with all member objects clipped to it and operations like hide(), show(), color_set(), clip_set() and clip_unset() operating on it.

This internal clipper size is huge by default (and not the same as the object size), this means that you should clip this object to another object clipper to get its contents restricted. This is the default because many times what we want are contents that can overflow SmartObject boudaries (ie: members with animations coming in from outside).

Variables:

clipper – the internal object used for clipping. You shouldn’t mess with it.

Todo :

remove current code and wrap C version (now it’s in evas).

Parameters:

• canvas (Canvas) – Evas canvas for this object
• size (tuple of ints) – Width and height
• pos (tuple of ints) – X and Y
• geometry (tuple of ints) – X, Y, width, height
• color (tuple of ints) – R, G, B, A
• name (string) – Object name
• file (string) – File name

clip_set()

Default implementation that acts on the the clipper.

clip_unset()

Default implementation that acts on the the clipper.

color_set()

Default implementation that acts on the the clipper.

hide()

Default implementation that acts on the the clipper.

member_add()

Set an evas object as a member of this object, already clipping.

member_del()

Removes a member object from a smart object, already unsets its clip.

show()

Default implementation that acts on the the clipper.