Some image object functions examples

In this example, we add two images to a canvas, each one having a quarter of the canvas' size, positioned on the top left and bottom right corners, respectively:

d.img1 = evas_object_image_add(d.evas);
evas_object_image_file_set(d.img1, valid_path, NULL);
err = evas_object_image_load_error_get(d.img1);
if (err != EVAS_LOAD_ERROR_NONE)
{
fprintf(stderr, "could not load image '%s'. error string is \"%s\"\n",
valid_path, evas_load_error_str(err));
}
else
{
printf("loaded image '%s' with succes! error string is \"%s\"\n",
valid_path, evas_load_error_str(err));
evas_object_move(d.img1, 3, 3);
evas_object_image_fill_set(d.img1, 0, 0, WIDTH / 2, HEIGHT / 2);
evas_object_resize(d.img1, WIDTH / 2, HEIGHT / 2);
evas_object_show(d.img1);
evas_object_focus_set(d.bg, EINA_TRUE);
evas_object_event_callback_add(
d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
}
/* this is a border around the image above, here just to emphasize
* its geometry */
d.border = evas_object_image_filled_add(d.evas);
evas_object_image_file_set(d.border, border_img_path, NULL);
evas_object_image_border_set(d.border, 3, 3, 3, 3);
evas_object_image_border_center_fill_set(d.border, EVAS_BORDER_FILL_NONE);
evas_object_move(d.border, 0, 0);
evas_object_resize(d.border, (WIDTH / 2) + 6, (HEIGHT / 2) + 6);
evas_object_show(d.border);
/* image loading will fail for this one -- unless one cheats and
* puts a valid image on that path */
d.img2 = evas_object_image_add(d.evas);
evas_object_image_file_set(d.img2, bogus_path, NULL);
err = evas_object_image_load_error_get(d.img2);
if (err != EVAS_LOAD_ERROR_NONE)
{
fprintf(stderr, "could not load image '%s': error string is \"%s\"\n",
bogus_path, evas_load_error_str(err));
}
else
{
evas_object_move(d.img2, WIDTH / 2, HEIGHT / 2);
evas_object_image_fill_set(d.img2, 0, 0, WIDTH / 2, HEIGHT / 2);
evas_object_resize(d.img2, WIDTH / 2, HEIGHT / 2);
evas_object_show(d.img2);
}
puts(commands);
ecore_main_loop_begin();
EVAS_CALLBACK_KEY_DOWN
@ EVAS_CALLBACK_KEY_DOWN
Key Press Event.
Definition: Evas_Common.h:430
ecore_main_loop_begin
void ecore_main_loop_begin(void)
Runs the application main loop.
Definition: ecore_main.c:1311
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
EVAS_LOAD_ERROR_NONE
@ EVAS_LOAD_ERROR_NONE
No error on load.
Definition: Evas_Loader.h:141
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814
evas_object_event_callback_add
EVAS_API void evas_object_event_callback_add(Evas_Object *eo_obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data)
Add (register) a callback function to a given Evas object event.
Definition: evas_callbacks.c:478
evas_object_move
EVAS_API void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y)
Move the given Evas object to the given location inside its canvas' viewport.
Definition: evas_object_main.c:1171
evas_object_focus_set
EVAS_API void evas_object_focus_set(Efl_Canvas_Object *obj, Eina_Bool focus)
Indicates that this object is the keyboard event receiver on its canvas.
Definition: efl_canvas_object_eo.legacy.c:39
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition: evas_object_main.c:1236
evas_object_image_border_set
EVAS_API void evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b)
Dimensions of this image's border, a region that does not scale with the center area.
Definition: evas_image_legacy.c:117
evas_object_image_fill_set
EVAS_API void evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h)
Set how to fill an image object's drawing rectangle given the (real) image bound to it.
Definition: evas_image_legacy.c:57
evas_object_image_load_error_get
EVAS_API Evas_Load_Error evas_object_image_load_error_get(const Evas_Object *obj)
Retrieves a number representing any error that occurred during the last loading of the given image ob...
Definition: evas_image_legacy.c:400
evas_object_image_add
EVAS_API Evas_Object * evas_object_image_add(Evas *eo_e)
Creates a new image object on the given Evas e canvas.
Definition: evas_image_legacy.c:25
evas_object_image_filled_add
EVAS_API Evas_Object * evas_object_image_filled_add(Evas *eo_e)
Creates a new image object that automatically scales its bound image to the object's area,...
Definition: evas_image_legacy.c:35
evas_object_image_border_center_fill_set
EVAS_API void evas_object_image_border_center_fill_set(Evas_Object *obj, Evas_Border_Fill_Mode fill)
Specifies how the center part of the object (not the borders) should be drawn when EFL is rendering i...
Definition: evas_image_legacy.c:145
evas_object_image_file_set
EVAS_API void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key)
Set the source file from where an image object must fetch the real image data (it may be an Eet file,...
Definition: evas_image_legacy.c:194
EVAS_BORDER_FILL_NONE
@ EVAS_BORDER_FILL_NONE
Image's center region is not to be rendered.
Definition: Evas_Legacy.h:5721
evas_load_error_str
EVAS_API const char * evas_load_error_str(Evas_Load_Error error)
Converts the given Evas image load error code into a string describing it in human-readable text.
Definition: evas_main.c:974

See there is a border image around the top left one, which is the one that should be displayed. The other one will (on purpose) fail to load, because we set a wrong file path as image source on it:

static const char *valid_path = PACKAGE_EXAMPLES_DIR EVAS_IMAGE_FOLDER "/enlightenment.png";
static const char *bogus_path = "/tmp/non-existent-220986.png";

This is how one is supposed to test for success when binding source images to image objects: evas_object_image_load_error_get(), followed by evas_load_error_str(), if one wants to pretty print/log the error. We'll talk about the border image further.

To interact with the program, there's a command line interface. A help string can be asked for with the 'h' key:

static const char *commands = \
"commands are:\n"
"\tx - change image's x fill coordinate\n"
"\ty - change image's y fill coordinate\n"
"\tw - change image's w fill size\n"
"\te - change image's h fill size\n"
"\tf - toggle image filled property (overrides fill)\n"
"\ta - toggle image's alpha channel usage\n"
"\tm - toggle border's smooth scaling\n"
"\tt - change border's thickness\n"
"\tb - change border's center region aspect\n"
"\tc - change border's scaling factor\n"
"\ts - print image's fill property status\n"
"\th - print help\n";

The first four commands will change the top left images's fill property values, which dictate how the source image (Enlightenment's logo) is to be displayed through the image object's area. Experiment with those switches until you get the idea of evas_object_fill_set().

The 'f' command will toggle that image's "filled" property, which is whether it should track its size and set the fill one to fit the object's boundaries perfectly (stretching). Note that this command and the four above it will conflict: in real usage one would use one or other ways of setting an image object's viewport with regard to its image source.

There are four commands which deal with the border image. This red frame is there to illustrate image borders. The image source for the border is a solid red rectangle, with a transparent rectangular area in its middle. See how we use it to get a 3 pixel wide frame with `evas_object_image_border_set(d.border, 3, 3, 3, 3)`. To finish the effect of showing it as a border, we issue `evas_object_image_border_center_fill_set(d.border, EVAS_BORDER_FILL_NONE)`.

Use 't' to change the border's thickness. 'b' will change the border image's center region rendering schema: either a hole (no rendering), blending (see the original transparent area, in this case) or solid (the transparent area gets filled). Finally, 'c' will change the border's scaling factor.

While you have the border in 'blending mode', test the command 'm': it will set whether to use or not smooth scaling on the border's source image. Since the image is small originally (30 x 30), we're obviously up-scaling it (except the border pixels, do you remember?). With this last switch, you'll either see the transparent shape in the middle flat (no smoothing) or blurry (smoothed).

The full example follows.

#ifdef HAVE_CONFIG_H
#include "config.h"
#else
#define PACKAGE_EXAMPLES_DIR "."
#endif
#include <Ecore.h>
#include <Ecore_Evas.h>
#include <stdio.h>
#include <errno.h>
#include "evas-common.h"
#define WIDTH (320)
#define HEIGHT (240)
static const char *border_img_path = PACKAGE_EXAMPLES_DIR EVAS_IMAGE_FOLDER "/red.png";
static const char *valid_path = PACKAGE_EXAMPLES_DIR EVAS_IMAGE_FOLDER "/enlightenment.png";
static const char *bogus_path = "/tmp/non-existent-220986.png";
static const char *commands = \
"commands are:\n"
"\tx - change image's x fill coordinate\n"
"\ty - change image's y fill coordinate\n"
"\tw - change image's w fill size\n"
"\te - change image's h fill size\n"
"\tf - toggle image filled property (overrides fill)\n"
"\ta - toggle image's alpha channel usage\n"
"\tm - toggle border's smooth scaling\n"
"\tt - change border's thickness\n"
"\tb - change border's center region aspect\n"
"\tc - change border's scaling factor\n"
"\ts - print image's fill property status\n"
"\th - print help\n";
struct test_data
{
Ecore_Evas *ee;
Evas *evas;
Evas_Object *img1, *img2, *bg, *border;
};
static struct test_data d = {0};
static void
_on_destroy(Ecore_Evas *ee EINA_UNUSED)
{
ecore_main_loop_quit();
}
/* Keep the example's window size in sync with the background image's size */
static void
_canvas_resize_cb(Ecore_Evas *ee)
{
int w, h;
ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
evas_object_resize(d.bg, w, h);
}
static const char *
_border_fill_mode_to_str(Evas_Border_Fill_Mode mode)
{
switch (mode)
{
case EVAS_BORDER_FILL_NONE:
return "none";
case EVAS_BORDER_FILL_DEFAULT:
return "default";
case EVAS_BORDER_FILL_SOLID:
return "solid";
default:
return "invalid";
}
}
static void
_on_keydown(void *data EINA_UNUSED,
Evas *evas EINA_UNUSED,
Evas_Object *o EINA_UNUSED,
void *einfo)
{
Evas_Event_Key_Down *ev = einfo;
if (strcmp(ev->key, "h") == 0) /* print help */
{
puts(commands);
return;
}
if (strcmp(ev->key, "m") == 0) /* toggle border image's smooth scaling */
{
Eina_Bool smooth_scale = evas_object_image_smooth_scale_get(d.border);
evas_object_image_smooth_scale_set(d.border, !smooth_scale);
printf("Image's border is now %s smooth scaling\n",
smooth_scale ? "without" : "with");
return;
}
if (strcmp(ev->key, "t") == 0) /* change border's thickness */
{
int l, r, t, b;
evas_object_image_border_get(d.border, &l, &r, &t, &b);
l = (l + 3) % 9;
r = (r + 3) % 9;
t = (t + 3) % 9;
b = (b + 3) % 9;
evas_object_image_border_set(d.border, l, r, t, b);
printf("Image's border thickness is now %d\n", l);
return;
}
if (strcmp(ev->key, "c") == 0) /* change border's scaling factor */
{
double scale = evas_object_image_border_scale_get(d.border);
scale *= 2;
if (scale > 4.0) scale = 1.0;
evas_object_image_border_scale_set(d.border, scale);
printf("Image's border scaling factor is now %f\n", scale);
return;
}
if (strcmp(ev->key, "b") == 0) /* change border's center
* region's aspect */
{
Eina_Bool fill = \
evas_object_image_border_center_fill_get(d.border);
fill = (fill + 1) % 3;
evas_object_image_border_center_fill_set(d.border, fill);
printf("Image's border center region aspect is now \"%s\"\n",
_border_fill_mode_to_str(fill));
return;
}
if (strcmp(ev->key, "a") == 0) /* toggle alpha channel usage */
{
Eina_Bool alpha = evas_object_image_alpha_get(d.img1);
evas_object_image_alpha_set(d.img1, !alpha);
printf("Image's alpha channel is now %s\n",
alpha ? "off" : "on");
return;
}
if (strcmp(ev->key, "f") == 0) /* toggle filled property */
{
Eina_Bool filled = evas_object_image_filled_get(d.img1);
evas_object_image_filled_set(d.img1, !filled);
printf("Image's x filled property is now %s\n",
filled ? "off" : "on");
return;
}
if (strcmp(ev->key, "x") == 0) /* change x fill coordinate */
{
Evas_Coord x, y, w, h;
evas_object_image_fill_get(d.img1, &x, &y, &w, &h);
x = (x + 20) % (WIDTH / 2);
evas_object_image_fill_set(d.img1, x, y, w, h);
printf("Image's x fill coordinate changed to %d\n", x);
return;
}
if (strcmp(ev->key, "y") == 0) /* change y fill coordinate */
{
Evas_Coord x, y, w, h;
evas_object_image_fill_get(d.img1, &x, &y, &w, &h);
y = (y + 20) % (HEIGHT / 2);
evas_object_image_fill_set(d.img1, x, y, w, h);
printf("Image's y fill coordinate changed to %d\n", y);
return;
}
if (strcmp(ev->key, "w") == 0) /* change w fill size */
{
Evas_Coord x, y, w, h;
evas_object_image_fill_get(d.img1, &x, &y, &w, &h);
if (w == (WIDTH / 4)) w = (WIDTH / 2);
else if (w == WIDTH / 2) w = WIDTH;
else w = (WIDTH / 4);
evas_object_image_fill_set(d.img1, x, y, w, h);
printf("Image's w fill size changed to %d\n", w);
return;
}
if (strcmp(ev->key, "e") == 0) /* change h fill size */
{
Evas_Coord x, y, w, h;
evas_object_image_fill_get(d.img1, &x, &y, &w, &h);
if (h == (HEIGHT / 4)) h = (HEIGHT / 2);
else if (h == HEIGHT / 2) h = HEIGHT;
else h = (HEIGHT / 4);
evas_object_image_fill_set(d.img1, x, y, w, h);
printf("Image's h fill size changed to %d\n", h);
return;
}
if (strcmp(ev->key, "s") == 0) /* status */
{
Evas_Coord x, y, w, h;
evas_object_image_fill_get(d.img1, &x, &y, &w, &h);
printf("Image has fill properties set to: %d, %d, %d, %d\n",
x, y, w, h);
return;
}
}
int
main(void)
{
int err;
if (!ecore_evas_init())
return EXIT_FAILURE;
/* this will give you a window with an Evas canvas under the first
* engine available */
d.ee = ecore_evas_new(NULL, 10, 10, WIDTH, HEIGHT, NULL);
if (!d.ee)
goto error;
ecore_evas_callback_destroy_set(d.ee, _on_destroy);
ecore_evas_callback_resize_set(d.ee, _canvas_resize_cb);
ecore_evas_show(d.ee);
/* the canvas pointer, de facto */
d.evas = ecore_evas_get(d.ee);
d.bg = evas_object_rectangle_add(d.evas);
evas_object_color_set(d.bg, 255, 255, 255, 255); /* white bg */
evas_object_move(d.bg, 0, 0); /* at canvas' origin */
evas_object_resize(d.bg, WIDTH, HEIGHT); /* covers full canvas */
evas_object_show(d.bg);
d.img1 = evas_object_image_add(d.evas);
evas_object_image_file_set(d.img1, valid_path, NULL);
err = evas_object_image_load_error_get(d.img1);
if (err != EVAS_LOAD_ERROR_NONE)
{
fprintf(stderr, "could not load image '%s'. error string is \"%s\"\n",
valid_path, evas_load_error_str(err));
}
else
{
printf("loaded image '%s' with succes! error string is \"%s\"\n",
valid_path, evas_load_error_str(err));
evas_object_move(d.img1, 3, 3);
evas_object_image_fill_set(d.img1, 0, 0, WIDTH / 2, HEIGHT / 2);
evas_object_resize(d.img1, WIDTH / 2, HEIGHT / 2);
evas_object_show(d.img1);
evas_object_focus_set(d.bg, EINA_TRUE);
evas_object_event_callback_add(
d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
}
/* this is a border around the image above, here just to emphasize
* its geometry */
d.border = evas_object_image_filled_add(d.evas);
evas_object_image_file_set(d.border, border_img_path, NULL);
evas_object_image_border_set(d.border, 3, 3, 3, 3);
evas_object_image_border_center_fill_set(d.border, EVAS_BORDER_FILL_NONE);
evas_object_move(d.border, 0, 0);
evas_object_resize(d.border, (WIDTH / 2) + 6, (HEIGHT / 2) + 6);
evas_object_show(d.border);
/* image loading will fail for this one -- unless one cheats and
* puts a valid image on that path */
d.img2 = evas_object_image_add(d.evas);
evas_object_image_file_set(d.img2, bogus_path, NULL);
err = evas_object_image_load_error_get(d.img2);
if (err != EVAS_LOAD_ERROR_NONE)
{
fprintf(stderr, "could not load image '%s': error string is \"%s\"\n",
bogus_path, evas_load_error_str(err));
}
else
{
evas_object_move(d.img2, WIDTH / 2, HEIGHT / 2);
evas_object_image_fill_set(d.img2, 0, 0, WIDTH / 2, HEIGHT / 2);
evas_object_resize(d.img2, WIDTH / 2, HEIGHT / 2);
evas_object_show(d.img2);
}
puts(commands);
ecore_main_loop_begin();
ecore_evas_free(d.ee);
ecore_evas_shutdown();
return 0;
error:
fprintf(stderr, "error: Requires at least one Evas engine built and linked"
" to ecore-evas for this example to run properly.\n");
ecore_evas_shutdown();
return -1;
}
Ecore_Evas.h
Evas wrapper functions.
Evas_Coord
int Evas_Coord
Type used for coordinates (in pixels, int).
Definition: Evas_Common.h:116
ecore_evas_init
EAPI int ecore_evas_init(void)
Inits the Ecore_Evas system.
Definition: ecore_evas.c:602
ecore_evas_callback_destroy_set
EAPI void ecore_evas_callback_destroy_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func)
Sets a callback for Ecore_Evas destroy events.
Definition: ecore_evas.c:1185
ecore_evas_show
EAPI void ecore_evas_show(Ecore_Evas *ee)
Shows an Ecore_Evas' window.
Definition: ecore_evas.c:1480
ecore_evas_get
EAPI Evas * ecore_evas_get(const Ecore_Evas *ee)
Gets an Ecore_Evas's Evas.
Definition: ecore_evas.c:1300
ecore_evas_geometry_get
EAPI void ecore_evas_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h)
Gets the geometry of an Ecore_Evas.
Definition: ecore_evas.c:1362
ecore_evas_callback_resize_set
EAPI void ecore_evas_callback_resize_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func)
Sets a callback for Ecore_Evas resize events.
Definition: ecore_evas.c:1140
ecore_evas_shutdown
EAPI int ecore_evas_shutdown(void)
Shuts down the Ecore_Evas system.
Definition: ecore_evas.c:666
ecore_evas_new
EAPI Ecore_Evas * ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options)
Creates a new Ecore_Evas based on engine name and common parameters.
Definition: ecore_evas.c:1039
ecore_evas_free
EAPI void ecore_evas_free(Ecore_Evas *ee)
Frees an Ecore_Evas.
Definition: ecore_evas.c:1083
ecore_main_loop_quit
void ecore_main_loop_quit(void)
Quits the main loop once all the events currently on the queue have been processed.
Definition: ecore_main.c:1321
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339
Evas
Eo Evas
An opaque handle to an Evas canvas.
Definition: Evas_Common.h:163
evas_object_image_alpha_get
EVAS_API Eina_Bool evas_object_image_alpha_get(const Evas_Object *obj)
Retrieve whether alpha channel data is being used on the given image object.
Definition: evas_image_legacy.c:110
evas_object_color_set
EVAS_API void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a)
Sets the general/main color of the given Evas object to the given one.
Definition: evas_object_main.c:2024
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185
evas_object_image_border_get
EVAS_API void evas_object_image_border_get(const Evas_Object *obj, int *l, int *r, int *t, int *b)
Dimensions of this image's border, a region that does not scale with the center area.
Definition: evas_image_legacy.c:124
evas_object_image_filled_get
EVAS_API Eina_Bool evas_object_image_filled_get(const Evas_Object *eo_obj)
Retrieve whether the image object's fill property should track the object's size.
Definition: evas_image_legacy.c:74
evas_object_image_border_scale_set
EVAS_API void evas_object_image_border_scale_set(Evas_Object *obj, double scale)
Scaling factor applied to the image borders.
Definition: evas_image_legacy.c:131
Evas_Border_Fill_Mode
Evas_Border_Fill_Mode
How an image's center region (the complement to the border region) should be rendered by Evas.
Definition: Evas_Legacy.h:5720
evas_object_image_alpha_set
EVAS_API void evas_object_image_alpha_set(Evas_Object *obj, Eina_Bool alpha)
Enable or disable alpha channel usage on the given image object.
Definition: evas_image_legacy.c:103
evas_object_image_fill_get
EVAS_API void evas_object_image_fill_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h)
Retrieve how an image object is to fill its drawing rectangle, given the (real) image bound to it.
Definition: evas_image_legacy.c:88
evas_object_image_smooth_scale_set
EVAS_API void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smooth_scale)
Sets whether to use high-quality image scaling algorithm on the given image object.
Definition: evas_image_legacy.c:407
evas_object_image_border_scale_get
EVAS_API double evas_object_image_border_scale_get(const Evas_Object *obj)
Scaling factor applied to the image borders.
Definition: evas_image_legacy.c:138
evas_object_image_filled_set
EVAS_API void evas_object_image_filled_set(Evas_Object *eo_obj, Eina_Bool value)
Set whether the image object's fill property should track the object's size.
Definition: evas_image_legacy.c:81
evas_object_image_smooth_scale_get
EVAS_API Eina_Bool evas_object_image_smooth_scale_get(const Evas_Object *obj)
Retrieves whether the given image object is using high-quality image scaling algorithm.
Definition: evas_image_legacy.c:414
EVAS_BORDER_FILL_DEFAULT
@ EVAS_BORDER_FILL_DEFAULT
Image's center region is to be blended with objects underneath it, if it has transparency.
Definition: Evas_Legacy.h:5722
EVAS_BORDER_FILL_SOLID
@ EVAS_BORDER_FILL_SOLID
Image's center region is to be made solid, even if it has transparency on it.
Definition: Evas_Legacy.h:5726
evas_object_rectangle_add
EVAS_API Evas_Object * evas_object_rectangle_add(Evas *e)
Adds a rectangle to the given evas.
Definition: evas_object_rectangle.c:78
_Evas_Event_Key_Down
Key press event.
Definition: Evas_Legacy.h:314
_Evas_Event_Key_Down::key
const char * key
The logical key : (eg shift+1 == exclamation)
Definition: Evas_Legacy.h:320