efl.evas.Image Class

class efl.evas.Image(Canvas canvas, file=None, **kwargs)

Bases: efl.evas.Object

Image from file or buffer.

Introduction

Image will consider the object’s geometry as the area to paint with tiles as described by fill and the real pixels (image data) will be stored as described by image_size. This can be tricky to understand at first, but gives flexibility to do everything.

If an image is loaded from file, it will have image_size set to its original size, unless some other size was set with load_size, load_dpi or load_scale_down.

Pixels will be scaled to match size specified by fill using either sampled or smooth methods, these can be specified with smooth_scale. The scale will consider borders as specified by border and border_center_fill, while the former specify the border dimensions (top and bottom will scale horizontally, while right and left will do vertically, corners are kept unscaled), the latter says whenever the center of the image will be used (useful to create frames).

Contents will be tiled using fill information in order to paint geometry, so if you want an image to be drawn just once, you should match every geometry = x, y, w, h by a call to fill = 0, 0, w, h. FilledImage does that for you.

Pixel data and buffer API

Images implement the Python Buffer API, so it’s possible to use it where buffers are expected (ie: file.write()). Available data will depend on alpha, colorspace and image_size, lines should be considered multiple of stride, with the following considerations about colorspace:

• EVAS_COLORSPACE_ARGB8888: This pixel format is a linear block of

  pixels, starting at the top-left row by row until the bottom right of the image or pixel region. All pixels are 32-bit unsigned int’s with the high-byte being alpha and the low byte being blue in the format ARGB. Alpha may or may not be used by evas depending on the alpha flag of the image, but if not used, should be set to 0xff anyway. This colorspace uses premultiplied alpha. That means that R, G and B cannot exceed A in value. The conversion from non-premultiplied colorspace is:

  R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
  

  So 50% transparent blue will be: 0x80000080. This will not be “dark” - just 50% transparent. Values are 0 == black, 255 == solid or full red, green or blue.

• EVAS_COLORSPACE_RGB565_A5P: In the process of being implemented in

  1 engine only. This may change. This is a pointer to image data for 16-bit half-word pixel data in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), with the high-byte containing red and the low byte containing blue, per pixel. This data is packed row by row from the top-left to the bottom right. If the image has an alpha channel enabled there will be an extra alpha plane after the color pixel plane. If not, then this data will not exist and should not be accessed in any way. This plane is a set of pixels with 1 byte per pixel defining the alpha values of all pixels in the image from the top-left to the bottom right of the image, row by row. Even though the values of the alpha pixels can be 0 to 255, only values 0 through to 31 are used, 31 being solid and 0 being transparent. RGB values can be 0 to 31 for red and blue and 0 to 63 for green, with 0 being black and 31 or 63 being full red, green or blue respectively. This colorspace is also pre-multiplied like EVAS_COLORSPACE_ARGB8888 so:

  R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
  

Note

if an image is resized it will tile it’s contents respecting geometry set by fill, so if you want the contents to be scaled you need to call fill with x=0, y=0, w=new_width, h=new_height, or you should use FilledImage instead.

Parameters

• canvas (Canvas) – Evas canvas for this object

• file (string or tuple) – File name or (File name, key)

• **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

alpha

Enable or disable alpha channel.

Type

bool

alpha_get()

alpha_mask

Enable an image to be used as an alpha mask.

This will set any flags, and discard any excess image data not used as an alpha mask.

Note

There is little point in using a image as alpha mask unless it has an alpha channel.

Type

bool

alpha_mask_set(ismask)

alpha_set(value)

animated

Check if an image object can be animated (have multiple frames)

Type

bool

This returns if the image file of an image object is capable of animation such as an animated gif file might. This is only useful to be called once the image object file has been set.

Example:

obj = Image(mycanvas, file="my_animated_file.gif")

if obj.animated:
    print("This image has %d frames" % (obj.animated_frame_count,))
    print("Frame 1's duration is %f. You had better set object's frame to 2 after this duration using timer." % (obj.animated_frame_duration_get(1, 0)))
    print("Loop count is %d. You had better run loop %d times." % (obj.loop_count, obj.loop_count))

    loop_type = obj.animated_loop_type
    if loop_type == EVAS_IMAGE_ANIMATED_HINT_LOOP:
        print("You had better set frame like 1->2->3->1->2->3...")
    elif loop_type == EVAS_IMAGE_ANIMATED_HINT_PINGPONG:
        print("You had better set frame like 1->2->3->2->1->2...")
    else:
        print("Unknown loop type.")

    obj.animated_frame = 1
    print("You set image objects frame to 1. You can see frame 1.")

animated_frame

Set the frame to current frame of an image object

Type

int

This set image object’s current frame to frame_num with 1 being the first frame.

animated_frame_count

Get the total number of frames of the image object.

Type

int

This returns total number of frames the image object supports (if animated)

animated_frame_count_get()

animated_frame_duration_get(start_frame, fram_num)

Get the duration of a sequence of frames.

Parameters

• start_frame (int) – The first frame

• fram_num (int) – Number of frames in the sequence

Returns

The duration of a sequence of frames.

Return type

double

This returns total duration that the specified sequence of frames should take in seconds.

If you set start_frame to 1 and frame_num 0, you get frame 1’s duration If you set start_frame to 1 and frame_num 1, you get frame 1’s duration + frame2’s duration

animated_frame_set(frame_num)

animated_get()

animated_loop_count

Get the number times the animation of the object loops.

Type

int

This returns loop count of image. The loop count is the number of times the animation will play fully from first to last frame until the animation should stop (at the final frame).

If 0 is returned, then looping should happen indefinitely (no limit to the number of times it loops).

animated_loop_count_get()

animated_loop_type

Get the kind of looping the image object does.

Type

Evas_Image_Animated_Loop_Hint

This returns the kind of looping the image object wants to do.

If it returns EVAS_IMAGE_ANIMATED_HINT_LOOP, you should display frames in a sequence like: 1->2->3->1->2->3->1… If it returns EVAS_IMAGE_ANIMATED_HINT_PINGPONG, it is better to display frames in a sequence like: 1->2->3->2->1->2->3->1…

The default type is EVAS_IMAGE_ANIMATED_HINT_LOOP.

animated_loop_type_get()

border

How much of each border is not to be scaled.

When rendering, the image may be scaled to fit the size of the image object. This property reflects what area around the border of the image is not to be scaled. This is useful for widget theming, where, for example, buttons may be of varying sizes, but the border size must remain constant.

Type

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

border_center_fill

If the center part of an image (not the border) should be drawn

See also

border

When rendering, the image may be scaled to fit the size of the image object. This property reflects if the center part of the scaled image is to be drawn or left completely blank. Very useful for frames and decorations.

Type

bool

border_center_fill_get()

border_center_fill_set(value)

border_get()

border_scale

The scaling factor (multiplier) for the borders of an image object.

Default is 1.0 - i.e. no scaling

Type

double

See

border

border_scale_get()

border_scale_set(scale)

border_set(left, right, top, bottom)

colorspace

The colorspace of image data (pixels).

May be one of (subject to engine implementation):

• EVAS_COLORSPACE_ARGB8888 ARGB 32 bits per pixel, high-byte is

  Alpha, accessed 1 32bit word at a time.

Type

Evas_Colorspace

colorspace_get()

colorspace_set(value)

content_hint

The content hint value of the given image of the canvas.

For example, if you’re on the GL engine and your driver implementation supports it, setting this hint to EVAS_IMAGE_CONTENT_HINT_DYNAMIC will make it need zero copies at texture upload time, which is an “expensive” operation.

Type

Evas_Image_Content_Hint

content_hint_get()

content_hint_set(hint)

file

Set the image to display a file.

Type

unicode filename or (unicode filename, unicode key)

Raises

EvasLoadError – on load error.

file_get()

file_set(filename, key=None)

fill

The rectangle that the image will be drawn to.

Note that the image will be tiled around this one rectangle. To have only one copy of the image drawn, x and y must be 0 and w and h need to be the width and height of the object respectively.

The default values for the fill parameters is x = 0, y = 0, w = 1 and h = 1.

Type

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

fill_get()

fill_set(x, y, w, h)

fill_spread

The tiling mode for the given evas image object’s fill.

One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT, EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.

Type

Evas_Fill_Spread

fill_spread_get()

fill_spread_set(spread)

filled

Whether the image object’s fill property should track the object’s size.

If True, then every efl.evas.Object.resize() will automatically assign a value to fill with the that new size (and 0, 0 as source image’s origin), so the bound image will fill the whole object’s area.

Type

bool

See also

FilledImage

filled_get()

filled_set(setting)

image_data_set(buf)

Sets the raw image data.

The given buffer will be copied, so it’s safe to give it a temporary object.

Note

that the raw data must be of the same size and colorspace of the image. If data is None the current image data will be freed.

Parameters

buf – The buffer

image_data_update_add(x, y, w, h)

Mark a sub-region of the image to be redrawn.

This function schedules a particular rectangular region to be updated (redrawn) at the next render.

Parameters

• x (int) – X coordinate

• y (int) – Y coordinate

• w (int) – Width

• h (int) – Height

image_size

The size of the image to be displayed.

Assigning to this property will scale down or crop the image so that it is treated as if it were at the given size. If the size given is smaller than the image, it will be cropped. If the size given is larger, then the image will be treated as if it were in the upper left hand corner of a larger image that is otherwise transparent.

This will force pixels to be allocated if they weren’t, so you should use this before accessing the image as a buffer in order to allocate the pixels.

This will recalculate stride based on width and the colorspace.

Type

(int w, int h)

image_size_get()

image_size_set(w, h)

load_dpi

Dots-per-inch to be used at image load time.

Type

double

load_dpi_get()

load_dpi_set(value)

load_error

The load error.

Type

int

load_error_get()

load_head_skip

A load option to skip initial header load and defer to preload

This is meant to be used in conjunction with evas_object_image_file_set() and evas_object_image_preload() by deferring any header loading until a evas_object_image_preload() is issued making the file file set simply set up the file to refer to without any validation of its type or file existence or even inspecting the image header to get size or alpha channel flags etc. All of this will then be done as part of the preload stage.

Type

bool

New in version 1.19.

load_head_skip_get()

load_head_skip_set(value)

load_orientation

Define if the orientation information in the image file should be honored.

Type

bool

load_orientation_get()

load_orientation_set(enable)

load_region

Inform a given image object to load a selective region of its source image.

Type

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

This is useful when one is not showing all of an image’s area on its image object.

Note

The image loader for the image format in question has to support selective region loading in order to this function to take effect.

load_region_get()

load_region_set(x, y, w, h)

load_scale_down

Scale down loaded image by the given amount.

Type

int

load_scale_down_get()

load_scale_down_set(value)

load_size

The size you want image loaded.

Loads image to the desired size, saving memory when loading large files.

Type

(int w, int h)

load_size_get()

load_size_set(w, h)

on_image_preloaded_add(func, *a, **k)

Same as event_callback_add(EVAS_CALLBACK_IMAGE_PRELOADED, …)

on_image_preloaded_del(func)

Same as event_callback_del(EVAS_CALLBACK_IMAGE_PRELOADED, …)

on_image_unloaded_add(func, *a, **k)

Same as event_callback_add(EVAS_CALLBACK_IMAGE_UNLOADED, …)

on_image_unloaded_del(func)

Same as event_callback_del(EVAS_CALLBACK_IMAGE_UNLOADED, …)

orient

The image orientation.

This allows to rotate or flip the image.

Type

Evas_Image_Orient

New in version 1.14.

orient_get()

orient_set(orient)

pixels_dirty

Mark or unmark pixels as dirty.

Type

bool

pixels_dirty_get()

pixels_dirty_set(value)

preload(cancel=0)

Preload image data asynchronously.

This will request Evas to create a thread to load image data from file, decompress and convert to pre-multiplied format used internally.

This will emit EVAS_CALLBACK_IMAGE_PRELOADED event callback when it is done, see on_image_preloaded_add().

If one calls this function with cancel=True, then preload will be canceled and load will happen when image is made visible.

If image is required before preload is done (ie: pixels are retrieved by user or when drawing), then it will be automatically canceled and load will be synchronous.

Parameters

cancel (bool) – if True, will cancel preload request.

region_support

Region support state

Type

bool

region_support_get()

reload()

Force reload of image data.

save(filename, key=None, flags=None)

Save image to file.

Parameters

• filename (unicode) – where to save.

• key (unicode) – some formats may require a key, EET for example.

• flags (unicode) – string of extra flags (separated by space), like “quality=85 compress=9”.

scale_hint

The scale hint value of the image object in the canvas, which will affect how Evas is to cache scaled versions of its original source image.

Type

Evas_Image_Scale_Hint

scale_hint_get()

scale_hint_set(hint)

smooth_scale

Enable or disable smooth scaling.

Type

bool

smooth_scale_get()

smooth_scale_set(value)

source

The source object on an image object to used as a proxy.

If an image object is set to behave as a proxy, it will mirror the rendering contents of a given source object in its drawing region, without affecting that source in any way. The source must be another valid Evas object. Other effects may be applied to the proxy, such as a map (see evas_object_map_set()) to create a reflection of the original object (for example).

Any existing source object on obj will be removed after this call. Setting src to NULL clears the proxy object (not in “proxy state” anymore).

Type

Object

Raises

RuntimeError – if source could not be (un)set.

Warning

You cannot set a proxy as another proxy’s source.

See also

source_visible

source_events

Whether an Evas object is to repeat events to source.

If True, it will make events on the object to also be repeated for the source object. When the object and source geometries are different, the event position will be transformed to the source object’s space.

If False, events occurring on the object will be processed only on it.

Type

bool

See also

source source_visible

New in version 1.8.

source_events_get()

source_events_set(source)

source_get()

source_set(src)

source_unset()

source_visible

Whether the source object is visible or not.

If set to False, the source object of the proxy will be invisible.

This API works differently to show() and hide(). Once source object is hidden by hide() then the proxy object will be hidden as well. Actually in this case both objects are excluded from the Evas internal update circle.

By this API, instead, one can toggle the visibility of a proxy’s source object remaining the proxy visibility untouched.

Type

bool

Warning

If the all of proxies are deleted, then the source visibility of the source object will be cancelled.

See also

source

New in version 1.8.

source_visible_get()

source_visible_set(visible)

stride

Get the row stride (in pixels) being used to draw this image.

While image have logical dimension of width and height set by image_size, the line can be a bit larger than width to improve memory alignment.

The amount of bytes will change based on colorspace, while using ARGB8888 it will be multiple of 4 bytes, with colors being laid out interleaved, RGB565_A5P will have the first part being RGB data using stride in multiple of 2 bytes and after that an alpha plane with data using stride in multiple of 1 byte.

Note

This value can change after setting image_size.

Note

Unit is pixels, not bytes.

Type

int

stride_get()

efl.evas.FilledImage Class

class efl.evas.FilledImage(Canvas canvas, **kargs)

Bases: efl.evas.Image

Image that automatically resize it’s contents to fit object size.

This Image subclass already calls Image.fill on resize so it will match and so be scaled to fill the whole area.

FilledImage(…)

Parameters

• canvas (Canvas) – The evas canvas for this object

• **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

fill_set(x, y, w, h)

Not available for this class.