`efl.evas.Object` Class¶

class efl.evas.Object(*args, **kwargs)¶

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, the 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.

Warning

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

above¶

The object above this.

Type: efl.evas.Object

above_get()¶

anti_alias¶

If anti-aliased primitives should be used.

Type: bool

anti_alias_get()¶

anti_alias_set(value)¶

below¶

The object below this.

Type: efl.evas.Object

below_get()¶

bottom¶

The bottommost object.

Type: efl.evas.Object

bottom_center¶

Object’s bottom-center coordinates.

Type: (int x, int y)

bottom_center_get()¶

bottom_center_set(x, y)¶

bottom_get()¶

bottom_left¶

Object’s bottom-left corner coordinates.

Type: (int x, int y)

bottom_left_get()¶

bottom_left_set(x, y)¶

bottom_right¶

Object’s bottom-right corner coordinates.

Type: (int x, int y)

bottom_right_get()¶

bottom_right_set(x, y)¶

center¶

Object’s center coordinates.

Type: (int x, int y)

center_get()¶

center_set(x, y)¶

clip¶

Object’s clipper.

Type: efl.evas.Object

clip_get()¶

clip_set(value)¶

clip_unset()¶

clipees¶

Objects that this object clips.

Type: tuple of efl.evas.Object

clipees_get()¶

color¶

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

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

color_get()¶

color_set(r, g, b, a)¶

delete()¶

delete() → None

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

evas_get()¶

event_callback_add(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(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.

event_freeze()¶: Pause event propagation for this object.

event_freeze_count_get()¶

Get the event freeze count for this object.

Returns: the freeze count
Return type: int

event_thaw()¶: Restart event propagation for this object.

focus¶

Whenever object currently have the focus.

Type: bool

focus_get()¶

focus_set(value)¶

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

freeze_events_get()¶

freeze_events_set(freeze)¶

geometry¶

Object’s position and size.

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

geometry_get()¶

geometry_set(x, y, w, h)¶

hide()¶
hide() → None: Hide the object.

is_deleted()¶

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

Returns: True if the object has been deleted yet, False otherwise.
Return type: bool

is_frame_object¶

Type: bool

is_frame_object_get()¶

is_frame_object_set(is_frame)¶

key_grab(keyname, modifiers, not_modifiers, exclusive)¶

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

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(keyname, modifiers, not_modifiers)¶

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

layer_get()¶

layer_set(layer)¶

left_center¶

The coordinates of the left-center position.

Type: (int x, int y)

left_center_get()¶

left_center_set(x, y)¶

lower()¶: Lower to the bottom of its layer.

map¶

Map

Type: Map

map_enabled¶

Map enabled state

Type: bool

map_enabled_get()¶

map_enabled_set(enabled)¶

map_get()¶

map_set(m)¶

move(x, y)¶

Same as assigning to pos.

Parameters

x (int) –
y (int) –

move_relative(dx, dy)¶

Move relatively to objects current position.

Parameters

dx (int) –
dy (int) –

name¶

Object name or None.

Type: string

name_get()¶

name_set(value)¶

on_changed_size_hints_add(func, *a, **k)¶: Same as event_callback_add(EVAS_CALLBACK_CHANGED_SIZE_HINTS, …)

on_changed_size_hints_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_CHANGED_SIZE_HINTS, …)

on_del_add(func, *a, **k)¶

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(func)¶: Same as event_callback_del(EVAS_CALLBACK_DEL, …)

on_focus_in_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_FOCUS_IN, …)

Expected signature:

function(object, *args, **kargs)

on_focus_in_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_FOCUS_IN, …)

on_focus_out_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_FOCUS_OUT, …)

Expected signature:

function(object, *args, **kargs)

on_focus_out_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_FOCUS_OUT, …)

on_free_add(func, *a, **k)¶

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(func)¶: Same as event_callback_del(EVAS_CALLBACK_FREE, …)

on_hide_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_HIDE, …)

Expected signature:

function(object, *args, **kargs)

on_hide_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_HIDE, …)

on_hold_add(func, *a, **k)¶: Same as event_callback_add(EVAS_CALLBACK_HOLD, …)

on_hold_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_HOLD, …)

on_key_down_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_KEY_DOWN, …)

Expected signature:

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

on_key_down_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_KEY_DOWN, …)

on_key_up_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_KEY_UP, …)

Expected signature:

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

on_key_up_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_KEY_UP, …)

on_mouse_down_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOUSE_DOWN, …)

Expected signature:

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

on_mouse_down_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOUSE_DOWN, …)

on_mouse_in_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOUSE_IN, …)

Expected signature:

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

on_mouse_in_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOUSE_IN, …)

on_mouse_move_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOUSE_MOVE, …)

Expected signature:

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

on_mouse_move_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOUSE_MOVE, …)

on_mouse_out_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOUSE_OUT, …)

Expected signature:

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

on_mouse_out_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOUSE_OUT, …)

on_mouse_up_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOUSE_UP, …)

Expected signature:

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

on_mouse_up_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOUSE_UP, …)

on_mouse_wheel_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOUSE_WHEEL, …)

Expected signature:

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

on_mouse_wheel_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOUSE_WHEEL, …)

on_move_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_MOVE, …)

Expected signature:

function(object, *args, **kargs)

on_move_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_MOVE, …)

on_resize_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_RESIZE, …)

Expected signature:

function(object, *args, **kargs)

on_resize_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_RESIZE, …)

on_restack_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_RESTACK, …)

Expected signature:

function(object, *args, **kargs)

on_restack_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_RESTACK, …)

on_show_add(func, *a, **k)¶

Same as event_callback_add(EVAS_CALLBACK_SHOW, …)

Expected signature:

function(object, *args, **kargs)

on_show_del(func)¶: Same as event_callback_del(EVAS_CALLBACK_SHOW, …)

paragraph_direction¶

This handles text paragraph direction of the object.

Even if the object is not textblock or text, its smart child objects can inherit the paragraph direction from the object.

The default paragraph direction is EVAS_BIDI_DIRECTION_INHERIT.

Type: Evas_BiDi_Direction

New in version 1.17.

parent¶

The parent object

Type: Eo

parent_get()¶

parent_set(parent)¶

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

pass_events_get()¶

pass_events_set(value)¶

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

pointer_mode_get()¶

pointer_mode_set(value)¶

pos¶

Object’s position on the X and Y coordinates.

Type: (int x, int y)

pos_get()¶

pos_set(x, 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.

precise_is_inside_get()¶

precise_is_inside_set(precise)¶

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

propagate_events_get()¶

propagate_events_set(value)¶

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

render_op_get()¶

render_op_set(value)¶

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

repeat_events_get()¶

repeat_events_set(value)¶

resize(w, 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)

right_center_get()¶

right_center_set(x, 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.

scale_get()¶

scale_set(scale)¶

show()¶
show() → None: Show the object.

size¶

Object’s size (width and height).

Type: (int w, int h)

size_get()¶

size_hint_align¶

The hints for an object’s alignment.

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

These are hints on how to align an object inside the boundaries of a container/manager. Accepted values are in the 0.0 to 1.0 range, with the special value EVAS_HINT_FILL used to specify “justify” or “fill” by some users. In this case, maximum size hints should be enforced with higher priority, if they are set. Also, any padding hint set on objects should add up to the alignment space on the final scene composition.

For the horizontal component, 0.0 means to the left, 1.0 means to the right. Analogously, for the vertical component, 0.0 to the top, 1.0 means to the bottom.

Note

Default alignment hint values are 0.5, for both axis.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type: (float x, float y)

See also

Size Hints

size_hint_align_get()¶

size_hint_align_set(x, y)¶

size_hint_aspect¶

The hints for an object’s aspect ratio.

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.

If any of the given aspect ratio terms are 0, the object’s container will ignore the aspect and scale the object to occupy the whole available area, for any given policy.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

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

Note

Smart objects (such as elementary) can have their own size hint policy. So calling this API may or may not affect the size of smart objects.

size_hint_aspect_get()¶

size_hint_aspect_set(aspect, w, 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.

This can be used for objects display mode like compress or expand.

Type: Evas_Display_Mode

size_hint_display_mode_get()¶

size_hint_display_mode_set(dispmode)¶

size_hint_expand¶

Hint about expand.

This is just a convenience property to make it easier to understand that weight is also used for expand properties. This is exactly the same as using size_hint_weight

Type: (float x, float y)

See also

Size Hints

New in version 1.13.

size_hint_expand_get()¶

size_hint_expand_set(x, y)¶

size_hint_fill¶

Hint about fill.

This is just a convenience property to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align). This is exactly the same as using size_hint_align

Type: (float x, float y)

See also

Size Hints

New in version 1.13.

size_hint_fill_get()¶

size_hint_fill_set(x, y)¶

size_hint_max¶

The hints for an object’s maximum size.

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

Values -1 will be treated as unset hint components, when queried by managers.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type: (int w, int h)

Note

Smart objects(such as elementary) can have their own size hint policy. So calling this API may or may not affect the size of smart objects.

size_hint_max_get()¶

size_hint_max_set(w, h)¶

size_hint_min¶

Hints for an object’s minimum size.

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

Values 0 will be treated as unset hint components, when queried by managers.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type: (int w, int h)

Note

Smart objects (such as elementary) can have their own size hint policy. So calling this API may or may not affect the size of smart objects.

size_hint_min_get()¶

size_hint_min_set(w, h)¶

size_hint_padding¶

The hints for an object’s padding space.

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

Padding is extra space an object takes on each of its delimiting rectangle sides, in canvas units. This space will be rendered transparent.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

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

Note

Smart objects(such as elementary) can have their own size hint policy. So calling this API may or may not affect the size of smart objects.

size_hint_padding_get()¶

size_hint_padding_set(l, r, t, b)¶

size_hint_request¶

The hints for an object’s optimum 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)

Note

Smart objects(such as elementary) can have their own size hint policy. So calling this API may or may not affect the size of smart objects.

size_hint_request_get()¶

size_hint_request_set(w, 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.

This is a hint on how a container object should resize a given child within its area. Containers may adhere to the simpler logic of just expanding the child object’s dimensions to fit its own (see the EVAS_HINT_EXPAND helper weight macro) or the complete one of taking each child’s weight hint as real weights to how much of its size to allocate for them in each axis. A container is supposed to, after normalizing the weights of its children (with weight hints), distribute the space it has to layout them by those factors – most weighted children get larger in this process than the least ones.

Accepted values are zero or positive values. Some users might use this hint as a boolean, but some might consider it as a proportion, see documentation of possible users, which in Evas are the Box and Table smart objects.

Note

Default weight hint values are 0.0, for both axis.

When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be emitted.

Type: (float x, float y)

See also

Size Hints

size_hint_weight_get()¶

size_hint_weight_set(x, y)¶

size_set(w, h)¶

smart_member_add(parent)¶

Set this object as a member of the parent 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 this object is already member of another SmartObject, it will be deleted from that membership and added to the given object.

smart_member_del()¶: Removes this object as a member of a smart object.

smart_parent¶

Object that this object is member of, or None.

Type: efl.evas.Object

Changed in version 1.14: This was renamed from parent as it was clashing with efl.eo.Eo.parent_get() and is more correct in regards to C api naming.

smart_parent_get()¶

stack_above(above)¶

Reorder to be above the given one.

Parameters: above (efl.evas.Object) –

stack_below(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

static_clip_get()¶

static_clip_set(value)¶

top¶

The topmost object.

Type: efl.evas.Object

top_center¶

The coordinates of the top-center position.

Type: (int x, int y)

top_center_get()¶

top_center_set(x, y)¶

top_get()¶

top_left¶

Object’s top-left corner coordinates.

Type: (int x, int y)

top_left_get()¶

top_left_set(x, y)¶

top_right¶

Object’s top-right corner coordinates.

Type: (int x, int y)

top_right_get()¶

top_right_set(x, y)¶

visible¶

Whenever it’s visible or not.

Type: bool

visible_get()¶

visible_set(spec)¶

`efl.evas.Object` Class¶

Previous topic

Next topic

efl.evas.Object Class¶

`efl.evas.Object` Class¶