Enumerations

enum  Elm_Image_Orient {
  ELM_IMAGE_ORIENT_NONE = 0,
  ELM_IMAGE_ORIENT_0 = 0,
  ELM_IMAGE_ROTATE_90 = 1,
  ELM_IMAGE_ROTATE_180 = 2,
  ELM_IMAGE_ROTATE_270 = 3,
  ELM_IMAGE_FLIP_HORIZONTAL = 4,
  ELM_IMAGE_FLIP_VERTICAL = 5,
  ELM_IMAGE_FLIP_TRANSPOSE = 6,
  ELM_IMAGE_FLIP_TRANSVERSE = 7
}
 Possible orientation options for elm_image_orient_set(). More...

Functions

Evas_Object * elm_image_add (Evas_Object *parent)
 Add a new image to the parent.
Eina_Bool elm_image_memfile_set (Evas_Object *obj, const void *img, size_t size, const char *format, const char *key)
 Set a location in memory to be used as an image object's source bitmap.
Eina_Bool elm_image_file_set (Evas_Object *obj, const char *file, const char *group)
 Set the file that will be used as the image's source.
void elm_image_file_get (const Evas_Object *obj, const char **file, const char **group)
 Get the file that will be used as image.
void elm_image_smooth_set (Evas_Object *obj, Eina_Bool smooth)
 Set the smooth effect for an image.
Eina_Bool elm_image_smooth_get (const Evas_Object *obj)
 Get the smooth effect for an image.
void elm_image_object_size_get (const Evas_Object *obj, int *w, int *h)
 Gets the current size of the image.
void elm_image_no_scale_set (Evas_Object *obj, Eina_Bool no_scale)
 Disable scaling of this object.
Eina_Bool elm_image_no_scale_get (const Evas_Object *obj)
 Get whether scaling is disabled on the object.
void elm_image_resizable_set (Evas_Object *obj, Eina_Bool size_up, Eina_Bool size_down)
 Set if the object is (up/down) resizable.
void elm_image_resizable_get (const Evas_Object *obj, Eina_Bool *size_up, Eina_Bool *size_down)
 Get if the object is (up/down) resizable.
void elm_image_fill_outside_set (Evas_Object *obj, Eina_Bool fill_outside)
 Set if the image fills the entire object area, when keeping the aspect ratio.
Eina_Bool elm_image_fill_outside_get (const Evas_Object *obj)
 Get if the object is filled outside.
void elm_image_preload_disabled_set (Evas_Object *obj, Eina_Bool disabled)
 Enable or disable preloading of the image.
void elm_image_prescale_set (Evas_Object *obj, int size)
 Set the prescale size for the image.
int elm_image_prescale_get (const Evas_Object *obj)
 Get the prescale size for the image.
void elm_image_orient_set (Evas_Object *obj, Elm_Image_Orient orient)
 Set the image orientation.
Elm_Image_Orient elm_image_orient_get (const Evas_Object *obj)
 Get the image orientation.
void elm_image_editable_set (Evas_Object *obj, Eina_Bool set)
 Make the image 'editable'.
Eina_Bool elm_image_editable_get (const Evas_Object *obj)
 Check if the image is 'editable'.
Evas_Object * elm_image_object_get (const Evas_Object *obj)
 Get the inlined image object of the image widget.
void elm_image_aspect_fixed_set (Evas_Object *obj, Eina_Bool fixed)
 Set whether the original aspect ratio of the image should be kept on resize.
Eina_Bool elm_image_aspect_fixed_get (const Evas_Object *obj)
 Get if the object retains the original aspect ratio.
Eina_Bool elm_image_animated_available_get (const Evas_Object *obj)
 Get whether an image object supports animation or not.
void elm_image_animated_set (Evas_Object *obj, Eina_Bool animated)
 Set whether an image object (which supports animation) is to animate itself or not.
Eina_Bool elm_image_animated_get (const Evas_Object *obj)
 Get whether an image object has animation enabled or not.
void elm_image_animated_play_set (Evas_Object *obj, Eina_Bool play)
 Start or stop an image object's animation.
Eina_Bool elm_image_animated_play_get (const Evas_Object *obj)
 Get whether an image object is under animation or not.

Detailed Description

image_inheritance_tree.png
preview-00.png

An Elementary image object is a direct realization of The Elementary Image Class, and it 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, through the elm_image_editable_set() call.

Signals that you can add callbacks for are:

  • "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

An example of usage for this API follows:


Enumeration Type Documentation

Possible orientation options for elm_image_orient_set().

elm_image_orient_set.png
Enumerator:
ELM_IMAGE_ORIENT_NONE 

no orientation change

ELM_IMAGE_ORIENT_0 

no orientation change

ELM_IMAGE_ROTATE_90 

rotate 90 degrees clockwise

ELM_IMAGE_ROTATE_180 

rotate 180 degrees clockwise

ELM_IMAGE_ROTATE_270 

rotate 90 degrees counter-clockwise (i.e.

270 degrees clockwise)

ELM_IMAGE_FLIP_HORIZONTAL 

flip image horizontally

ELM_IMAGE_FLIP_VERTICAL 

flip image vertically

ELM_IMAGE_FLIP_TRANSPOSE 

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

ELM_IMAGE_FLIP_TRANSVERSE 

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


Function Documentation

Evas_Object* elm_image_add ( Evas_Object *  parent)

Add a new image to the parent.

Parameters:
parentThe parent object
Returns:
The new object or NULL if it cannot be created
See also:
elm_image_file_set()
Eina_Bool elm_image_animated_available_get ( const Evas_Object *  obj)

Get whether an image object supports animation or not.

Parameters:
objThe image object
Returns:
EINA_TRUE if the image supports animation, EINA_FALSE otherwise.

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 EINA_FALSE, other elm_image_animated_xxx API calls won't work.

See also:
elm_image_animated_set()
Since:
1.7

References elm_image_object_get().

Referenced by elm_icon_animated_available_get().

Eina_Bool elm_image_animated_get ( const Evas_Object *  obj)

Get whether an image object has animation enabled or not.

Parameters:
objThe image object
Returns:
EINA_TRUE if the image has animation enabled, EINA_FALSE otherwise.
See also:
elm_image_animated_set()
Since:
1.7

Referenced by elm_icon_animated_get().

Eina_Bool elm_image_animated_play_get ( const Evas_Object *  obj)

Get whether an image object is under animation or not.

Parameters:
objThe image object
Returns:
EINA_TRUE, if the image is being animated, EINA_FALSE otherwise.
See also:
elm_image_animated_play_get()
Since:
1.7

Referenced by elm_icon_animated_play_get().

void elm_image_animated_play_set ( Evas_Object *  obj,
Eina_Bool  play 
)

Start or stop an image object's animation.

Parameters:
objThe image object
playEINA_TRUE to start the animation, EINA_FALSE otherwise. Default is EINA_FALSE.

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

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

See also:
elm_image_animated_available_get()
elm_image_animated_set()
elm_image_animated_play_get()
Since:
1.7

Referenced by elm_icon_animated_play_set().

void elm_image_animated_set ( Evas_Object *  obj,
Eina_Bool  animated 
)

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

Parameters:
objThe image object
animatedEINA_TRUE if the object is to animate itself, EINA_FALSE otherwise. Default is EINA_FALSE.

An image object, even if it supports animation, will be displayed by default without animation. Call this function with animated set to EINA_TRUE to enable its animation. To start or stop the animation, actually, use elm_image_animated_play_set().

See also:
elm_image_animated_get()
elm_image_animated_available_get()
elm_image_animated_play_set()
Since:
1.7

References elm_image_object_get().

Referenced by elm_icon_animated_set().

Eina_Bool elm_image_aspect_fixed_get ( const Evas_Object *  obj)

Get if the object retains the original aspect ratio.

Parameters:
objThe image object.
Returns:
EINA_TRUE if the object keeps the original aspect, EINA_FALSE otherwise.

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_aspect_fixed_get(), and elm_photo_aspect_fixed_get().

void elm_image_aspect_fixed_set ( Evas_Object *  obj,
Eina_Bool  fixed 
)

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

Parameters:
objThe image object.
fixedEINA_TRUE if the image should retain the aspect, EINA_FALSE otherwise.

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

See also:
elm_image_aspect_fixed_get()
elm_image_fill_outside_set()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_aspect_fixed_set(), and elm_photo_aspect_fixed_set().

Eina_Bool elm_image_editable_get ( const Evas_Object *  obj)

Check if the image is 'editable'.

Parameters:
objImage object.
Returns:
Editability.

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

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

void elm_image_editable_set ( Evas_Object *  obj,
Eina_Bool  set 
)

Make the image 'editable'.

Parameters:
objImage object.
setTurn on or off editability. Default is EINA_FALSE.

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

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_photo_editable_set().

void elm_image_file_get ( const Evas_Object *  obj,
const char **  file,
const char **  group 
)

Get the file that will be used as image.

Parameters:
objThe image object
fileThe path to file
groupThe group that the image belongs in edje file
See also:
elm_image_file_set()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_file_get().

Eina_Bool elm_image_file_set ( Evas_Object *  obj,
const char *  file,
const char *  group 
)

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

Parameters:
objThe image object
fileThe path to file that will be used as image source
groupThe group that the image belongs to, in case it's an EET (including Edje case) file
Returns:
(EINA_TRUE = success, EINA_FALSE = error)
See also:
elm_image_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, elm_image_file_edje_set() must be used, instead.

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_file_set(), elm_photo_file_set(), and elm_toolbar_item_icon_file_set().

Eina_Bool elm_image_fill_outside_get ( const Evas_Object *  obj)

Get if the object is filled outside.

Parameters:
objThe image object
Returns:
EINA_TRUE if the object is filled outside, EINA_FALSE otherwise.
See also:
elm_image_fill_outside_set()

Referenced by elm_icon_fill_outside_get().

void elm_image_fill_outside_set ( Evas_Object *  obj,
Eina_Bool  fill_outside 
)

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

Parameters:
objThe image object
fill_outsideEINA_TRUE if the object is filled outside, EINA_FALSE otherwise. Default is EINA_FALSE.

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 EINA_FALSE) or let the extra width or height go outside of the object, and the image will fill the entire object (fill_outside is EINA_TRUE).

Note:
This option will have no effect if elm_image_aspect_fixed_set() is set to EINA_FALSE.
See also:
elm_image_fill_outside_get()
elm_image_aspect_fixed_set()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_fill_outside_set(), and elm_photo_fill_inside_set().

Eina_Bool elm_image_memfile_set ( Evas_Object *  obj,
const void *  img,
size_t  size,
const char *  format,
const char *  key 
)

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

Parameters:
objThe image object
imgThe binary data that will be used as image source
sizeThe size of binary data blob img
format(Optional) expected format of img bytes
keyOptional indexing key of img to be passed to the image loader (eg. if img is a memory-mapped EET file)

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 (NULL, on the contrary). This improves the loader performance as it tries the "correct" loader first, before trying a range of other possible loaders until one succeeds.

Returns:
(EINA_TRUE = success, EINA_FALSE = error)
Since:
1.7

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_memfile_set(), and elm_toolbar_item_icon_memfile_set().

Eina_Bool elm_image_no_scale_get ( const Evas_Object *  obj)

Get whether scaling is disabled on the object.

Parameters:
objThe image object
Returns:
EINA_TRUE if scaling is disabled, EINA_FALSE otherwise
See also:
elm_image_no_scale_set()

Referenced by elm_icon_no_scale_get().

void elm_image_no_scale_set ( Evas_Object *  obj,
Eina_Bool  no_scale 
)

Disable scaling of this object.

Parameters:
objThe image object.
no_scaleEINA_TRUE if the object is not scalable, EINA_FALSE otherwise. Default is EINA_FALSE.

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

See also:
elm_image_no_scale_get()
elm_image_resizable_set()
elm_object_scale_set()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_no_scale_set().

Evas_Object* elm_image_object_get ( const Evas_Object *  obj)

Get the inlined image object of the image widget.

Parameters:
objThe image object to get the inlined image from
Returns:
The inlined image object, or NULL if none exists

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.

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_object_get(), elm_image_animated_available_get(), and elm_image_animated_set().

void elm_image_object_size_get ( const Evas_Object *  obj,
int *  w,
int *  h 
)

Gets the current size of the image.

Parameters:
objThe image object.
wPointer to store width, or NULL.
hPointer to store height, or NULL.

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

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_size_get().

Elm_Image_Orient elm_image_orient_get ( const Evas_Object *  obj)

Get the image orientation.

Parameters:
objThe image object
Returns:
The image orientation Elm_Image_Orient
See also:
elm_image_orient_set()
Elm_Image_Orient

References ELM_IMAGE_CLASS, ELM_IMAGE_ORIENT_NONE, and ELM_WIDGET_DATA.

void elm_image_orient_set ( Evas_Object *  obj,
Elm_Image_Orient  orient 
)

Set the image orientation.

Parameters:
objThe image object
orientThe image orientation Elm_Image_Orient Default is ELM_IMAGE_ORIENT_NONE.

This function allows to rotate or flip the given image.

See also:
elm_image_orient_get()
Elm_Image_Orient

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

void elm_image_preload_disabled_set ( Evas_Object *  obj,
Eina_Bool  disabled 
)

Enable or disable preloading of the image.

Parameters:
objThe image object
disabledIf EINA_TRUE, preloading will be disabled

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_preload_disabled_set().

int elm_image_prescale_get ( const Evas_Object *  obj)

Get the prescale size for the image.

Parameters:
objThe image object
Returns:
The prescale size
See also:
elm_image_prescale_set()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_prescale_get().

void elm_image_prescale_set ( Evas_Object *  obj,
int  size 
)

Set the prescale size for the image.

Parameters:
objThe image object
sizeThe prescale size. This value is used for both width and height.

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 elm_bg_load_size_set() function 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.
See also:
elm_image_prescale_get()
elm_bg_load_size_set()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_prescale_set(), and elm_photo_size_set().

void elm_image_resizable_get ( const Evas_Object *  obj,
Eina_Bool *  size_up,
Eina_Bool *  size_down 
)

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

Parameters:
objThe image object
size_upA bool to set if the object is resizable up
size_downA bool to set if the object is resizable down
See also:
elm_image_resizable_set()

Referenced by elm_icon_resizable_get().

void elm_image_resizable_set ( Evas_Object *  obj,
Eina_Bool  size_up,
Eina_Bool  size_down 
)

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

Parameters:
objThe image object
size_upA bool to set if the object is resizable up. Default is EINA_TRUE.
size_downA bool to set if the object is resizable down. Default is EINA_TRUE.

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

See also:
elm_image_resizable_get()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_resizable_set().

Eina_Bool elm_image_smooth_get ( const Evas_Object *  obj)

Get the smooth effect for an image.

Parameters:
objThe image object
Returns:
EINA_TRUE if smooth scaling is enabled, EINA_FALSE otherwise.
See also:
elm_image_smooth_get()

Referenced by elm_icon_smooth_get().

void elm_image_smooth_set ( Evas_Object *  obj,
Eina_Bool  smooth 
)

Set the smooth effect for an image.

Parameters:
objThe image object
smoothEINA_TRUE if smooth scaling should be used, EINA_FALSE otherwise. Default is EINA_TRUE.

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

See also:
elm_image_smooth_get()

References ELM_IMAGE_CLASS, and ELM_WIDGET_DATA.

Referenced by elm_icon_smooth_set().