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