src/lib/elm_image.h

   1    /**
   2     * @defgroup Image Image
   3     *
   4     * @image html img/widget/image/preview-00.png
   5     * @image latex img/widget/image/preview-00.eps
   6
   7     *
   8     * An object that allows one to load an image file to it. It can be used
   9     * anywhere like any other elementary widget.
  10     *
  11     * This widget provides most of the functionality provided from @ref Bg or @ref
  12     * Icon, but with a slightly different API (use the one that fits better your
  13     * needs).
  14     *
  15     * The features not provided by those two other image widgets are:
  16     * @li allowing to get the basic @c Evas_Object with elm_image_object_get();
  17     * @li change the object orientation with elm_image_orient_set();
  18     * @li and turning the image editable with elm_image_editable_set().
  19     *
  20     * Signals that you can add callbacks for are:
  21     *
  22     * @li @c "clicked" - This is called when a user has clicked the image
  23     *
  24     * An example of usage for this API follows:
  25     * @li @ref tutorial_image
  26     */
  27
  28    /**
  29     * @addtogroup Image
  30     * @{
  31     */
  32
  33    /**
  34     * @enum _Elm_Image_Orient
  35     * @typedef Elm_Image_Orient
  36     *
  37     * Possible orientation options for elm_image_orient_set().
  38     *
  39     * @image html elm_image_orient_set.png
  40     * @image latex elm_image_orient_set.eps width=\textwidth
  41     *
  42     * @ingroup Image
  43     */
  44    typedef enum _Elm_Image_Orient
  45      {
  46         ELM_IMAGE_ORIENT_NONE = 0, /**< no orientation change */
  47         ELM_IMAGE_ORIENT_0 = 0, /**< no orientation change */
  48         ELM_IMAGE_ROTATE_90 = 1, /**< rotate 90 degrees clockwise */
  49         ELM_IMAGE_ROTATE_180 = 2, /**< rotate 180 degrees clockwise */
  50         ELM_IMAGE_ROTATE_270 = 3, /**< rotate 90 degrees counter-clockwise (i.e. 270 degrees clockwise) */
  51    // XXX: remove
  52         /*EINA_DEPRECATED*/ELM_IMAGE_ROTATE_90_CW = 1, /**< rotate 90 degrees clockwise */
  53    // XXX: remove
  54         /*EINA_DEPRECATED*/ELM_IMAGE_ROTATE_180_CW = 2, /**< rotate 180 degrees clockwise */
  55    // XXX: remove
  56         /*EINA_DEPRECATED*/ELM_IMAGE_ROTATE_90_CCW = 3, /**< rotate 90 degrees counter-clockwise (i.e. 270 degrees clockwise) */
  57         ELM_IMAGE_FLIP_HORIZONTAL = 4, /**< flip image horizontally */
  58         ELM_IMAGE_FLIP_VERTICAL = 5, /**< flip image vertically */
  59         ELM_IMAGE_FLIP_TRANSPOSE = 6, /**< flip the image along the y = (width - x) line (bottom-left to top-right) */
  60         ELM_IMAGE_FLIP_TRANSVERSE = 7 /**< flip the image along the y = x line (top-left to bottom-right) */
  61      } Elm_Image_Orient;
  62
  63    /**
  64     * Add a new image to the parent.
  65     *
  66     * @param parent The parent object
  67     * @return The new object or NULL if it cannot be created
  68     *
  69     * @see elm_image_file_set()
  70     *
  71     * @ingroup Image
  72     */
  73    EAPI Evas_Object     *elm_image_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  74
  75    /**
  76     * Set the file that will be used as image.
  77     *
  78     * @param obj The image object
  79     * @param file The path to file that will be used as image
  80     * @param group The group that the image belongs in edje file (if it's an
  81     * edje image)
  82     *
  83     * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
  84     *
  85     * @see elm_image_file_get()
  86     *
  87     * @ingroup Image
  88     */
  89    EAPI Eina_Bool        elm_image_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
  90
  91    /**
  92     * Get the file that will be used as image.
  93     *
  94     * @param obj The image object
  95     * @param file The path to file
  96     * @param group The group that the image belongs in edje file
  97     *
  98     * @see elm_image_file_set()
  99     *
 100     * @ingroup Image
 101     */
 102    EAPI void             elm_image_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
 103
 104    /**
 105     * Set the smooth effect for an image.
 106     *
 107     * @param obj The image object
 108     * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
 109     * otherwise. Default is @c EINA_TRUE.
 110     *
 111     * Set the scaling algorithm to be used when scaling the image. Smooth
 112     * scaling provides a better resulting image, but is slower.
 113     *
 114     * The smooth scaling should be disabled when making animations that change
 115     * the image size, since it will be faster. Animations that don't require
 116     * resizing of the image can keep the smooth scaling enabled (even if the
 117     * image is already scaled, since the scaled image will be cached).
 118     *
 119     * @see elm_image_smooth_get()
 120     *
 121     * @ingroup Image
 122     */
 123    EAPI void             elm_image_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
 124
 125    /**
 126     * Get the smooth effect for an image.
 127     *
 128     * @param obj The image object
 129     * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
 130     *
 131     * @see elm_image_smooth_get()
 132     *
 133     * @ingroup Image
 134     */
 135    EAPI Eina_Bool        elm_image_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 136
 137    /**
 138     * Gets the current size of the image.
 139     *
 140     * @param obj The image object.
 141     * @param w Pointer to store width, or NULL.
 142     * @param h Pointer to store height, or NULL.
 143     *
 144     * This is the real size of the image, not the size of the object.
 145     *
 146     * On error, neither w and h will be fileld with 0.
 147     *
 148     * @ingroup Image
 149     */
 150    EAPI void             elm_image_object_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
 151
 152    /**
 153     * Disable scaling of this object.
 154     *
 155     * @param obj The image object.
 156     * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
 157     * otherwise. Default is @c EINA_FALSE.
 158     *
 159     * This function disables scaling of the elm_image widget through the
 160     * function elm_object_scale_set(). However, this does not affect the widget
 161     * size/resize in any way. For that effect, take a look at
 162     * elm_image_scale_set().
 163     *
 164     * @see elm_image_no_scale_get()
 165     * @see elm_image_scale_set()
 166     * @see elm_object_scale_set()
 167     *
 168     * @ingroup Image
 169     */
 170    EAPI void             elm_image_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
 171
 172    /**
 173     * Get whether scaling is disabled on the object.
 174     *
 175     * @param obj The image object
 176     * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
 177     *
 178     * @see elm_image_no_scale_set()
 179     *
 180     * @ingroup Image
 181     */
 182    EAPI Eina_Bool        elm_image_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 183
 184    /**
 185     * Set if the object is (up/down) resizable.
 186     *
 187     * @param obj The image object
 188     * @param scale_up A bool to set if the object is resizable up. Default is
 189     * @c EINA_TRUE.
 190     * @param scale_down A bool to set if the object is resizable down. Default
 191     * is @c EINA_TRUE.
 192     *
 193     * This function limits the image resize ability. If @p scale_up is set to
 194     * @c EINA_FALSE, the object can't have its height or width resized to a value
 195     * higher than the original image size. Same is valid for @p scale_down.
 196     *
 197     * @see elm_image_scale_get()
 198     *
 199     * @ingroup Image
 200     */
 201    EAPI void             elm_image_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
 202
 203    /**
 204     * Get if the object is (up/down) resizable.
 205     *
 206     * @param obj The image object
 207     * @param scale_up A bool to set if the object is resizable up
 208     * @param scale_down A bool to set if the object is resizable down
 209     *
 210     * @see elm_image_scale_set()
 211     *
 212     * @ingroup Image
 213     */
 214    EAPI void             elm_image_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
 215
 216    /**
 217     * Set if the image fills the entire object area, when keeping the aspect ratio.
 218     *
 219     * @param obj The image object
 220     * @param fill_outside @c EINA_TRUE if the object is filled outside,
 221     * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 222     *
 223     * When the image should keep its aspect ratio even if resized to another
 224     * aspect ratio, there are two possibilities to resize it: keep the entire
 225     * image inside the limits of height and width of the object (@p fill_outside
 226     * is @c EINA_FALSE) or let the extra width or height go outside of the object,
 227     * and the image will fill the entire object (@p fill_outside is @c EINA_TRUE).
 228     *
 229     * @note This option will have no effect if
 230     * elm_image_aspect_ratio_retained_set() is set to @c EINA_FALSE.
 231     *
 232     * @see elm_image_fill_outside_get()
 233     * @see elm_image_aspect_ratio_retained_set()
 234     *
 235     * @ingroup Image
 236     */
 237    EAPI void             elm_image_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
 238
 239    /**
 240     * Get if the object is filled outside
 241     *
 242     * @param obj The image object
 243     * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
 244     *
 245     * @see elm_image_fill_outside_set()
 246     *
 247     * @ingroup Image
 248     */
 249    EAPI Eina_Bool        elm_image_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 250
 251    /**
 252     * Set the prescale size for the image
 253     *
 254     * @param obj The image object
 255     * @param size The prescale size. This value is used for both width and
 256     * height.
 257     *
 258     * This function sets a new size for pixmap representation of the given
 259     * image. It allows the image to be loaded already in the specified size,
 260     * reducing the memory usage and load time when loading a big image with load
 261     * size set to a smaller size.
 262     *
 263     * It's equivalent to the elm_bg_load_size_set() function for bg.
 264     *
 265     * @note this is just a hint, the real size of the pixmap may differ
 266     * depending on the type of image being loaded, being bigger than requested.
 267     *
 268     * @see elm_image_prescale_get()
 269     * @see elm_bg_load_size_set()
 270     *
 271     * @ingroup Image
 272     */
 273    EAPI void             elm_image_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
 274
 275    /**
 276     * Get the prescale size for the image
 277     *
 278     * @param obj The image object
 279     * @return The prescale size
 280     *
 281     * @see elm_image_prescale_set()
 282     *
 283     * @ingroup Image
 284     */
 285    EAPI int              elm_image_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 286
 287    /**
 288     * Set the image orientation.
 289     *
 290     * @param obj The image object
 291     * @param orient The image orientation @ref Elm_Image_Orient
 292     *  Default is #ELM_IMAGE_ORIENT_NONE.
 293     *
 294     * This function allows to rotate or flip the given image.
 295     *
 296     * @see elm_image_orient_get()
 297     * @see @ref Elm_Image_Orient
 298     *
 299     * @ingroup Image
 300     */
 301    EAPI void             elm_image_orient_set(Evas_Object *obj, Elm_Image_Orient orient) EINA_ARG_NONNULL(1);
 302
 303    /**
 304     * Get the image orientation.
 305     *
 306     * @param obj The image object
 307     * @return The image orientation @ref Elm_Image_Orient
 308     *
 309     * @see elm_image_orient_set()
 310     * @see @ref Elm_Image_Orient
 311     *
 312     * @ingroup Image
 313     */
 314    EAPI Elm_Image_Orient elm_image_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 315
 316    /**
 317     * Make the image 'editable'.
 318     *
 319     * @param obj Image object.
 320     * @param set Turn on or off editability. Default is @c EINA_FALSE.
 321     *
 322     * This means the image is a valid drag target for drag and drop, and can be
 323     * cut or pasted too.
 324     *
 325     * @ingroup Image
 326     */
 327    EAPI void             elm_image_editable_set(Evas_Object *obj, Eina_Bool set) EINA_ARG_NONNULL(1);
 328
 329    /**
 330     * Check if the image 'editable'.
 331     *
 332     * @param obj Image object.
 333     * @return Editability.
 334     *
 335     * A return value of EINA_TRUE means the image is a valid drag target
 336     * for drag and drop, and can be cut or pasted too.
 337     *
 338     * @ingroup Image
 339     */
 340    EAPI Eina_Bool        elm_image_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 341
 342    /**
 343     * Get the basic Evas_Image object from this object (widget).
 344     *
 345     * @param obj The image object to get the inlined image from
 346     * @return The inlined image object, or NULL if none exists
 347     *
 348     * This function allows one to get the underlying @c Evas_Object of type
 349     * Image from this elementary widget. It can be useful to do things like get
 350     * the pixel data, save the image to a file, etc.
 351     *
 352     * @note Be careful to not manipulate it, as it is under control of
 353     * elementary.
 354     *
 355     * @ingroup Image
 356     */
 357    EAPI Evas_Object     *elm_image_object_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 358
 359    /**
 360     * Set whether the original aspect ratio of the image should be kept on resize.
 361     *
 362     * @param obj The image object.
 363     * @param retained @c EINA_TRUE if the image should retain the aspect,
 364     * @c EINA_FALSE otherwise.
 365     *
 366     * The original aspect ratio (width / height) of the image is usually
 367     * distorted to match the object's size. Enabling this option will retain
 368     * this original aspect, and the way that the image is fit into the object's
 369     * area depends on the option set by elm_image_fill_outside_set().
 370     *
 371     * @see elm_image_aspect_ratio_retained_get()
 372     * @see elm_image_fill_outside_set()
 373     *
 374     * @ingroup Image
 375     */
 376    EAPI void             elm_image_aspect_ratio_retained_set(Evas_Object *obj, Eina_Bool retained) EINA_ARG_NONNULL(1);
 377
 378    /**
 379     * Get if the object retains the original aspect ratio.
 380     *
 381     * @param obj The image object.
 382     * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
 383     * otherwise.
 384     *
 385     * @ingroup Image
 386     */
 387    EAPI Eina_Bool        elm_image_aspect_ratio_retained_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 388
 389    /**
 390     * @}
 391     */
 392