Image

Widget description

An Elementary image object allows one to load and display an image file on it, be it from a disk file or from a memory region.

Exceptionally, one may also load an Edje group as the contents of the image. In this case, though, most of the functions of the image API will act as a no-op.

One can tune various properties of the image, like:

• pre-scaling,
• smooth scaling,
• orientation,
• aspect ratio during resizes, etc.

An image object may also be made valid source and destination for drag and drop actions by setting editable.

Emitted signals

• drop - This is called when a user has dropped an image typed object onto the object in question – the event info argument is the path to that image file
• clicked - This is called when a user has clicked the image
• download,start - remote url download has started
• download,progress - url download in progress
• download,end - remote url download has finished
• download,error - remote url download has finished with errors

Enumerations

Image manipulation types

efl.elementary.ELM_IMAGE_ORIENT_NONE

No orientation change

efl.elementary.ELM_IMAGE_ORIENT_0

No orientation change

efl.elementary.ELM_IMAGE_ROTATE_90

Rotate 90 degrees clockwise

efl.elementary.ELM_IMAGE_ROTATE_180

Rotate 180 degrees clockwise

efl.elementary.ELM_IMAGE_ROTATE_270

Rotate 270 degrees clockwise

efl.elementary.ELM_IMAGE_FLIP_HORIZONTAL

Flip the image horizontally

efl.elementary.ELM_IMAGE_FLIP_VERTICAL

Flip the image vertically

efl.elementary.ELM_IMAGE_FLIP_TRANSPOSE

Flip the image along the y = (width - x) line (bottom-left to top-right)

efl.elementary.ELM_IMAGE_FLIP_TRANSVERSE

Flip the image along the y = x line (top-left to bottom-right)

Inheritance diagram

class efl.elementary.Image(Object parent, *args, **kwargs)

Bases: efl.elementary.__init__.Object

Parameters:

• parent (efl.evas.Object) – The parent object
• **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

animated

Whether an image object (which supports animation) is to animate itself or not.

An image object, even if it supports animation, will be displayed by default without animation. Set this to True to enable its animation. To start or stop the animation, actually, use animated_play.

See also

animated_available animated_play

Type:bool

animated_available

Whether an image object supports animation or not.

This returns if this Elementary image object’s internal image can be animated. Currently Evas only supports GIF animation. If the return value is False, other animated_xxx API calls won’t work.

See also

animated

Type:bool

animated_available_get()

animated_get()

animated_play

Start or stop an image object’s animation.

To actually start playing any image object’s animation, if it supports it, one must do something like:

if img.animated_available:
    img.animated = True
    img.animated_play = True

animated will enable animation on the image, but not start it yet. This is the property one uses to start and stop animation on an image object or get whether it is animating or not.

See also

animated_available animated

Type:bool

animated_play_get()

animated_play_set(play)

animated_set(animated)

aspect_fixed

Whether the original aspect ratio of the image should be kept on resize.

The original aspect ratio (width / height) of the image is usually distorted to match the object’s size. Enabling this option will retain this original aspect, and the way that the image is fit into the object’s area depends on the option set by fill_outside.

See also

fill_outside

Type:bool

aspect_fixed_get()

aspect_fixed_set(fixed)

callback_clicked_add(func, *args, **kwargs)

This is called when a user has clicked the image.

callback_clicked_del(func)

callback_download_done_add(func, *args, **kwargs)

This is called when you set a remote url and the download finish

New in version 1.8.

callback_download_done_del(func)

callback_download_error_add(func, *args, **kwargs)

This is called in case a download has errors

New in version 1.8.

callback_download_error_del(func)

callback_download_progress_add(func, *args, **kwargs)

This is called while a remote image download is in progress

New in version 1.8.

callback_download_progress_del(func)

callback_download_start_add(func, *args, **kwargs)

This is called when you set a remote url and the download start

New in version 1.8.

callback_download_start_del(func)

callback_drop_add(func, *args, **kwargs)

This is called when a user has dropped an image typed object onto the object in question – the event info argument is the path to that image file.

callback_drop_del(func)

editable

Whether the image is ‘editable’.

This means the image is a valid drag target for drag and drop, and can be cut or pasted too. Default is False.

Type:bool

editable_get()

editable_set(editable)

file

The file (and edje group) that will be used as the image’s source.

Note

Setting this will trigger the Edje file case based on the extension of the file string (expects ".edj", for this case).

Note

If you use animated gif image and create multiple image objects with one gif image file, you should set the group differently for each object, else image objects will share one evas image cache entry and you will get unwanted frames.

Type:unicode file or (unicode file, unicode group) Raises RuntimeError:  when setting the file fails

Changed in version 1.8: Raises RuntimeError when setting the file fails, instead of returning a bool.

file_get()

file_set(filename, group=None)

fill_outside

Whether the image fills the entire object area, when keeping the aspect ratio.

When the image should keep its aspect ratio even if resized to another aspect ratio, there are two possibilities to resize it: keep the entire image inside the limits of height and width of the object (fill_outside is False) or let the extra width or height go outside of the object, and the image will fill the entire object (fill_outside is True).

Note

This option will have no effect if aspect_fixed is set to False.

Type:bool

fill_outside_get()

fill_outside_set(fill_outside)

memfile_set(img, size, format=None, key=None)

Set a location in memory to be used as an image object’s source bitmap.

This function is handy when the contents of an image file are mapped in memory, for example.

The format string should be something like "png", "jpg", "tga", "tiff", "bmp" etc, when provided. This improves the loader performance as it tries the “correct” loader first, before trying a range of other possible loaders until one succeeds.

Returns:True on success or False on error

New in version 1.14.

Parameters:

• img – The binary data that will be used as image source, must support the buffer interface
• size – The size of binary data blob img
• format – (Optional) expected format of img bytes
• key – Optional indexing key of img to be passed to the image loader (eg. if img is a memory-mapped EET file)

no_scale

Whether to disable scaling of this object.

This disables scaling of the elm_image widget through the property efl.elementary.object.Object.scale. However, this does not affect the widget size/resize in any way. For that effect, take a look at resizable.

Type:bool

no_scale_get()

no_scale_set(no_scale)

object

Get the inlined image object of the image widget.

This function allows one to get the underlying Evas_Object of type Image from this elementary widget. It can be useful to do things like get the pixel data, save the image to a file, etc.

Note

Be careful to not manipulate it, as it is under control of elementary.

Type:efl.evas.Image

object_get()

object_size

The current size of the image.

This is the real size of the image, not the size of the object.

Type:(int width, int height)

object_size_get()

orient

The image orientation.

Setting this allows to rotate or flip the given image.

Type:Image manipulation types

orient_get()

orient_set(orientation)

preload_disabled

Enable or disable preloading of the image

Type:bool

preload_disabled_set(disabled)

prescale

The prescale size for the image

This is the size for pixmap representation of the given image. It allows the image to be loaded already in the specified size, reducing the memory usage and load time when loading a big image with load size set to a smaller size.

It’s equivalent to the efl.elementary.background.Background.load_size property for bg.

Note

this is just a hint, the real size of the pixmap may differ depending on the type of image being loaded, being bigger than requested.

Type:int

prescale_get()

prescale_set(size)

resizable

Whether the object is (up/down) resizable.

This limits the image resize ability. If set to False, the object can’t have its height or width resized to a value higher than the original image size. Same is valid for size_down.

Type:(bool size_up, bool size_down)

resizable_get()

resizable_set(size_up, size_down)

smooth

The smooth effect for an image.

The scaling algorithm to be used when scaling the image. Smooth scaling provides a better resulting image, but is slower.

The smooth scaling should be disabled when making animations that change the image size, since it will be faster. Animations that don’t require resizing of the image can keep the smooth scaling enabled (even if the image is already scaled, since the scaled image will be cached).

Type:bool

smooth_get()

smooth_set(smooth)