Package elementary :: Module c_elementary :: Class Image
[hide private]
[frames] | no frames]

Class Image

        object --+        
                 |        
evas.c_evas.Object --+    
                     |    
                Object --+
                         |
                        Image
Known Subclasses:

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:

An image object may also be made valid source and destination for drag and drop actions, through the editable_set() call.

Signals that you can add callbacks for are:

Instance Methods [hide private]
 
__init__(...)
x.__init__(...) initializes x; see help(type(x)) for signature
a new object with type S, a subtype of T
__new__(T, S, ...)
bool
animated_available_get(...)
Get whether an image object supports animation or not.
bool
animated_get(...)
Get whether an image object has animation enabled or not.
bool
animated_play_get(...)
Get whether an image object is under animation or not.
 
animated_play_set(...)
Start or stop an image object's animation.
 
animated_set(...)
Set whether an image object (which supports animation) is to animate itself or not.
bool
aspect_fixed_get(...)
Get if the object retains the original aspect ratio.
 
aspect_fixed_set(...)
Set whether the original aspect ratio of the image should be kept on resize.
bool
editable_get(...)
Check if the image is 'editable'.
 
editable_set(...)
Make the image 'editable'.
tuple of strings
file_get(...)
Get the file that will be used as image.
bool
file_set(...)
Set the file that will be used as the image's source.
bool
fill_outside_get(...)
Get if the object is filled outside
 
fill_outside_set(...)
Set if the image fills the entire object area, when keeping the aspect ratio.
bool
no_scale_get(...)
Get whether scaling is disabled on the object.
 
no_scale_set(...)
Disable scaling of this object.
evas.Image
object_get(...)
Get the inlined image object of the image widget.
tuple of ints
object_size_get(...)
Gets the current size of the image.
Elm_Image_Orient
orient_get(...)
Get the image orientation.
 
orient_set(...)
Set the image orientation.
 
preload_disabled_set(...)
Enable or disable preloading of the image
int
prescale_get(...)
Get the prescale size for the image
 
prescale_set(...)
Set the prescale size for the image
tuple of bools
resizable_get(...)
Get if the object is (up/down) resizable.
 
resizable_set(...)
Set if the object is (up/down) resizable.
bool
smooth_get(...)
Get the smooth effect for an image.
 
smooth_set(...)
Set the smooth effect for an image.

Inherited from Object: tree_focus_allow_get, tree_focus_allow_set

Inherited from evas.c_evas.Object: __repr__, __str__, bottom_center_get, bottom_center_set, clipees_get, evas_get, left_center_get, left_center_set, map_enabled_get, map_enabled_set, map_get, map_set, name_get, name_set, parent_get, right_center_get, right_center_set, size_hint_align_get, size_hint_align_set, size_hint_aspect_get, size_hint_aspect_set, size_hint_max_get, size_hint_max_set, size_hint_min_get, size_hint_min_set, size_hint_padding_get, size_hint_padding_set, size_hint_request_get, size_hint_request_set, size_hint_weight_get, size_hint_weight_set, static_clip_get, static_clip_set, top_center_get, top_center_set, type_get

Inherited from evas.c_evas.Object (private): _set_common_params, _set_evas

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

    General

Inherited from Object: access_info_set, content_get, content_set, content_unset, domain_translatable_text_part_set, domain_translatable_text_set, elm_event_callback_add, elm_event_callback_del, name_find, part_content_get, part_content_set, part_content_unset, part_text_get, part_text_set, signal_emit, text_get, text_set, translatable_text_get, translatable_text_part_get, translatable_text_set

    Styles

Inherited from Object: disabled_get, disabled_set, style_get, style_set

    Widget Tree Navigation

Inherited from Object: parent_widget_get, top_widget_get, widget_check, widget_type_get

    Cursors

Inherited from Object: cursor_get, cursor_set, cursor_style_get, cursor_style_set, cursor_theme_search_enabled_get, cursor_theme_search_enabled_set, cursor_unset

    Focus

Inherited from Object: focus_allow_get, focus_allow_set, focus_custom_chain_append, focus_custom_chain_get, focus_custom_chain_prepend, focus_custom_chain_set, focus_custom_chain_unset, focus_get, focus_set

    Mirroring

Inherited from Object: mirrored_automatic_get, mirrored_automatic_set, mirrored_get, mirrored_set

    Widget Scaling

Inherited from Object: scale_get, scale_set

    Scrollhints

Inherited from Object: scroll_freeze_pop, scroll_freeze_push, scroll_hold_pop, scroll_hold_push, scroll_lock_x_get, scroll_lock_x_set, scroll_lock_y_get, scroll_lock_y_set

    Tooltips

Inherited from Object: tooltip_content_cb_set, tooltip_domain_translatable_text_set, tooltip_hide, tooltip_show, tooltip_style_get, tooltip_style_set, tooltip_text_set, tooltip_translatable_text_set, tooltip_unset, tooltip_window_mode_get, tooltip_window_mode_set

    Callbacks
 
callback_clicked_add(...)
This is called when a user has clicked the image.
 
callback_clicked_del(...)
 
callback_drop_add(...)
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(...)
    State manipulation

Inherited from evas.c_evas.Object: clip_get, clip_set, clip_unset, color_get, color_set, delete, hide, is_deleted, show, visible_get, visible_set

    Positioning

Inherited from evas.c_evas.Object: bottom_left_get, bottom_left_set, bottom_right_get, bottom_right_set, center_get, center_set, geometry_get, geometry_set, move, move_relative, pos_get, pos_set, resize, size_get, size_set, top_left_get, top_left_set, top_right_get, top_right_set

    Layer & Stack manipulation

Inherited from evas.c_evas.Object: above_get, below_get, bottom_get, layer_get, layer_set, lower, raise_, stack_above, stack_below, top_get

    Event processing control

Inherited from evas.c_evas.Object: pass_events_get, pass_events_set, propagate_events_get, propagate_events_set, repeat_events_get, repeat_events_set

    Event callbacks

Inherited from evas.c_evas.Object: event_callback_add, event_callback_del, on_changed_size_hints_add, on_changed_size_hints_del, on_del_add, on_del_del, on_focus_in_add, on_focus_in_del, on_focus_out_add, on_focus_out_del, on_free_add, on_free_del, on_hide_add, on_hide_del, on_hold_add, on_hold_del, on_key_down_add, on_key_down_del, on_key_up_add, on_key_up_del, on_mouse_down_add, on_mouse_down_del, on_mouse_in_add, on_mouse_in_del, on_mouse_move_add, on_mouse_move_del, on_mouse_out_add, on_mouse_out_del, on_mouse_up_add, on_mouse_up_del, on_mouse_wheel_add, on_mouse_wheel_del, on_move_add, on_move_del, on_resize_add, on_resize_del, on_restack_add, on_restack_del, on_show_add, on_show_del

    Often unused

Inherited from evas.c_evas.Object: anti_alias_get, anti_alias_set, pointer_mode_get, pointer_mode_set, render_op_get, render_op_set

Instance Variables [hide private]

Inherited from evas.c_evas.Object: data, evas

Properties [hide private]
bool animated
Whether an image object (which supports animation) is to animate itself or not.
bool animated_available
Whether an image object supports animation or not.
bool animated_play
Start or stop an image object's animation.
bool aspect_fixed
Whether the original aspect ratio of the image should be kept on resize.
bool editable
Whether the image is 'editable'.
string or tuple of strings file
The file (and edje group) that will be used as the image's source.
bool fill_outside
Whether the image fills the entire object area, when keeping the aspect ratio.
bool no_scale
Whether to disable scaling of this object.
evas.Image object
Get the inlined image object of the image widget.
tuple of ints object_size
The current size of the image.
Elm_Image_Orient orient
The image orientation.
bool preload_disabled
Enable or disable preloading of the image
int prescale
The prescale size for the image
(bool size_up, bool size_down) resizable
Whether the object is (up/down) resizable.
bool smooth
The smooth effect for an image.

Inherited from Object: content, cursor, mirrored, parent_widget, scale, style, theme, top_widget, tree_focus_allow, widget_type

Inherited from evas.c_evas.Object: bottom_center, clipees, left_center, map, map_enabled, name, parent, rect, right_center, size_hint_align, size_hint_aspect, size_hint_max, size_hint_min, size_hint_padding, size_hint_request, size_hint_weight, static_clip, top_center, type

Inherited from object: __class__

    General

Inherited from Object: text, translatable_text

    Styles

Inherited from Object: disabled

    Cursors

Inherited from Object: cursor_style, cursor_theme_search_enabled

    Focus

Inherited from Object: focus_allow, focus_custom_chain

    Mirroring

Inherited from Object: mirrored_automatic

    Scrollhints

Inherited from Object: scroll_lock_x, scroll_lock_y

    Tooltips

Inherited from Object: tooltip_style, tooltip_window_mode

    State manipulation

Inherited from evas.c_evas.Object: clip, color, visible

    Positioning

Inherited from evas.c_evas.Object: bottom_left, bottom_right, center, geometry, pos, size, top_left, top_right

    Layer & Stack manipulation

Inherited from evas.c_evas.Object: above, below, bottom, layer, top

    Event processing control

Inherited from evas.c_evas.Object: focus, pass_events, propagate_events, repeat_events

    Often unused

Inherited from evas.c_evas.Object: anti_alias, pointer_mode, render_op

Method Details [hide private]

__init__(...)
(Constructor)

 

x.__init__(...) initializes x; see help(type(x)) for signature

Parameters:
  • evas - Evas canvas for this object
Overrides: object.__init__

__new__(T, S, ...)

 
Returns: a new object with type S, a subtype of T
Overrides: object.__new__

animated_available_get(...)

 

Get whether an image object supports animation or not.

This function 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.

Returns: bool
True if the image supports animation, False otherwise.

See Also: animated_set()

animated_get(...)

 

Get whether an image object has animation enabled or not.

Returns: bool
True if the image has animation enabled, False otherwise.

See Also: animated_set()

animated_play_get(...)

 

Get whether an image object is under animation or not.

Returns: bool
True, if the image is being animated, False otherwise.

animated_play_set(...)

 

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_get():
       img.animated_set(True)
       img.animated_play_set(True)

animated_set() will enable animation on the image, but not start it yet. This is the function one uses to start and stop animations on image objects.

Parameters:
  • play (bool) - True to start the animation, False otherwise. Default is False.

animated_set(...)

 

Set 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. Call this function with animated set to True to enable its animation. To start or stop the animation, actually, use animated_play_set().

Parameters:
  • animated (bool) - True if the object is to animate itself, False otherwise. Default is False.

aspect_fixed_get(...)

 

Get if the object retains the original aspect ratio.

Returns: bool
True if the object keeps the original aspect, False otherwise.

aspect_fixed_set(...)

 

Set 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_set().

Parameters:
  • fixed (bool) - True if the image should retain the aspect, False otherwise.

editable_get(...)

 

Check if the image is 'editable'.

A return value of True means the image is a valid drag target for drag and drop, and can be cut or pasted too.

Returns: bool
Editability.

editable_set(...)

 

Make the image 'editable'.

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

Parameters:
  • set (bool) - Turn on or off editability. Default is False.

file_get(...)

 

Get the file that will be used as image.

Returns: tuple of strings
File path and group

See Also: file_set()

file_set(...)

 

Set the file that will be used as the image's source.

Parameters:
  • file (string) - The path to file that will be used as image source
  • group (string) - The group that the image belongs to, in case it's an EET (including Edje case) file
Returns: bool
(True = success, False = error)

See Also: file_get()

Note: This function will trigger the Edje file case based on the extension of the file string (expects ".edj", for this case). If one wants to force this type of file independently of the extension, file_edje_set() must be used, instead.

fill_outside_get(...)

 

Get if the object is filled outside

Returns: bool
True if the object is filled outside, False otherwise.

See Also: fill_outside_set()

fill_outside_set(...)

 

Set if 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).

Parameters:
  • fill_outside (bool) - True if the object is filled outside, False otherwise. Default is False.

Note: This option will have no effect if aspect_fixed_set() is set to False.

See Also:
fill_outside_get(), aspect_fixed_set()

no_scale_get(...)

 

Get whether scaling is disabled on the object.

Returns: bool
True if scaling is disabled, False otherwise

See Also: no_scale_set()

no_scale_set(...)

 

Disable scaling of this object.

This function disables scaling of the elm_image widget through the function Object.scale_set(). However, this does not affect the widget size/resize in any way. For that effect, take a look at resizable_set().

Parameters:
  • no_scale (bool) - True if the object is not scalable, False otherwise. Default is False.

object_get(...)

 

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.

Returns: evas.Image
The inlined image object, or None if none exists

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

object_size_get(...)

 

Gets the current size of the image.

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

Returns: tuple of ints
Width and height of the image

orient_get(...)

 

Get the image orientation.

Returns: Elm_Image_Orient
The image orientation

See Also: orient_set()

orient_set(...)

 

Set the image orientation.

This function allows to rotate or flip the given image.

Parameters:
  • orient (Elm_Image_Orient) - The image orientation. Default is ELM_IMAGE_ORIENT_NONE.

See Also: orient_get()

preload_disabled_set(...)

 

Enable or disable preloading of the image

Parameters:
  • disabled (bool) - If True, preloading will be disabled

prescale_get(...)

 

Get the prescale size for the image

Returns: int
The prescale size

See Also: prescale_set()

prescale_set(...)

 

Set the prescale size for the image

This function sets a new 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 Background.load_size_set() function for bg.

Parameters:
  • size (int) - The prescale size. This value is used for both width and height.

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.

See Also:
prescale_get(), Background.load_size_set()

resizable_get(...)

 

Get if the object is (up/down) resizable.

Returns: tuple of bools
The values of resizable up and down

resizable_set(...)

 

Set if the object is (up/down) resizable.

This function limits the image resize ability. If size_up is 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.

Parameters:
  • size_up (bool) - A bool to set if the object is resizable up. Default is True.
  • size_down (bool) - A bool to set if the object is resizable down. Default is True.

See Also: resizable_get()

smooth_get(...)

 

Get the smooth effect for an image.

Returns: bool
True if smooth scaling is enabled, False otherwise.

See Also: smooth_get()

smooth_set(...)

 

Set the smooth effect for an image.

Set 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).

Parameters:
  • smooth (bool) - True if smooth scaling should be used, False otherwise. Default is True.

See Also: smooth_get()


Property Details [hide private]

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.

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.

Type:
bool

See Also: animated

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.

Type:
bool

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.

Type:
bool

See Also: fill_outside

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

file

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

Type:
string or tuple of strings

Note: Setting this will trigger the Edje file case based on the extension of the file string (expects ".edj", for this case). If one wants to force this type of file independently of the extension, file_edje_set() must be used, instead.

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).

Type:
bool

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

See Also: aspect_fixed

no_scale

Whether to disable scaling of this object.

This disables scaling of the elm_image widget through the function Object.scale_set(). However, this does not affect the widget size/resize in any way. For that effect, take a look at resizable_set().

Type:
bool

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.

Type:
evas.Image

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

object_size

The current size of the image.

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

Type:
tuple of ints

orient

The image orientation.

Setting this allows to rotate or flip the given image.

Type:
Elm_Image_Orient

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 Background.load_size property for bg.

Type:
int

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.

See Also: Background.load_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)

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