efl.evas.Object Class

class efl.evas.Object

Bases: efl.eo.Eo

Basic Graphical Object (or actor).

Objects are managed by Canvas in a non- immediate way, that is, all operations, like moving, resizing, changing the color, etc will not trigger immediate repainting, instead it will save the new state and mark both this object and its Canvas as “dirty” so can be redrawn on Canvas.render() (usually called by the underlying system, when you’re entering idle. This means that doesn’t matter how many times you’re moving an object between frame updates: just the last state will be used, that’s why you really should do animations using Animator() instead of Timer, since it will call registered functions in one batch and then trigger redraw, instead of calling one function, then redraw, then the next function, and redraw...

The most important concept for evas object is clipping (clip), usually done by use of Rectangle as clipper. Clip objects will affect the drawing behavior:

• Limiting visibility
• Limiting geometry
• Modulating color

Clips respects the hierarchy: the minimum area and the composed color will be used used at the end, if one object is not visible, othe lower objects (clipped by it) will not be visible as well. Clipping is the recommended way of doing fade out/in effect, instead of changing object’s color, clip it to a rectangle and change its color: this will work as expected with every object, unlike directly changing color that just work for Images

As with every evas component, colors should be specified in pre-multiplied format, see efl.evas.color_parse() and efl.evas.color_argb_premul().

Objects can be grouped by means of SmartObject, a virtual class that can have it’s methods implemented in order to apply methods to its children.

Attention

Since we have two systems controlling object’s life (Evas and Python) objects need to be explicitly deleted using delete() call. If this call is not issued, the Python object will not be released, but if the object is deleted by Evas (ie: due parent deletion), the object will become “shallow” and all operations will either have no effect or raise exceptions. You can be notified of object deletion by EVAS_CALLBACK_FREE

See also

efl.evas.Object.on_free_add() efl.evas.Object.event_callback_add()

above

The object above this.

Type :efl.evas.Object

anti_alias

If anti-aliased primitives should be used.

Type :bool

below

The object below this.

Type :efl.evas.Object

bottom

The bottommost object.

Type :efl.evas.Object

bottom_center

Object’s bottom-center coordinates.

Type :(int x, int y)

bottom_left

Object’s bottom-left corner coordinates.

Type :(int x, int y)

bottom_right

Object’s bottom-right corner coordinates.

Type :(int x, int y)

center

Object’s center coordinates.

Type :(int x, int y)

clip

Object’s clipper.

Type :efl.evas.Object

clipees

Objects that this object clips.

Type :tuple of efl.evas.Object

color

Object’s (r, g, b, a) color, in pre-multiply colorspace.

Type :(int r, int g, int b, int a)

delete()

Delete object and free it’s internal (wrapped) resources.

Note

after this operation the object will be still alive in Python, but it will be shallow and every operation will have no effect (and may raise exceptions).

Raises ValueError:  if object already deleted.

evas

The evas Canvas that owns this object.

Type :efl.evas.Canvas

event_callback_add(Evas_Callback_Type type, func, *args, **kargs)

Add a new callback for the given event.

Parameters:

• type (int) – an integer with event type code, like EVAS_CALLBACK_MOUSE_IN, EVAS_CALLBACK_KEY_DOWN and other EVAS_CALLBACK_ constants.
• func (function) –

  function to call back, this function will have one of the following signatures:

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

  The former is used by events that provide more data, like EVAS_CALLBACK_MOUSE_, EVAS_CALLBACK_KEY_, while the second is used by events without. Parameters given at the end of event_callback_add() will be given to the callback. Note that the object passed to the callback in event parameter will only be valid during the callback, using it after callback returns will raise an ValueError.

Raises:

• ValueError – if type is unknown.
• TypeError – if func is not callable.

event_callback_del(Evas_Callback_Type type, func)

Remove callback for the given event.

Parameters:

• type (int) – an integer with event type code.
• func (function) – function used with event_callback_add().

Precond :

type and func must be used as parameter for event_callback_add().

Raises ValueError:  

if type is unknown or if there was no func connected with this type.

focus

Whenever object currently have the focus.

Type :bool

freeze_events

Whether an Evas object is to freeze (discard) events.

If True, events will be discarded. Unlike pass_events, events will not be passed to next lower object. This API can be used for blocking events while the object is on transiting.

If False, events will be processed as normal.

Type :bool

See also

pass_events repeat_events propagate_events

geometry

Object’s position and size.

Type :(int x, int y, int w, int h)

hide()

Hide the object.

is_deleted()

Check if the object has been deleted thus leaving the object shallow

is_frame_object

Type :bool

key_grab()

Requests keyname key events be directed to obj.

Parameters:

• keyname – the key to request events for.
• modifiers (Evas_Modifier_Mask) – a mask of modifiers that must be present to trigger the event.
• not_modifiers (Evas_Modifier_Mask) – a mask of modifiers that must not be present to trigger the event.
• exclusive (bool) – request that the obj is the only object receiving the keyname events.

Raises RuntimeError:  

if grabbing the key was unsuccesful

Key grabs allow one or more objects to receive key events for specific key strokes even if other objects have focus. Whenever a key is grabbed, only the objects grabbing it will get the events for the given keys.

keyname is a platform dependent symbolic name for the key pressed (see Evas_Keys for more information).

modifiers and not_modifiers are bit masks of all the modifiers that must and mustn’t, respectively, be pressed along with keyname key in order to trigger this new key grab. Modifiers can be things such as Shift and Ctrl as well as user defined types via evas_key_modifier_add(). Retrieve them with evas_key_modifier_mask_get() or use 0 for empty masks.

exclusive will make the given object the only one permitted to grab the given key. If given EINA_TRUE, subsequent calls on this function with different obj arguments will fail, unless the key is ungrabbed again.

Warning

Providing impossible modifier sets creates undefined behavior

See :evas_object_key_ungrab See :evas_object_focus_set See :evas_object_focus_get See :evas_focus_get See :evas_key_modifier_add

key_ungrab()

Removes the grab on keyname key events by obj.

Parameters:

• keyname – the key the grab is set for.
• modifiers – a mask of modifiers that must be present to trigger the event.
• not_modifiers – a mask of modifiers that must not not be present to trigger the event.

Removes a key grab on obj if keyname, modifiers, and not_modifiers match.

See :evas_object_key_grab See :evas_object_focus_set See :evas_object_focus_get See :evas_focus_get

layer

Object’s layer number.

Type :int

left_center

The coordinates of the left-center position.

Type :(int x, int y)

lower()

Lower to the bottom of its layer.

map

Map

Type :Map

map_enabled

Map enabled state

Type :bool

move(int x, int y)

Same as assigning to pos.

Parameters:

• x (int) –
• y (int) –

move_relative(int dx, int dy)

Move relatively to objects current position.

Parameters:

• dx (int) –
• dy (int) –

name

Object name or None.

Type :string

on_changed_size_hints_add()

Same as event_callback_add(EVAS_CALLBACK_CHANGED_SIZE_HINTS, ...)

on_changed_size_hints_del()

Same as event_callback_del(EVAS_CALLBACK_CHANGED_SIZE_HINTS, ...)

on_del_add()

Same as event_callback_add(EVAS_CALLBACK_DEL, ...)

This is called before freeing object resources (see EVAS_CALLBACK_FREE).

Expected signature:

function(object, *args, **kargs)

on_del_del()

Same as event_callback_del(EVAS_CALLBACK_DEL, ...)

on_focus_in_add()

Same as event_callback_add(EVAS_CALLBACK_FOCUS_IN, ...)

Expected signature:

function(object, *args, **kargs)

on_focus_in_del()

Same as event_callback_del(EVAS_CALLBACK_FOCUS_IN, ...)

on_focus_out_add()

Same as event_callback_add(EVAS_CALLBACK_FOCUS_OUT, ...)

Expected signature:

function(object, *args, **kargs)

on_focus_out_del()

Same as event_callback_del(EVAS_CALLBACK_FOCUS_OUT, ...)

on_free_add()

Same as event_callback_add(EVAS_CALLBACK_FREE, ...)

This is called after freeing object resources (see EVAS_CALLBACK_DEL).

Expected signature:

function(object, *args, **kargs)

on_free_del()

Same as event_callback_del(EVAS_CALLBACK_FREE, ...)

on_hide_add()

Same as event_callback_add(EVAS_CALLBACK_HIDE, ...)

Expected signature:

function(object, *args, **kargs)

on_hide_del()

Same as event_callback_del(EVAS_CALLBACK_HIDE, ...)

on_hold_add()

Same as event_callback_add(EVAS_CALLBACK_HOLD, ...)

on_hold_del()

Same as event_callback_del(EVAS_CALLBACK_HOLD, ...)

on_key_down_add()

Same as event_callback_add(EVAS_CALLBACK_KEY_DOWN, ...)

Expected signature:

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

on_key_down_del()

Same as event_callback_del(EVAS_CALLBACK_KEY_DOWN, ...)

on_key_up_add()

Same as event_callback_add(EVAS_CALLBACK_KEY_UP, ...)

Expected signature:

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

on_key_up_del()

Same as event_callback_del(EVAS_CALLBACK_KEY_UP, ...)

on_mouse_down_add()

Same as event_callback_add(EVAS_CALLBACK_MOUSE_DOWN, ...)

Expected signature:

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

on_mouse_down_del()

Same as event_callback_del(EVAS_CALLBACK_MOUSE_DOWN, ...)

on_mouse_in_add()

Same as event_callback_add(EVAS_CALLBACK_MOUSE_IN, ...)

Expected signature:

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

on_mouse_in_del()

Same as event_callback_del(EVAS_CALLBACK_MOUSE_IN, ...)

on_mouse_move_add()

Same as event_callback_add(EVAS_CALLBACK_MOUSE_MOVE, ...)

Expected signature:

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

on_mouse_move_del()

Same as event_callback_del(EVAS_CALLBACK_MOUSE_MOVE, ...)

on_mouse_out_add()

Same as event_callback_add(EVAS_CALLBACK_MOUSE_OUT, ...)

Expected signature:

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

on_mouse_out_del()

Same as event_callback_del(EVAS_CALLBACK_MOUSE_OUT, ...)

on_mouse_up_add()

Same as event_callback_add(EVAS_CALLBACK_MOUSE_UP, ...)

Expected signature:

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

on_mouse_up_del()

Same as event_callback_del(EVAS_CALLBACK_MOUSE_UP, ...)

on_mouse_wheel_add()

Same as event_callback_add(EVAS_CALLBACK_MOUSE_WHEEL, ...)

Expected signature:

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

on_mouse_wheel_del()

Same as event_callback_del(EVAS_CALLBACK_MOUSE_WHEEL, ...)

on_move_add()

Same as event_callback_add(EVAS_CALLBACK_MOVE, ...)

Expected signature:

function(object, *args, **kargs)

on_move_del()

Same as event_callback_del(EVAS_CALLBACK_MOVE, ...)

on_resize_add()

Same as event_callback_add(EVAS_CALLBACK_RESIZE, ...)

Expected signature:

function(object, *args, **kargs)

on_resize_del()

Same as event_callback_del(EVAS_CALLBACK_RESIZE, ...)

on_restack_add()

Same as event_callback_add(EVAS_CALLBACK_RESTACK, ...)

Expected signature:

function(object, *args, **kargs)

on_restack_del()

Same as event_callback_del(EVAS_CALLBACK_RESTACK, ...)

on_show_add()

Same as event_callback_add(EVAS_CALLBACK_SHOW, ...)

Expected signature:

function(object, *args, **kargs)

on_show_del()

Same as event_callback_del(EVAS_CALLBACK_SHOW, ...)

parent

Object that this object is member of, or None.

Type :efl.evas.Object

pass_events

Whenever object should ignore and pass events.

If True, this will cause events on it to be ignored. They will be triggered on the next lower object (that is not set to pass events) instead.

Objects that pass events will also not be accounted in some operations unless explicitly required, like efl.evas.Canvas.top_at_xy_get(), efl.evas.Canvas.top_in_rectangle_get(), efl.evas.Canvas.objects_at_xy_get(), efl.evas.Canvas.objects_in_rectangle_get().

Type :bool

pointer_mode

If pointer should be grabbed while processing events.

If EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse is down at this object, events will be restricted to it as source, mouse moves, for example, will be emitted even if outside this object area.

If EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will be emitted just when inside this object area.

The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.

Type :Evas_Object_Pointer_Mode

pos

Object’s position on the X and Y coordinates.

Type :(int x, int y)

precise_is_inside

Set whether to use precise (usually expensive) point collision detection for a given Evas object.

Use this function to make Evas treat objects’ transparent areas as not belonging to it with regard to mouse pointer events. By default, all of the object’s boundary rectangle will be taken in account for them.

Type :bool

Warning

By using precise point collision detection you’ll be making Evas more resource intensive.

propagate_events

Whenever object should propagate events to its parent.

If True, this will cause events on this object to propagate to its efl.evas.SmartObject parent, if it’s a member of one.

Type :bool

raise_()

Raise to the top of its layer.

rect

A rectangle representing the object’s geometry.

Rectangles have useful operations like clip, clamp, union and also provides various attributes like top_left, center_x, ...

Note

The rectangle you receive is a snapshot of current state, it is not synchronized to the object, so modifying attributes WILL NOT change the object itself! You must assign it back to this property to update object information.

Type :efl.evas.Rect

render_op

Render operation used at drawing.

Type :Evas_Render_Op

repeat_events

Whenever object should process and then repeat events.

If True, this will cause events on it to be processed but then they will be triggered on the next lower object (that is not set to pass events).

Type :bool

resize(int w, int h)

Same as assigning to size.

Parameters:

• w (int) – Width.
• h (int) – Height.

right_center

The coordinates of the right-center position.

Type :(int x, int y)

scale

The scaling factor for an Evas object. Does not affect all objects.

Value of 1.0 means no scaling, default size.

This will multiply the object’s dimension by the given factor, thus altering its geometry (width and height). Useful when you want scalable UI elements, possibly at run time.

Type :double

Note

Only text and textblock objects have scaling change handlers. Other objects won’t change visually on this call.

show()

Show the object.

size

Object’s size (width and height).

Type :(int w, int h)

size_hint_align

Hint about alignment.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

Accepted values are in the 0.0 to 1.0 range, with the special value -1.0 used to specify”justify” or “fill” by some users. See documentation of possible users.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(double x, double y)

size_hint_aspect

Hint about aspect.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

Aspect EVAS_ASPECT_CONTROL_NONE is disabled.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(Evas_Aspect_Control aspect, int w, int h)

size_hint_display_mode

The hints for an object’s display mode

This is not a size enforcement in any way, it’s just a hint that can be used whenever appropriate. This mode can be used objects display mode like compress or expand.

Type :Evas_Display_Mode

size_hint_max

Hint about maximum size.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

Value -1 is disabled.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(int w, int h)

size_hint_min

Hint about minimum size.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

Value 0 is disabled.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(int w, int h)

size_hint_padding

Hint about padding.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(int l, int r, int t, int b)

size_hint_request

Hint about request size.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

Value 0 is disabled.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(int w, int h)

size_hint_weight

Hint about weight.

This is not an enforcement, just a hint that can be used by other objects like Edje, boxes, tables and others.

Value 0.0 is disabled.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type :(double x, double y)

stack_above(Object above)

Reorder to be above the given one.

Parameters:above (efl.evas.Object) –

stack_below(Object below)

Reorder to be below the given one.

Parameters:below (efl.evas.Object) –

static_clip

A hint flag on the object, whether this is used as a static clipper or not.

Type :bool

top

The topmost object.

Type :efl.evas.Object

top_center

The coordinates of the top-center position.

Type :(int x, int y)

top_left

Object’s top-left corner coordinates.

Type :(int x, int y)

top_right

Object’s top-right corner coordinates.

Type :(int x, int y)

visible

Whenever it’s visible or not.

Type :bool