src/lib/elm_image.h

   1 /**
   2  * @defgroup Image Image
   3  * @ingroup Elementary
   4  *
   5  * @image html image_inheritance_tree.png
   6  * @image latex image_inheritance_tree.eps
   7  *
   8  * @image html img/widget/image/preview-00.png
   9  * @image latex img/widget/image/preview-00.eps
  10  *
  11  * An Elementary image object is a direct realization of
  12  * @ref elm-image-class, and it allows one to load and display an @b image
  13  * file on it, be it from a disk file or from a memory
  14  * region. Exceptionally, one may also load an Edje group as the
  15  * contents of the image. In this case, though, most of the functions
  16  * of the image API will act as a no-op.
  17  *
  18  * One can tune various properties of the image, like:
  19  * - pre-scaling,
  20  * - smooth scaling,
  21  * - orientation,
  22  * - aspect ratio during resizes, etc.
  23  *
  24  * An image object may also be made valid source and destination for
  25  * drag and drop actions, through the elm_image_editable_set() call.
  26  *
  27  * Signals that you can add callbacks for are:
  28  *
  29  * @li @c "drop" - This is called when a user has dropped an image
  30  *                 typed object onto the object in question -- the
  31  *                 event info argument is the path to that image file
  32  * @li @c "clicked" - This is called when a user has clicked the image
  33  *
  34  * An example of usage for this API follows:
  35  * @li @ref tutorial_image
  36  */
  37
  38 /**
  39  * @addtogroup Image
  40  * @{
  41  */
  42
  43 /**
  44  * Possible orientation options for elm_image_orient_set().
  45  *
  46  * @image html elm_image_orient_set.png
  47  * @image latex elm_image_orient_set.eps width=\textwidth
  48  *
  49  * @ingroup Image
  50  */
  51 typedef enum
  52 {
  53    ELM_IMAGE_ORIENT_NONE = 0, /**< no orientation change */
  54    ELM_IMAGE_ORIENT_0 = 0, /**< no orientation change */
  55    ELM_IMAGE_ROTATE_90 = 1, /**< rotate 90 degrees clockwise */
  56    ELM_IMAGE_ROTATE_180 = 2, /**< rotate 180 degrees clockwise */
  57    ELM_IMAGE_ROTATE_270 = 3, /**< rotate 90 degrees counter-clockwise (i.e. 270 degrees clockwise) */
  58    ELM_IMAGE_FLIP_HORIZONTAL = 4, /**< flip image horizontally */
  59    ELM_IMAGE_FLIP_VERTICAL = 5, /**< flip image vertically */
  60    ELM_IMAGE_FLIP_TRANSPOSE = 6, /**< flip the image along the y = (width - x) line (bottom-left to top-right) */
  61    ELM_IMAGE_FLIP_TRANSVERSE = 7 /**< flip the image along the y = x line (top-left to bottom-right) */
  62 } Elm_Image_Orient;
  63
  64 /**
  65  * Add a new image to the parent.
  66  *
  67  * @param parent The parent object
  68  * @return The new object or NULL if it cannot be created
  69  *
  70  * @see elm_image_file_set()
  71  *
  72  * @ingroup Image
  73  */
  74 EAPI Evas_Object     *elm_image_add(Evas_Object *parent);
  75
  76 /**
  77  * Set a location in memory to be used as an image object's source
  78  * bitmap.
  79  *
  80  * @param obj The image object
  81  * @param img The binary data that will be used as image source
  82  * @param size The size of binary data blob @p img
  83  * @param format (Optional) expected format of @p img bytes
  84  * @param key Optional indexing key of @p img to be passed to the
  85  *            image loader (eg. if @p img is a memory-mapped EET file)
  86  *
  87  * This function is handy when the contents of an image file are
  88  * mapped in memory, for example.
  89  *
  90  * The @p format string should be something like @c "png", @c "jpg",
  91  * @c "tga", @c "tiff", @c "bmp" etc, when provided (@c NULL, on the
  92  * contrary). This improves the loader performance as it tries the
  93  * "correct" loader first, before trying a range of other possible
  94  * loaders until one succeeds.
  95  *
  96  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
  97  *
  98  * @since 1.7
  99  *
 100  * @ingroup Image
 101  */
 102 EAPI Eina_Bool             elm_image_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key);
 103
 104 /**
 105  * Set the file that will be used as the image's source.
 106  *
 107  * @param obj The image object
 108  * @param file The path to file that will be used as image source
 109  * @param group The group that the image belongs to, in case it's an
 110  *              EET (including Edje case) file
 111  *
 112  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 113  *
 114  * @see elm_image_file_get()
 115  *
 116  * @note This function will trigger the Edje file case based on the
 117  * extension of the @a file string (expects @c ".edj", for this
 118  * case). If one wants to force this type of file independently of the
 119  * extension, elm_image_file_edje_set() must be used, instead.
 120  *
 121  * @ingroup Image
 122  */
 123 EAPI Eina_Bool        elm_image_file_set(Evas_Object *obj, const char *file, const char *group);
 124
 125 /**
 126  * Get the file that will be used as image.
 127  *
 128  * @param obj The image object
 129  * @param file The path to file
 130  * @param group The group that the image belongs in edje file
 131  *
 132  * @see elm_image_file_set()
 133  *
 134  * @ingroup Image
 135  */
 136 EAPI void             elm_image_file_get(const Evas_Object *obj, const char **file, const char **group);
 137
 138 /**
 139  * Set the smooth effect for an image.
 140  *
 141  * @param obj The image object
 142  * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
 143  * otherwise. Default is @c EINA_TRUE.
 144  *
 145  * Set the scaling algorithm to be used when scaling the image. Smooth
 146  * scaling provides a better resulting image, but is slower.
 147  *
 148  * The smooth scaling should be disabled when making animations that change
 149  * the image size, since it will be faster. Animations that don't require
 150  * resizing of the image can keep the smooth scaling enabled (even if the
 151  * image is already scaled, since the scaled image will be cached).
 152  *
 153  * @see elm_image_smooth_get()
 154  *
 155  * @ingroup Image
 156  */
 157 EAPI void             elm_image_smooth_set(Evas_Object *obj, Eina_Bool smooth);
 158
 159 /**
 160  * Get the smooth effect for an image.
 161  *
 162  * @param obj The image object
 163  * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
 164  *
 165  * @see elm_image_smooth_get()
 166  *
 167  * @ingroup Image
 168  */
 169 EAPI Eina_Bool        elm_image_smooth_get(const Evas_Object *obj);
 170
 171 /**
 172  * Gets the current size of the image.
 173  *
 174  * @param obj The image object.
 175  * @param w Pointer to store width, or NULL.
 176  * @param h Pointer to store height, or NULL.
 177  *
 178  * This is the real size of the image, not the size of the object.
 179  *
 180  * @ingroup Image
 181  */
 182 EAPI void             elm_image_object_size_get(const Evas_Object *obj, int *w, int *h);
 183
 184 /**
 185  * Disable scaling of this object.
 186  *
 187  * @param obj The image object.
 188  * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
 189  * otherwise. Default is @c EINA_FALSE.
 190  *
 191  * This function disables scaling of the elm_image widget through the
 192  * function elm_object_scale_set(). However, this does not affect the widget
 193  * size/resize in any way. For that effect, take a look at
 194  * elm_image_resizable_set().
 195  *
 196  * @see elm_image_no_scale_get()
 197  * @see elm_image_resizable_set()
 198  * @see elm_object_scale_set()
 199  *
 200  * @ingroup Image
 201  */
 202 EAPI void             elm_image_no_scale_set(Evas_Object *obj, Eina_Bool no_scale);
 203
 204 /**
 205  * Get whether scaling is disabled on the object.
 206  *
 207  * @param obj The image object
 208  * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
 209  *
 210  * @see elm_image_no_scale_set()
 211  *
 212  * @ingroup Image
 213  */
 214 EAPI Eina_Bool        elm_image_no_scale_get(const Evas_Object *obj);
 215
 216 /**
 217  * Set if the object is (up/down) resizable.
 218  *
 219  * @param obj The image object
 220  * @param size_up A bool to set if the object is resizable up. Default is
 221  * @c EINA_TRUE.
 222  * @param size_down A bool to set if the object is resizable down. Default
 223  * is @c EINA_TRUE.
 224  *
 225  * This function limits the image resize ability. If @p size_up is set to
 226  * @c EINA_FALSE, the object can't have its height or width resized to a value
 227  * higher than the original image size. Same is valid for @p size_down.
 228  *
 229  * @see elm_image_resizable_get()
 230  *
 231  * @ingroup Image
 232  */
 233 EAPI void             elm_image_resizable_set(Evas_Object *obj, Eina_Bool size_up, Eina_Bool size_down);
 234
 235 /**
 236  * Get if the object is (up/down) resizable.
 237  *
 238  * @param obj The image object
 239  * @param size_up A bool to set if the object is resizable up
 240  * @param size_down A bool to set if the object is resizable down
 241  *
 242  * @see elm_image_resizable_set()
 243  *
 244  * @ingroup Image
 245  */
 246 EAPI void             elm_image_resizable_get(const Evas_Object *obj, Eina_Bool *size_up, Eina_Bool *size_down);
 247
 248 /**
 249  * Set if the image fills the entire object area, when keeping the aspect ratio.
 250  *
 251  * @param obj The image object
 252  * @param fill_outside @c EINA_TRUE if the object is filled outside,
 253  * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 254  *
 255  * When the image should keep its aspect ratio even if resized to another
 256  * aspect ratio, there are two possibilities to resize it: keep the entire
 257  * image inside the limits of height and width of the object (@p fill_outside
 258  * is @c EINA_FALSE) or let the extra width or height go outside of the object,
 259  * and the image will fill the entire object (@p fill_outside is @c EINA_TRUE).
 260  *
 261  * @note This option will have no effect if
 262  * elm_image_aspect_fixed_set() is set to @c EINA_FALSE.
 263  *
 264  * @see elm_image_fill_outside_get()
 265  * @see elm_image_aspect_fixed_set()
 266  *
 267  * @ingroup Image
 268  */
 269 EAPI void             elm_image_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside);
 270
 271 /**
 272  * Get if the object is filled outside
 273  *
 274  * @param obj The image object
 275  * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
 276  *
 277  * @see elm_image_fill_outside_set()
 278  *
 279  * @ingroup Image
 280  */
 281 EAPI Eina_Bool        elm_image_fill_outside_get(const Evas_Object *obj);
 282
 283 /**
 284  * Enable or disable preloading of the image
 285  *
 286  * @param obj The image object
 287  * @param disabled If EINA_TRUE, preloading will be disabled
 288  * @ingroup Image
 289  */
 290 EAPI void                  elm_image_preload_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 291
 292 /**
 293  * Set the prescale size for the image
 294  *
 295  * @param obj The image object
 296  * @param size The prescale size. This value is used for both width and
 297  * height.
 298  *
 299  * This function sets a new size for pixmap representation of the given
 300  * image. It allows the image to be loaded already in the specified size,
 301  * reducing the memory usage and load time when loading a big image with load
 302  * size set to a smaller size.
 303  *
 304  * It's equivalent to the elm_bg_load_size_set() function for bg.
 305  *
 306  * @note this is just a hint, the real size of the pixmap may differ
 307  * depending on the type of image being loaded, being bigger than requested.
 308  *
 309  * @see elm_image_prescale_get()
 310  * @see elm_bg_load_size_set()
 311  *
 312  * @ingroup Image
 313  */
 314 EAPI void             elm_image_prescale_set(Evas_Object *obj, int size);
 315
 316 /**
 317  * Get the prescale size for the image
 318  *
 319  * @param obj The image object
 320  * @return The prescale size
 321  *
 322  * @see elm_image_prescale_set()
 323  *
 324  * @ingroup Image
 325  */
 326 EAPI int              elm_image_prescale_get(const Evas_Object *obj);
 327
 328 /**
 329  * Set the image orientation.
 330  *
 331  * @param obj The image object
 332  * @param orient The image orientation @ref Elm_Image_Orient
 333  *  Default is #ELM_IMAGE_ORIENT_NONE.
 334  *
 335  * This function allows to rotate or flip the given image.
 336  *
 337  * @see elm_image_orient_get()
 338  * @see @ref Elm_Image_Orient
 339  *
 340  * @ingroup Image
 341  */
 342 EAPI void             elm_image_orient_set(Evas_Object *obj, Elm_Image_Orient orient);
 343
 344 /**
 345  * Get the image orientation.
 346  *
 347  * @param obj The image object
 348  * @return The image orientation @ref Elm_Image_Orient
 349  *
 350  * @see elm_image_orient_set()
 351  * @see @ref Elm_Image_Orient
 352  *
 353  * @ingroup Image
 354  */
 355 EAPI Elm_Image_Orient elm_image_orient_get(const Evas_Object *obj);
 356
 357 /**
 358  * Make the image 'editable'.
 359  *
 360  * @param obj Image object.
 361  * @param set Turn on or off editability. Default is @c EINA_FALSE.
 362  *
 363  * This means the image is a valid drag target for drag and drop, and can be
 364  * cut or pasted too.
 365  *
 366  * @ingroup Image
 367  */
 368 EAPI void             elm_image_editable_set(Evas_Object *obj, Eina_Bool set);
 369
 370 /**
 371  * Check if the image is 'editable'.
 372  *
 373  * @param obj Image object.
 374  * @return Editability.
 375  *
 376  * A return value of EINA_TRUE means the image is a valid drag target
 377  * for drag and drop, and can be cut or pasted too.
 378  *
 379  * @ingroup Image
 380  */
 381 EAPI Eina_Bool        elm_image_editable_get(const Evas_Object *obj);
 382
 383 /**
 384  * Get the inlined image object of the image widget.
 385  *
 386  * @param obj The image object to get the inlined image from
 387  * @return The inlined image object, or NULL if none exists
 388  *
 389  * This function allows one to get the underlying @c Evas_Object of type
 390  * Image from this elementary widget. It can be useful to do things like get
 391  * the pixel data, save the image to a file, etc.
 392  *
 393  * @note Be careful to not manipulate it, as it is under control of
 394  * elementary.
 395  *
 396  * @ingroup Image
 397  */
 398 EAPI Evas_Object     *elm_image_object_get(const Evas_Object *obj);
 399
 400 /**
 401  * Set whether the original aspect ratio of the image should be kept on resize.
 402  *
 403  * @param obj The image object.
 404  * @param fixed @c EINA_TRUE if the image should retain the aspect,
 405  * @c EINA_FALSE otherwise.
 406  *
 407  * The original aspect ratio (width / height) of the image is usually
 408  * distorted to match the object's size. Enabling this option will retain
 409  * this original aspect, and the way that the image is fit into the object's
 410  * area depends on the option set by elm_image_fill_outside_set().
 411  *
 412  * @see elm_image_aspect_fixed_get()
 413  * @see elm_image_fill_outside_set()
 414  *
 415  * @ingroup Image
 416  */
 417 EAPI void             elm_image_aspect_fixed_set(Evas_Object *obj, Eina_Bool fixed);
 418
 419 /**
 420  * Get if the object retains the original aspect ratio.
 421  *
 422  * @param obj The image object.
 423  * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
 424  * otherwise.
 425  *
 426  * @ingroup Image
 427  */
 428 EAPI Eina_Bool        elm_image_aspect_fixed_get(const Evas_Object *obj);
 429
 430 /**
 431  * Get whether an image object supports animation or not.
 432  *
 433  * @param obj The image object
 434  * @return @c EINA_TRUE if the image supports animation,
 435  *         @c EINA_FALSE otherwise.
 436  *
 437  * This function returns if this Elementary image object's internal
 438  * image can be animated. Currently Evas only supports GIF
 439  * animation. If the return value is @b EINA_FALSE, other
 440  * @c elm_image_animated_xxx API calls won't work.
 441  *
 442  * @see elm_image_animated_set()
 443  *
 444  * @ingroup Image
 445  * @since 1.7
 446  */
 447 EAPI Eina_Bool        elm_image_animated_available_get(const Evas_Object *obj);
 448
 449 /**
 450  * Set whether an image object (which supports animation) is to
 451  * animate itself or not.
 452  *
 453  * @param obj The image object
 454
 455  * @param animated @c EINA_TRUE if the object is to animate itself,
 456  *                 @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 457  *
 458  * An image object, even if it supports animation, will be displayed
 459  * by default without animation. Call this function with @a animated
 460  * set to @c EINA_TRUE to enable its animation. To start or stop the
 461  * animation, actually, use elm_image_animated_play_set().
 462  *
 463  * @see elm_image_animated_get()
 464  * @see elm_image_animated_available_get()
 465  * @see elm_image_animated_play_set()
 466  *
 467  * @ingroup Image
 468  * @since 1.7
 469  */
 470 EAPI void             elm_image_animated_set(Evas_Object *obj, Eina_Bool animated);
 471
 472 /**
 473  * Get whether an image object has animation enabled or not.
 474  *
 475  * @param obj The image object
 476  *
 477  * @return @c EINA_TRUE if the image has animation enabled,
 478  *         @c EINA_FALSE otherwise.
 479  *
 480  * @see elm_image_animated_set()
 481  *
 482  * @ingroup Image
 483  * @since 1.7
 484  */
 485 EAPI Eina_Bool        elm_image_animated_get(const Evas_Object *obj);
 486
 487 /**
 488  * Start or stop an image object's animation.
 489  *
 490  * @param obj The image object
 491  * @param play @c EINA_TRUE to start the animation, @c EINA_FALSE
 492  *             otherwise. Default is @c EINA_FALSE.
 493  *
 494  * To actually start playing any image object's animation, if it
 495  * supports it, one must do something like:
 496  *
 497  * @code
 498  * if (elm_image_animated_available_get(img))
 499  *   {
 500  *      elm_image_animated_set(img, EINA_TRUE);
 501  *      elm_image_animated_play_set(img, EINA_TRUE);
 502  *   }
 503  * @endcode
 504  *
 505  * elm_image_animated_set() will enable animation on the image, <b>but
 506  * not start it yet</b>. This is the function one uses to start and
 507  * stop animations on image objects.
 508  *
 509  * @see elm_image_animated_available_get()
 510  * @see elm_image_animated_set()
 511  * @see elm_image_animated_play_get()
 512  *
 513  * @ingroup Image
 514  * @since 1.7
 515  */
 516 EAPI void             elm_image_animated_play_set(Evas_Object *obj, Eina_Bool play);
 517
 518 /**
 519  * Get whether an image object is under animation or not.
 520  *
 521  * @param obj The image object
 522  * @return @c EINA_TRUE, if the image is being animated, @c EINA_FALSE
 523  *            otherwise.
 524  *
 525  * @see elm_image_animated_play_get()
 526  *
 527  * @ingroup Image
 528  * @since 1.7
 529  */
 530 EAPI Eina_Bool        elm_image_animated_play_get(const Evas_Object *obj);
 531
 532 /**
 533  * @}
 534  */