[evas] Documenting the following.

 - evas_object_image_content_hint_get
 - evas_object_image_content_hint_set
 - evas_object_image_data_copy_set
 - evas_object_image_data_get
 - evas_object_image_data_set
 - evas_object_image_data_update_add

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/evas@60918 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/doc/examples.dox b/doc/examples.dox
index c0276ad..545f463 100644 (file)
--- a/doc/examples.dox
+++ b/doc/examples.dox
@@ -128,9 +128,11 @@
  * @skip noise_img =
  * @until show
  * Since we are creating the data for its pixel buffer ourselves, we
- * have to set its size with @c evas_object_image_size_set. There's a
- * last command to print it's @b stride value. Since its created with
- * one quarter of the canvas's original width
+ * have to set its size with evas_object_image_size_set(), first. We
+ * set our data with the function evas_object_image_data_set(),
+ * whose second argument is a buffer with random data. 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

diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 8afa04f..4d6a199 100644 (file)
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -99,6 +99,7 @@ files_DATA += \
        $(srcdir)/evas-buffer-simple.c \
        $(srcdir)/evas-init-shutdown.c \
        $(srcdir)/evas-images.c \
+       $(srcdir)/evas-images2.c \
        $(srcdir)/evas-object-manipulation.c \
        $(srcdir)/evas-events.c \
        $(srcdir)/evas-aspect-hints.c \
@@ -110,6 +111,7 @@ EXTRA_DIST = $(EDCS) \
        $(srcdir)/evas-buffer-simple.c \
        $(srcdir)/evas-init-shutdown.c \
        $(srcdir)/evas-images.c \
+       $(srcdir)/evas-images2.c \
        $(srcdir)/evas-object-manipulation.c \
        $(srcdir)/evas-events.c \
        $(srcdir)/evas-aspect-hints.c \

diff --git a/src/examples/evas-images2.c b/src/examples/evas-images2.c
index df9b8f8..ba7766c 100644 (file)
--- a/src/examples/evas-images2.c
+++ b/src/examples/evas-images2.c
@@ -6,13 +6,18 @@
  * for output.
  *
  * @verbatim
- * gcc -o evas-images3 evas-images3.c `pkg-config --libs --cflags ecore-evas`
+ * gcc -o evas-images2 evas-images2.c `pkg-config --libs --cflags evas ecore ecore-evas`
  * @endverbatim
  */
 
 #ifdef HAVE_CONFIG_H
 
 #include "config.h"
+#else
+
+#define PACKAGE_EXAMPLES_DIR "."
+#define __UNUSED__
+
 #endif
 
 #include <Ecore.h>
@@ -161,7 +166,6 @@ main(void)
    evas_object_image_preload(d.logo, EINA_TRUE);
 
    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);
 

diff --git a/src/lib/Evas.h b/src/lib/Evas.h
index d98e749..48ae28b 100644 (file)
--- a/src/lib/Evas.h
+++ b/src/lib/Evas.h
@@ -689,7 +689,7 @@ typedef enum _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 */
+} Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */
 
 typedef enum _Evas_Image_Scale_Hint
 {
@@ -706,10 +706,10 @@ typedef enum _Evas_Engine_Render_Mode
 
 typedef enum _Evas_Image_Content_Hint
 {
-   EVAS_IMAGE_CONTENT_HINT_NONE = 0,
-   EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1,
-   EVAS_IMAGE_CONTENT_HINT_STATIC = 2
-} Evas_Image_Content_Hint;
+   EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */
+   EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents will change on time */
+   EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents won't change on time */
+} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */
 
 struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
 {
@@ -5770,11 +5770,15 @@ EAPI Evas_Load_Error          evas_object_image_load_error_get         (const Ev
 /**
  * Sets the raw image data of the given image object.
  *
- * Note that the raw data must be of the same size and colorspace of
- * the image. If data is NULL the current image data will be freed.
- *
  * @param obj The given image object.
  * @param data The raw data, or @c NULL.
+ *
+ * Note that the raw data must be of the same size (see
+ * evas_object_image_size_set()) and colorspace (see
+ * evas_object_image_colorspace_set()) of the image. If data is @c
+ * NULL, the current image data will be freed.
+ *
+ * @see evas_object_image_data_get()
  */
 EAPI void                     evas_object_image_data_set               (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
 
@@ -5799,25 +5803,31 @@ EAPI void                    *evas_object_image_data_convert           (Evas_Obj
 /**
  * Get a pointer to the raw image data of the given image object.
  *
+ * @param obj The given image object.
+ * @param for_writing Whether the data being retrieved will be
+ *        modified (@c EINA_TRUE) or not (@c EINA_FALSE).
+ * @return The raw image data.
+ *
  * This function returns a pointer to an image object's internal pixel
  * buffer, for reading only or read/write. If you request it for
  * writing, the image will be marked dirty so that it gets redrawn at
  * the next update.
  *
- * This is best suited when you want to modify an existing image,
+ * This is best suited for when you want to modify an existing image,
  * without changing its dimensions.
  *
- * @param obj The given image object.
- * @param for_writing Whether the data being retrieved will be modified.
- * @return The raw image data.
+ * @see evas_object_image_data_set()
  */
 EAPI void                    *evas_object_image_data_get               (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
 
 /**
  * Replaces the raw image data of the given image object.
  *
+ * @param obj The given image object.
+ * @param data The raw data to replace.
+ *
  * This function lets the application replace an image object's
- * internal pixel buffer with a user-allocated one. For best results,
+ * internal pixel buffer with an user-allocated one. For best results,
  * you should generally first call evas_object_image_size_set() with
  * the width and height for the new buffer.
  *
@@ -5830,24 +5840,22 @@ EAPI void                    *evas_object_image_data_get               (const Ev
  * finished with it, as user-set image data will not be automatically
  * freed when the image object is deleted.
  *
- * See @ref evas_object_image_data_get for more details.
+ * See @ref evas_object_image_data_get() for more details.
  *
- * @param obj The given image object.
- * @param data The raw data.
  */
 EAPI void                     evas_object_image_data_copy_set          (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
 
 /**
  * Mark a sub-region of the given image object to be redrawn.
  *
- * This function schedules a particular rectangular region of an image
- * object to be updated (redrawn) at the next render.
- *
  * @param obj The given image object.
  * @param x X-offset of the region to be updated.
  * @param y Y-offset of the region to be updated.
  * @param w Width of the region to be updated.
  * @param h Height of the region to be updated.
+ *
+ * This function schedules a particular rectangular region of an image
+ * object to be updated (redrawn) at the next rendering cycle.
  */
 EAPI void                     evas_object_image_data_update_add        (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
 
@@ -6160,23 +6168,31 @@ EAPI void                     evas_object_image_scale_hint_set         (Evas_Obj
 EAPI Evas_Image_Scale_Hint    evas_object_image_scale_hint_get         (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
 
 /**
- * Set the content hint of a given image of the canvas.
+ * Set the content hint setting of a given image object of the canvas.
  *
  * @param obj The given canvas pointer.
- * @param hint The content hint value.
+ * @param hint The content hint value, one of the
+ * #Evas_Image_Content_Hint ones.
  *
- * This function sets the content hint value of the given image of the canvas.
+ * This function sets the content hint value of the given image of the
+ * canvas.
  *
+ * @see evas_object_image_content_hint_get()
  */
 EAPI void                     evas_object_image_content_hint_set       (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
 
 /**
- * Get the content hint of a given image of the canvas.
+ * Get the content hint setting of a given image object of the canvas.
  *
  * @param obj The given canvas pointer.
+ * @return hint The content hint value set on it, one of the
+ * #Evas_Image_Content_Hint ones (#EVAS_IMAGE_CONTENT_HINT_NONE means
+ * an error).
  *
- * This function returns the content hint value of the given image of the canvas.
+ * This function returns the content hint value of the given image of
+ * the canvas.
  *
+ * @see evas_object_image_content_hint_set()
  */
 EAPI Evas_Image_Content_Hint  evas_object_image_content_hint_get       (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;