*
* @ref Example_Evas_Init_Shutdown
*
- * @ref Example_Evas_Load_Error_Str
+ * @ref Example_Evas_Images
*
* @ref Example_Evas_Events
*
*/
/**
- * @page Example_Evas_Load_Error_Str Some image object functions and evas_load_error_str() example
- * @dontinclude evas-load-error-str.c
+ * @page Example_Evas_Images Some image object functions examples
+ * @dontinclude evas-images.c
*
* 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:
- * @skip img1 = evas_object_image_add(evas);
+ * @skip img1 = evas_object_image_add(d.evas);
* @until ecore_main_loop_begin
* See there is a border image around the top left one, <b>which is
* the one that should be displayed</b>. The other one will (on
* purpose) fail to load, because we set a wrong file path as image
* source on it:
- * @dontinclude evas-load-error-str.c
+ * @dontinclude evas-images.c
* @skip valid_path
* @until bogus_path
* 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.
+ * the error. We'll talk about the border image further.
*
* To interact with the program, there's a command line interface,
* whose help string can be asked for with the 'h' key:
- * @dontinclude evas-events.c
- * @skip if (strcmp(ev->keyname, "h") == 0)
- * @until }
+ * @dontinclude evas-images.c
+ * @skip commands
+ * @until ;
* The first four commands will change the top left images's @b fill property
* values, which dictate how the source image (Enlightenment's logo)
* is to be displayed through the image object's area. Experiment with
* 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
+ * frame is there to illustrate <b>image borders</b>. 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
+ * <code>evas_object_image_border_set(d.border, 3, 3, 3, 3)</code>. To
+ * finish the effect of showing it as a border, we issue
+ * <code>evas_object_image_border_center_fill_set(d.border,
+ * EVAS_BORDER_FILL_NONE)</code>.
+ *
+ * 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.
+ *
* The full example follows.
*
- * @include evas-load-error-str.c
- * @example evas-load-error-str.c
+ * @include evas-images.c
+ * @example evas-images.c
*/
/**
#the ones using ecore_evas follow
AM_CPPFLAGS += @ECORE_EVAS_CFLAGS@
-pkglib_PROGRAMS += evas_load_error_str
-evas_load_error_str_SOURCES = evas-load-error-str.c
-evas_load_error_str_LDADD = $(top_builddir)/src/lib/libevas.la @ECORE_EVAS_LIBS@
+pkglib_PROGRAMS += evas_images
+evas_images_SOURCES = evas-images.c
+evas_images_LDADD = $(top_builddir)/src/lib/libevas.la @ECORE_EVAS_LIBS@
pkglib_PROGRAMS += evas_events
evas_events_SOURCES = evas-events.c
$(EDCS) \
$(srcdir)/evas-buffer-simple.c \
$(srcdir)/evas-init-shutdown.c \
- $(srcdir)/evas-load-error-str.c \
+ $(srcdir)/evas-images.c \
$(srcdir)/evas-object-manipulation.c \
$(srcdir)/evas-events.c \
$(srcdir)/evas-aspect-hints.c \
EXTRA_DIST = $(EDCS) \
$(srcdir)/evas-buffer-simple.c \
$(srcdir)/evas-init-shutdown.c \
- $(srcdir)/evas-load-error-str.c \
+ $(srcdir)/evas-images.c \
$(srcdir)/evas-object-manipulation.c \
$(srcdir)/evas-events.c \
$(srcdir)/evas-aspect-hints.c \
--- /dev/null
+/**
+ * Simple Evas example illustrating some image objects functions and evas_load_error_str()'s usage.
+ *
+ * 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`
+ * @endverbatim
+ *
+ */
+
+#ifdef HAVE_CONFIG_H
+
+#include "config.h"
+#endif
+
+#include <Ecore.h>
+#include <Ecore_Evas.h>
+#include <stdio.h>
+#include <errno.h>
+
+#define WIDTH (320)
+#define HEIGHT (240)
+
+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";
+
+struct test_data
+{
+ Evas *evas;
+ Ecore_Evas *ee;
+ Evas_Object *img1, *img2, *bg, *border;
+};
+
+static struct test_data d = {0};
+
+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 __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, "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);
+
+ fprintf(stdout, "Image's border thickness is now %d\n", l);
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "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);
+
+ fprintf(stdout, "Image's border scaling factor is now %f\n", scale);
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "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);
+
+ fprintf(stdout, "Image's border center region aspect is now \"%s\"\n",
+ _border_fill_mode_to_str(fill));
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "a") == 0) /* toggle alpha channel usage */
+ {
+ Eina_Bool alpha = evas_object_image_alpha_get(d.img1);
+
+ evas_object_image_alpha_set(d.img1, !alpha);
+
+ fprintf(stdout, "Image's alpha channel is now %s\n",
+ alpha ? "off" : "on");
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "f") == 0) /* toggle filled property */
+ {
+ Eina_Bool filled = evas_object_image_filled_get(d.img1);
+
+ evas_object_image_filled_set(d.img1, !filled);
+
+ fprintf(stdout, "Image's x filled property is now %s\n",
+ filled ? "off" : "on");
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "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);
+
+ fprintf(stdout, "Image's x fill coordinate changed to %d\n", x);
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "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);
+
+ fprintf(stdout, "Image's y fill coordinate changed to %d\n", y);
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "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 / 2)) w = (WIDTH / 2);
+ else w = WIDTH;
+ evas_object_image_fill_set(d.img1, x, y, w, h);
+
+ fprintf(stdout, "Image's w fill size changed to %d\n", w);
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "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 / 2)) h = (HEIGHT / 2);
+ else h = HEIGHT;
+ evas_object_image_fill_set(d.img1, x, y, w, h);
+
+ fprintf(stdout, "Image's h fill size changed to %d\n", h);
+
+ return;
+ }
+
+ if (strcmp(ev->keyname, "s") == 0) /* status */
+ {
+ Evas_Coord x, y, w, h;
+
+ evas_object_image_fill_get(d.img1, &x, &y, &w, &h);
+
+ fprintf(stdout, "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_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
+ {
+ fprintf(stdout,
+ "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);
+ }
+
+ 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;
+}
+++ /dev/null
-/**
- * Simple Evas example illustrating some image objects functions and evas_load_error_str()'s usage.
- *
- * 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`
- * @endverbatim
- *
- */
-
-#ifdef HAVE_CONFIG_H
-
-#include "config.h"
-#endif
-
-#include <Ecore.h>
-#include <Ecore_Evas.h>
-#include <stdio.h>
-#include <errno.h>
-
-#define WIDTH (320)
-#define HEIGHT (240)
-
-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 void
-_on_keydown(void *data,
- Evas *evas __UNUSED__,
- Evas_Object *o __UNUSED__,
- void *einfo)
-{
- Evas_Object *img = data;
- Evas_Event_Key_Down *ev = einfo;
-
- if (strcmp(ev->keyname, "h") == 0) /* print help */
- {
- fprintf(stdout, "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"
- "\ts - print image's fill property status\n"
- "\th - print help\n");
- return;
- }
-
- if (strcmp(ev->keyname, "f") == 0) /* toggle filled property */
- {
- Eina_Bool filled = evas_object_image_filled_get(img);
-
- evas_object_image_filled_set(img, !filled);
-
- fprintf(stdout, "Image's x filled property is now %s\n",
- filled ? "off" : "on");
-
- return;
- }
-
- if (strcmp(ev->keyname, "x") == 0) /* change x fill coordinate */
- {
- Evas_Coord x, y, w, h;
-
- evas_object_image_fill_get(img, &x, &y, &w, &h);
- x = (x + 20) % (WIDTH / 2);
- evas_object_image_fill_set(img, x, y, w, h);
-
- fprintf(stdout, "Image's x fill coordinate changed to %d\n", x);
-
- return;
- }
-
- if (strcmp(ev->keyname, "y") == 0) /* change y fill coordinate */
- {
- Evas_Coord x, y, w, h;
-
- evas_object_image_fill_get(img, &x, &y, &w, &h);
- y = (y + 20) % (HEIGHT / 2);
- evas_object_image_fill_set(img, x, y, w, h);
-
- fprintf(stdout, "Image's y fill coordinate changed to %d\n", y);
-
- return;
- }
-
- if (strcmp(ev->keyname, "w") == 0) /* change w fill size */
- {
- Evas_Coord x, y, w, h;
-
- evas_object_image_fill_get(img, &x, &y, &w, &h);
- if (w > (WIDTH / 2)) w = (WIDTH / 2);
- else w = WIDTH;
- evas_object_image_fill_set(img, x, y, w, h);
-
- fprintf(stdout, "Image's w fill size changed to %d\n", w);
-
- return;
- }
-
- if (strcmp(ev->keyname, "e") == 0) /* change h fill size */
- {
- Evas_Coord x, y, w, h;
-
- evas_object_image_fill_get(img, &x, &y, &w, &h);
- if (h > (HEIGHT / 2)) h = (HEIGHT / 2);
- else h = HEIGHT;
- evas_object_image_fill_set(img, x, y, w, h);
-
- fprintf(stdout, "Image's h fill size changed to %d\n", h);
-
- return;
- }
-
- if (strcmp(ev->keyname, "s") == 0) /* status */
- {
- Evas_Coord x, y, w, h;
-
- evas_object_image_fill_get(img, &x, &y, &w, &h);
-
- fprintf(stdout, "Image has fill properties set to: %d, %d, %d, %d\n",
- x, y, w, h);
-
- return;
- }
-}
-
-int
-main(void)
-{
- Evas *evas;
- Ecore_Evas *ee;
- Evas_Object *img1, *img2, *bg, *border;
- int err;
-
- if (!ecore_evas_init())
- return EXIT_FAILURE;
-
- /* this will give you a window with an Evas canvas under the first
- * engine available */
- ee = ecore_evas_new(NULL, 10, 10, WIDTH, HEIGHT, NULL);
- if (!ee)
- goto error;
-
- ecore_evas_show(ee);
-
- /* the canvas pointer, de facto */
- evas = ecore_evas_get(ee);
-
- bg = evas_object_rectangle_add(evas);
- evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */
- evas_object_move(bg, 0, 0); /* at canvas' origin */
- evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */
- evas_object_show(bg);
-
- img1 = evas_object_image_add(evas);
- evas_object_image_file_set(img1, valid_path, NULL);
- err = evas_object_image_load_error_get(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
- {
- fprintf(stdout,
- "loaded image '%s' with succes! error string is \"%s\"\n",
- valid_path, evas_load_error_str(err));
-
- evas_object_move(img1, 0, 0);
- evas_object_image_fill_set(img1, 0, 0, WIDTH / 2, HEIGHT / 2);
- evas_object_resize(img1, WIDTH / 2, HEIGHT / 2);
- evas_object_show(img1);
-
- evas_object_focus_set(bg, EINA_TRUE);
- evas_object_event_callback_add(
- bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, img1);
- }
-
- /* this is a border around the image above, here just to emphasize
- * its geometry */
- border = evas_object_image_filled_add(evas);
- evas_object_image_file_set(border, border_img_path, NULL);
- evas_object_image_border_set(border, 3, 3, 3, 3);
- evas_object_image_border_center_fill_set(border, EVAS_BORDER_FILL_NONE);
-
- evas_object_move(border, 0, 0);
- evas_object_resize(border, (WIDTH / 2) + 3, (HEIGHT / 2) + 3);
- evas_object_show(border);
-
- /* image loading will fail for this one -- unless one cheats and
- * puts a valid image on that path */
- img2 = evas_object_image_add(evas);
- evas_object_image_file_set(img2, bogus_path, NULL);
- err = evas_object_image_load_error_get(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(img2, WIDTH / 2, HEIGHT / 2);
- evas_object_image_fill_set(img2, 0, 0, WIDTH / 2, HEIGHT / 2);
- evas_object_resize(img2, WIDTH / 2, HEIGHT / 2);
- evas_object_show(img2);
- }
-
- ecore_main_loop_begin();
-
- ecore_evas_free(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;
-}
typedef enum _Evas_Border_Fill_Mode
{
- EVAS_BORDER_FILL_NONE = 0,
- EVAS_BORDER_FILL_DEFAULT = 1,
- EVAS_BORDER_FILL_SOLID = 2
-} Evas_Border_Fill_Mode;
+ EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */
+ EVAS_BORDER_FILL_DEFAULT = 1, /**< Image's center region is to be @b blended with objects underneath it, if it has transparency. This is the default behavior for image objects */
+ EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */
+} Evas_Border_Fill_Mode; /**< How a image's center region (the complement to the border region) should be rendered by Evas */
typedef enum _Evas_Image_Scale_Hint
{
* for alpha masking.
*
* Some examples on this group of functions can be found @ref
- * Example_Evas_Load_Error_Str "here".
+ * Example_Evas_Images "here".
*
* @ingroup Evas_Object_Specific
*/
+
+/**
+ * @addtogroup Evas_Object_Image
+ * @{
+ */
+
typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
/**
- * Sets how much of each border of the given image object is not
- * to be scaled.
+ * Set the dimensions for an image object's border, a region which @b
+ * won't ever be scaled together with its center.
+ *
+ * @param obj The given image object.
+ * @param l The border's left width.
+ * @param r The border's right width.
+ * @param t The border's top width.
+ * @param b The border's bottom width.
*
- * When rendering, the image may be scaled to fit the size of the
- * image object. This function sets what area around the border of the
- * image is not to be scaled. This sort of function is useful for
- * widget theming, where, for example, buttons may be of varying
- * sizes, but the border size must remain constant.
+ * When Evas is rendering, an image source may be scaled to fit the
+ * size of its image object. This function sets an area from the
+ * borders of the image inwards which is @b not to be scaled. This
+ * function is useful for making frames and for widget theming, where,
+ * for example, buttons may be of varying sizes, but their border size
+ * must remain constant.
*
- * The units used for @p l, @p r, @p t and @p b are output units.
+ * The units used for @p l, @p r, @p t and @p b are canvas units.
*
- * @param obj The given image object.
- * @param l Distance of the left border that is not to be stretched.
- * @param r Distance of the right border that is not to be stretched.
- * @param t Distance of the top border that is not to be stretched.
- * @param b Distance of the bottom border that is not to be stretched.
+ * @note The border region itself @b may be scaled by the
+ * evas_object_image_border_scale_set() function.
+ *
+ * @note By default, image objects have no borders set, i. e. @c l, @c
+ * r, @c t and @c b start as @c 0.
+ *
+ * @see evas_object_image_border_get()
+ * @see evas_object_image_border_center_fill_set()
*/
EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
/**
- * Retrieves how much of each border of the given image object is not
- * to be scaled.
- *
- * See @ref evas_object_image_border_set for more details.
+ * Retrieve the dimensions for an image object's border, a region
+ * which @b won't ever be scaled together with its center.
*
* @param obj The given image object.
- * @param l Location to store the left border width in, or @c NULL.
- * @param r Location to store the right border width in, or @c NULL.
- * @param t Location to store the top border width in, or @c NULL.
- * @param b Location to store the bottom border width in, or @c NULL.
+ * @param l Location to store the border's left width in.
+ * @param r Location to store the border's right width in.
+ * @param t Location to store the border's top width in.
+ * @param b Location to store the border's bottom width in.
+ *
+ * @note Use @c NULL pointers on the border components you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * See @ref evas_object_image_border_set() for more details.
*/
EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
/**
- * Sets if the center part of the given image object (not the border)
- * should be drawn.
- *
- * When rendering, the image may be scaled to fit the size of the
- * image object. This function sets if the center part of the scaled
- * image is to be drawn or left completely blank, or forced to be
- * solid. Very useful for frames and decorations.
+ * Sets @b how the center part of the given image object (not the
+ * borders) should be drawn when Evas is rendering it.
*
* @param obj The given image object.
- * @param fill Fill mode of the middle.
+ * @param fill Fill mode of the center region of @p obj (a value in
+ * #Evas_Border_Fill_Mode).
+ *
+ * This function sets how the center part of the image object's source
+ * image is to be drawn, which must be one of the values in
+ * #Evas_Border_Fill_Mode. By center we mean the complementary part of
+ * that defined by evas_object_image_border_set(). This one is very
+ * useful for making frames and decorations. You would most probably
+ * also be using a filled image (as in evas_object_image_filled_set())
+ * to use as a frame.
+ *
+ * @see evas_object_image_border_center_fill_get()
*/
EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
/**
- * Retrieves if the center of the given image object is to be drawn or
- * not.
- *
- * See @ref evas_object_image_fill_set for more details.
+ * Retrieves @b how the center part of the given image object (not the
+ * borders) is to be drawn when Evas is rendering it.
*
* @param obj The given image object.
- * @return Fill mode of the center.
+ * @return fill Fill mode of the center region of @p obj (a value in
+ * #Evas_Border_Fill_Mode).
+ *
+ * See @ref evas_object_image_fill_set() for more details.
*/
EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
* so the bound image will fill the whole object's area.
*
* @see evas_object_image_filled_add()
- * @see evas_object_image_fill_set()
+ * @see evas_object_image_fill_get()
*/
EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
- * Sets a scale factor (multiplier) for the borders of an image
+ * Sets the scaling factor (multiplier) for the borders of an image
+ * object.
*
* @param obj The given image object.
- * @param scale The scale factor (default is 1.0 - i.e. no scale)
+ * @param scale The scale factor (default is @c 1.0 - i.e. no scaling)
+ *
+ * @see evas_object_image_border_set()
+ * @see evas_object_image_border_scale_get()
*/
EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
/**
- * Retrieves the border scale factor
- *
- * See evas_object_image_border_scale_set()
+ * Retrieves the scaling factor (multiplier) for the borders of an
+ * image object.
*
* @param obj The given image object.
- * @return The scale factor
+ * @return The scale factor set for its borders
+ *
+ * @see evas_object_image_border_set()
+ * @see evas_object_image_border_scale_set()
*/
EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
/**
- * Enable or disable alpha channel of the given image object.
+ * Enable or disable alpha channel usage on the given image object.
+ *
+ * @param obj The given image object.
+ * @param has_alpha Whether to use alpha channel (@c EINA_TRUE) data
+ * or not (@c EINA_FALSE).
*
* This function sets a flag on an image object indicating whether or
- * not to use alpha channel data. A value of 1 indicates to use alpha
- * channel data, and 0 indicates to ignore any alpha channel
+ * not to use alpha channel data. A value of @c EINA_TRUE makes it use
+ * alpha channel data, and @c EINA_FALSE makes it ignore that
* data. Note that this has nothing to do with an object's color as
* manipulated by evas_object_color_set().
*
- * @param obj The given image object.
- * @param has_alpha Whether to use alpha channel data or not.
+ * @see evas_object_image_alpha_get()
*/
EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieves the alpha channel setting of the given image object.
+ * Retrieve whether alpha channel data is being used on the given
+ * image object.
*
* @param obj The given image object.
- * @return Whether the alpha channel data is being used.
+ * @return Whether the alpha channel data is being used (@c EINA_TRUE)
+ * or not (@c EINA_FALSE).
*
- * This function returns 1 if the image object's alpha channel is
- * being used, or 0 otherwise.
+ * This function returns @c EINA_TRUE if the image object's alpha
+ * channel is being used, or @c EINA_FALSE otherwise.
*
- * See @ref evas_object_image_alpha_set for more details.
+ * See @ref evas_object_image_alpha_set() for more details.
*/
EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
/**
+ * @}
+ */
+
+/**
* @defgroup Evas_Object_Text Text Object Functions
*
* Functions that operate on single line, single style text objects.
* of evas_load_error_str() would be (if no other errors occur):
* <code>"No error on load"</code> and <code>"File (or file path) does
* not exist"</code>, respectively. See the full @ref
- * Example_Evas_Load_Error_Str "example".
+ * Example_Evas_Images "example".
*
* @ingroup Evas_Utils
*/
projects / framework / uifw / evas.git / commitdiff
