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 fileclicked
- This is called when a user has clicked the imagedownload,start
- remote url download has starteddownload,progress
- url download in progressdownload,end
- remote url download has finisheddownload,error
- remote url download has finished with errorsload,open
- Triggered when the file has been opened, if async open is enabled (image size is known). (since 1.19)load,ready
- Triggered when the image file is ready for display, if preload is enabled. (since 1.19)load,error
- Triggered if an async I/O or decoding error occurred, if async open or preload is enabled (since 1.19)load,cancel
- Triggered whenener async I/O was cancelled. (since 1.19)
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
This is the class that actually implements the widget.
- 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, useanimated_play
.See also
- 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
- 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
- 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
- Type
bool
- aspect_fixed_get()¶
- aspect_fixed_set(fixed)¶
- async_open¶
Enable asynchronous file I/O for file set.
If True, this will make elm_image_file_set() an asynchronous operation.
- Type
bool (writeonly)
New in version 1.19.
- async_open_set(async)¶
- 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)¶
- callback_load_cancel_add(func, *args, **kwargs)¶
Triggered whenener async I/O was cancelled
New in version 1.19.
- callback_load_cancel_del(func)¶
- callback_load_error_add(func, *args, **kwargs)¶
Triggered if an async I/O or decoding error occurred, if async open or preload is enabled
New in version 1.19.
- callback_load_error_del(func)¶
- callback_load_open_add(func, *args, **kwargs)¶
Triggered when the file has been opened, if async open is enabled (image size is known)
New in version 1.19.
- callback_load_open_del(func)¶
- callback_load_ready_add(func, *args, **kwargs)¶
Triggered when the image file is ready for display, if preload is enabled
New in version 1.19.
- callback_load_ready_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 orFalse
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
byteskey – Optional indexing key of
img
to be passed to the image loader (eg. ifimg
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 atresizable
.- 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
- 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.
- orient_get()¶
- orient_set(orientation)¶
- preload_disabled¶
Enable or disable preloading of the image
- Type
bool (writeonly)
- 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)¶