From 54a13c07c068d7c1a29b9e6d04ee70fdb4759110 Mon Sep 17 00:00:00 2001 From: Gustavo Lima Chaves Date: Thu, 30 Jun 2011 21:29:02 +0000 Subject: [PATCH] [evas] Documenting/exemplifying the following: - evas_object_image_smooth_scale_get - evas_object_image_smooth_scale_set - evas_object_image_source_get - evas_object_image_source_set - evas_object_image_source_unset - evas_object_image_stride_get SVN revision: 60887 --- legacy/evas/doc/examples.dox | 57 +++++++- legacy/evas/src/examples/Makefile.am | 4 + legacy/evas/src/examples/evas-images.c | 109 +++++++++------ legacy/evas/src/examples/evas-images2.c | 172 ++++++++++++++++++++++++ legacy/evas/src/lib/Evas.h | 80 ++++++----- 5 files changed, 346 insertions(+), 76 deletions(-) create mode 100644 legacy/evas/src/examples/evas-images2.c diff --git a/legacy/evas/doc/examples.dox b/legacy/evas/doc/examples.dox index 22cef0a260..feb3d3c2c7 100644 --- a/legacy/evas/doc/examples.dox +++ b/legacy/evas/doc/examples.dox @@ -9,6 +9,8 @@ * * @ref Example_Evas_Images * + * @ref Example_Evas_Images_2 + * * @ref Example_Evas_Events * * @ref Example_Evas_Object_Manipulation @@ -74,13 +76,13 @@ * one or other ways of setting an image object's viewport with regard * to its image source. * - * There are three commands which deal with the border image. This red + * 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 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, + * for the border is a solid red rectangle, with a transparent @b + * 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 @@ -89,12 +91,55 @@ * 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 originallly (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. * * @include evas-images.c * @example evas-images.c */ +/** + * @page Example_Evas_Images_2 Some more image object functions examples (2nd block) + * @dontinclude evas-images2.c + * + * In this example, we have three images on the canvas, but one of + * them is special -- we're using it as a proxy image + * object. It will mirror the contents of the other two images + * (which are the ones on the top of the canvas), one at a time: + * @skip d.proxy_img = evas_object_image_filled_add(d.evas); + * @until evas_object_show(d.proxy_img); + * As in other examples, we have a command line interface on it. + * @dontinclude evas-images2.c + * @skip commands + * @until ; + * The 'p' one will change the source of the proxy image to one of the + * other two, as seem above. + * @skip if (strcmp(ev->keyname, "p") == 0) + * @until } + * Note the top right image, the smaller one: + * @dontinclude evas-images2.c + * @skip noise_img = + * @until show + * There's a last command to print it's @b stride value. Since its + * created with one quarter of the canvas's original width + * @dontinclude evas-images2.c + * @skip define WIDTH + * @until define HEIGHT + * you can check this value. + * + * The full example follows. + * + * @include evas-images2.c + * @example evas-images2.c + */ + /** * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example * @dontinclude evas-events.c diff --git a/legacy/evas/src/examples/Makefile.am b/legacy/evas/src/examples/Makefile.am index b6da36b71f..8afa04f8d4 100644 --- a/legacy/evas/src/examples/Makefile.am +++ b/legacy/evas/src/examples/Makefile.am @@ -65,6 +65,10 @@ pkglib_PROGRAMS += evas_stacking evas_stacking_SOURCES = evas-stacking.c evas_stacking_LDADD = $(top_builddir)/src/lib/libevas.la @ECORE_EVAS_LIBS@ +pkglib_PROGRAMS += evas_images2 +evas_images2_SOURCES = evas-images2.c +evas_images2_LDADD = $(top_builddir)/src/lib/libevas.la @ECORE_EVAS_LIBS@ + #the ones using ecore_evas and edje follow AM_CPPFLAGS += @EDJE_CFLAGS@ diff --git a/legacy/evas/src/examples/evas-images.c b/legacy/evas/src/examples/evas-images.c index 12f1fffc7d..54e1aeeb08 100644 --- a/legacy/evas/src/examples/evas-images.c +++ b/legacy/evas/src/examples/evas-images.c @@ -1,15 +1,13 @@ /** - * Simple Evas example illustrating some image objects functions and evas_load_error_str()'s usage. + * Simple Evas example illustrating some image objects functions * * You'll need at least one engine built for it (excluding the buffer * one) and the png image loader also built. See stdout/stderr for * output. * * @verbatim - * gcc -o evas-load-error-str evas-load-error-str.c `pkg-config --libs \ - * --cflags ecore-evas` + * gcc -o evas-images evas-images.c `pkg-config --libs --cflags ecore-evas` * @endverbatim - * */ #ifdef HAVE_CONFIG_H @@ -29,42 +27,63 @@ static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png"; static const char *valid_path = PACKAGE_EXAMPLES_DIR "/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" - "\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"; + "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 { - Evas *evas; - Ecore_Evas *ee; + Ecore_Evas *ee; + Evas *evas; Evas_Object *img1, *img2, *bg, *border; }; static struct test_data d = {0}; -static const char* +static void +_on_destroy(Ecore_Evas *ee __UNUSED__) +{ + ecore_main_loop_quit(); +} + +/* here just to keep our example's window size and background image's + * size in synchrony */ +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"; - } + 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 @@ -81,18 +100,30 @@ _on_keydown(void *data __UNUSED__, return; } + if (strcmp(ev->keyname, "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); + + fprintf(stdout, "Image's border is now %s smooth scaling\n", + smooth_scale ? "without" : "with"); + + return; + } + if (strcmp(ev->keyname, "t") == 0) /* change border's thickness */ { - int l, r, t, b; + int l, r, t, b; - evas_object_image_border_get(d.border, &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; + 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); + evas_object_image_border_set(d.border, l, r, t, b); fprintf(stdout, "Image's border thickness is now %d\n", l); @@ -117,7 +148,7 @@ _on_keydown(void *data __UNUSED__, * region's aspect */ { Eina_Bool fill = \ - evas_object_image_border_center_fill_get(d.border); + evas_object_image_border_center_fill_get(d.border); fill = (fill + 1) % 3; @@ -234,6 +265,8 @@ main(void) 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 */ diff --git a/legacy/evas/src/examples/evas-images2.c b/legacy/evas/src/examples/evas-images2.c new file mode 100644 index 0000000000..5ba251a5bb --- /dev/null +++ b/legacy/evas/src/examples/evas-images2.c @@ -0,0 +1,172 @@ +/** + * Simple Evas example illustrating some image objects functions + * + * You'll need at least one engine built for it (excluding the buffer + * one) and the png image loader also built. See stdout/stderr for + * output. + * + * @verbatim + * gcc -o evas-images3 evas-images3.c `pkg-config --libs --cflags ecore-evas` + * @endverbatim + */ + +#ifdef HAVE_CONFIG_H + +#include "config.h" +#endif + +#include +#include +#include +#include + +#define WIDTH (320) +#define HEIGHT (240) + +static const char *img_path = PACKAGE_EXAMPLES_DIR "/enlightenment.png"; +static const char *commands = \ + "commands are:\n" + "\tp - change proxy image's source\n" + "\ts - print noise image's stride value\n" + "\th - print help\n"; + +struct test_data +{ + Ecore_Evas *ee; + Evas *evas; + Evas_Object *logo, *noise_img, *proxy_img, *bg; +}; + +static struct test_data d = {0}; + +static void +_on_destroy(Ecore_Evas *ee __UNUSED__) +{ + ecore_main_loop_quit(); +} + +/* here just to keep our example's window size and background image's + * size in synchrony */ +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 void +_on_keydown(void *data __UNUSED__, + Evas *evas __UNUSED__, + Evas_Object *o __UNUSED__, + void *einfo) +{ + Evas_Event_Key_Down *ev = einfo; + + if (strcmp(ev->keyname, "h") == 0) /* print help */ + { + fprintf(stdout, commands); + return; + } + + if (strcmp(ev->keyname, "s") == 0) /* print proxy image' stride value */ + { + int stride = evas_object_image_stride_get(d.noise_img); + + fprintf(stdout,"Image has row stride value of %d, which accounts" + " for %d pixels\n", stride, stride / 4); + + return; + } + + if (strcmp(ev->keyname, "p") == 0) /* change proxy's source */ + { + Evas_Object *source = evas_object_image_source_get(d.proxy_img); + + if (source == d.logo) source = d.noise_img; + else source = d.logo; + + evas_object_image_source_set(d.proxy_img, source); + + fprintf(stdout, "Proxy image's source changed\n"); + + return; + } +} + +int +main(void) +{ + unsigned int i; + unsigned int pixels[(WIDTH / 4) * (HEIGHT / 4)]; + + srand(time(NULL)); + + 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); + + evas_object_focus_set(d.bg, EINA_TRUE); + evas_object_event_callback_add( + d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL); + + d.logo = evas_object_image_filled_add(d.evas); + evas_object_image_file_set(d.logo, img_path, NULL); + evas_object_image_fill_set(d.logo, 0, 0, WIDTH / 2, HEIGHT / 2); + evas_object_resize(d.logo, WIDTH / 2, HEIGHT / 2); + evas_object_show(d.logo); + + /* creating noise image */ + for (i = 0; i < sizeof(pixels) / sizeof(pixels[0]); i++) + pixels[i] = rand(); + + d.noise_img = evas_object_image_add(d.evas); + evas_object_image_size_set(d.noise_img, WIDTH / 4, HEIGHT / 4); + evas_object_image_data_set(d.noise_img, pixels); + evas_object_image_filled_set(d.noise_img, EINA_TRUE); + evas_object_move(d.noise_img, (WIDTH * 3)/ 4, 0); + evas_object_resize(d.noise_img, WIDTH / 4, HEIGHT / 4); + evas_object_show(d.noise_img); + fprintf(stdout, "Creating noise image with size %d, %d\n", + WIDTH / 4, HEIGHT / 4); + + /* todo: option to save noise image to /tmp dir */ + + d.proxy_img = evas_object_image_filled_add(d.evas); + evas_object_image_source_set(d.proxy_img, d.logo); + evas_object_move(d.proxy_img, WIDTH / 4, HEIGHT / 2); + evas_object_resize(d.proxy_img, WIDTH / 2, HEIGHT / 2); + evas_object_show(d.proxy_img); + + fprintf(stdout, commands); + ecore_main_loop_begin(); + + ecore_evas_free(d.ee); + ecore_evas_shutdown(); + return 0; + +error: + fprintf(stderr, "you got to have at least one evas engine built and linked" + " up to ecore-evas for this example to run properly.\n"); + ecore_evas_shutdown(); + return -1; +} diff --git a/legacy/evas/src/lib/Evas.h b/legacy/evas/src/lib/Evas.h index d6657ef9f0..b2a0462726 100644 --- a/legacy/evas/src/lib/Evas.h +++ b/legacy/evas/src/lib/Evas.h @@ -5746,13 +5746,13 @@ EAPI void evas_object_image_size_set (Evas_Obj EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); /** - * Retrieves the row stride of the given image object, - * - * The row stride is the number of units between the start of a - * row and the start of the next row. + * Retrieves the row stride of the given image object. * * @param obj The given image object. - * @return The stride of the image. + * @return The stride of the image (in bytes). + * + * The row stride is the number of bytes between the start of a row + * and the start of the next row for image data. */ EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -5884,26 +5884,32 @@ EAPI void evas_object_image_alpha_set (Evas_Obj EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Sets whether to use of high-quality image scaling algorithm - * of the given image object. - * - * When enabled, a higher quality image scaling algorithm is used when - * scaling images to sizes other than the source image. This gives - * better results but is more computationally expensive. + * Sets whether to use high-quality image scaling algorithm on the + * given image object. * * @param obj The given image object. * @param smooth_scale Whether to use smooth scale or not. + * + * When enabled, a higher quality image scaling algorithm is used when + * scaling images to sizes other than the source image's original + * one. This gives better results but is more computationally + * expensive. + * + * @note Image objects get created originally with smooth scaling @b + * on. + * + * @see evas_object_image_smooth_scale_get() */ EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1); /** - * Retrieves whether the given image object is using use a - * high-quality image scaling algorithm. - * - * See @ref evas_object_image_smooth_scale_set for more details. + * Retrieves whether the given image object is using high-quality + * image scaling algorithm. * * @param obj The given image object. * @return Whether smooth scale is being used. + * + * See @ref evas_object_image_smooth_scale_set() for more details. */ EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -6179,39 +6185,49 @@ EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Ev EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1); /** - * Set the source object on a proxy object. + * Set the source object on an image object to used as a @b proxy. + * + * @param obj Proxy (image) object. + * @param src Source object to use for the proxy. + * @return @c EINA_TRUE on success, @c EINA_FALSE on error. * - * The source must be another object. The proxy will have the same base - * appearance of the source object. Obviously other effects may be applied to - * the proxy, such as a map to create a reflection of the original object. + * If an image object is set to behave as a @b proxy, it will mirror + * the rendering contents of a given @b source object in its drawing + * region, without affecting that source in any way. The source must + * be another valid Evas object. Other effects may be applied to the + * proxy, such as a map (see evas_object_map_set()) to create a + * reflection of the original object (for example). * - * Any existing source object will be removed. Setting the src to NULL clears - * the proxy object. + * Any existing source object on @p obj will be removed after this + * call. Setting @p src to @c NULL clears the proxy object (not in + * "proxy state" anymore). * - * You cannot set a proxy on a proxy. + * @warning You cannot set a proxy as another proxy's source. * - * @param obj Proxy object. - * @param src Source of the proxy. - * @return EINA_TRUE on success, EINA_FALSE on error. + * @see evas_object_image_source_get() + * @see evas_object_image_source_unset() */ EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1); /** - * Get the current source object of an image. + * Get the current source object of an image object. * * @param obj Image object - * @return Source object, or @c NULL on error. + * @return Source object (if any), or @c NULL, if not in "proxy mode" + * (or on errors). + * + * @see evas_object_image_source_set() for more details */ EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Clear the source on a proxy image. - * - * This is equivalent to calling evas_object_image_source_set with a NULL - * source. + * Clear the source object on a proxy image object. * * @param obj Image object to clear source of. - * @return EINA_TRUE on success, EINA_FALSE on error. + * @return @c EINA_TRUE on success, @c EINA_FALSE on error. + * + * This is equivalent to calling evas_object_image_source_set() with a + * @c NULL source. */ EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1); -- 2.34.1