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  * Possible orientation options for elm_image_orient_set().
  35  *
  36  * @image html elm_image_orient_set.png
  37  * @image latex elm_image_orient_set.eps width=\textwidth
  38  *
  39  * @ingroup Image
  40  */
  41 typedef enum
  42 {
  43    ELM_IMAGE_ORIENT_NONE = 0, /**< no orientation change */
  44    ELM_IMAGE_ORIENT_0 = 0, /**< no orientation change */
  45    ELM_IMAGE_ROTATE_90 = 1, /**< rotate 90 degrees clockwise */
  46    ELM_IMAGE_ROTATE_180 = 2, /**< rotate 180 degrees clockwise */
  47    ELM_IMAGE_ROTATE_270 = 3, /**< rotate 90 degrees counter-clockwise (i.e. 270 degrees clockwise) */
  48    ELM_IMAGE_FLIP_HORIZONTAL = 4, /**< flip image horizontally */
  49    ELM_IMAGE_FLIP_VERTICAL = 5, /**< flip image vertically */
  50    ELM_IMAGE_FLIP_TRANSPOSE = 6, /**< flip the image along the y = (width - x) line (bottom-left to top-right) */
  51    ELM_IMAGE_FLIP_TRANSVERSE = 7 /**< flip the image along the y = x line (top-left to bottom-right) */
  52 } Elm_Image_Orient;
  53
  54 /**
  55  * Add a new image to the parent.
  56  *
  57  * @param parent The parent object
  58  * @return The new object or NULL if it cannot be created
  59  *
  60  * @see elm_image_file_set()
  61  *
  62  * @ingroup Image
  63  */
  64 EAPI Evas_Object     *elm_image_add(Evas_Object *parent);
  65
  66 /**
  67  * Set the file that will be used as image.
  68  *
  69  * @param obj The image object
  70  * @param file The path to file that will be used as image
  71  * @param group The group that the image belongs in edje file (if it's an
  72  * edje image)
  73  *
  74  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
  75  *
  76  * @see elm_image_file_get()
  77  *
  78  * @ingroup Image
  79  */
  80 EAPI Eina_Bool        elm_image_file_set(Evas_Object *obj, const char *file, const char *group);
  81
  82 /**
  83  * Get the file that will be used as image.
  84  *
  85  * @param obj The image object
  86  * @param file The path to file
  87  * @param group The group that the image belongs in edje file
  88  *
  89  * @see elm_image_file_set()
  90  *
  91  * @ingroup Image
  92  */
  93 EAPI void             elm_image_file_get(const Evas_Object *obj, const char **file, const char **group);
  94
  95 /**
  96  * Set the smooth effect for an image.
  97  *
  98  * @param obj The image object
  99  * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
 100  * otherwise. Default is @c EINA_TRUE.
 101  *
 102  * Set the scaling algorithm to be used when scaling the image. Smooth
 103  * scaling provides a better resulting image, but is slower.
 104  *
 105  * The smooth scaling should be disabled when making animations that change
 106  * the image size, since it will be faster. Animations that don't require
 107  * resizing of the image can keep the smooth scaling enabled (even if the
 108  * image is already scaled, since the scaled image will be cached).
 109  *
 110  * @see elm_image_smooth_get()
 111  *
 112  * @ingroup Image
 113  */
 114 EAPI void             elm_image_smooth_set(Evas_Object *obj, Eina_Bool smooth);
 115
 116 /**
 117  * Get the smooth effect for an image.
 118  *
 119  * @param obj The image object
 120  * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
 121  *
 122  * @see elm_image_smooth_get()
 123  *
 124  * @ingroup Image
 125  */
 126 EAPI Eina_Bool        elm_image_smooth_get(const Evas_Object *obj);
 127
 128 /**
 129  * Gets the current size of the image.
 130  *
 131  * @param obj The image object.
 132  * @param w Pointer to store width, or NULL.
 133  * @param h Pointer to store height, or NULL.
 134  *
 135  * This is the real size of the image, not the size of the object.
 136  *
 137 <<<<<<< HEAD
 138  * On error, neither w and h will be fileld with 0.
 139  *
 140 =======
 141 >>>>>>> remotes/origin/upstream
 142  * @ingroup Image
 143  */
 144 EAPI void             elm_image_object_size_get(const Evas_Object *obj, int *w, int *h);
 145
 146 /**
 147  * Disable scaling of this object.
 148  *
 149  * @param obj The image object.
 150  * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
 151  * otherwise. Default is @c EINA_FALSE.
 152  *
 153  * This function disables scaling of the elm_image widget through the
 154  * function elm_object_scale_set(). However, this does not affect the widget
 155  * size/resize in any way. For that effect, take a look at
 156 <<<<<<< HEAD
 157  * elm_image_scale_set().
 158  *
 159  * @see elm_image_no_scale_get()
 160  * @see elm_image_scale_set()
 161 =======
 162  * elm_image_resizable_set().
 163  *
 164  * @see elm_image_no_scale_get()
 165  * @see elm_image_resizable_set()
 166 >>>>>>> remotes/origin/upstream
 167  * @see elm_object_scale_set()
 168  *
 169  * @ingroup Image
 170  */
 171 EAPI void             elm_image_no_scale_set(Evas_Object *obj, Eina_Bool no_scale);
 172
 173 /**
 174  * Get whether scaling is disabled on the object.
 175  *
 176  * @param obj The image object
 177  * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
 178  *
 179  * @see elm_image_no_scale_set()
 180  *
 181  * @ingroup Image
 182  */
 183 EAPI Eina_Bool        elm_image_no_scale_get(const Evas_Object *obj);
 184
 185 /**
 186  * Set if the object is (up/down) resizable.
 187  *
 188  * @param obj The image object
 189 <<<<<<< HEAD
 190  * @param scale_up A bool to set if the object is resizable up. Default is
 191  * @c EINA_TRUE.
 192  * @param scale_down A bool to set if the object is resizable down. Default
 193  * is @c EINA_TRUE.
 194  *
 195  * This function limits the image resize ability. If @p scale_up is set to
 196  * @c EINA_FALSE, the object can't have its height or width resized to a value
 197  * higher than the original image size. Same is valid for @p scale_down.
 198  *
 199  * @see elm_image_scale_get()
 200  *
 201  * @ingroup Image
 202  */
 203 EAPI void             elm_image_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down);
 204 =======
 205  * @param size_up A bool to set if the object is resizable up. Default is
 206  * @c EINA_TRUE.
 207  * @param size_down A bool to set if the object is resizable down. Default
 208  * is @c EINA_TRUE.
 209  *
 210  * This function limits the image resize ability. If @p size_up is set to
 211  * @c EINA_FALSE, the object can't have its height or width resized to a value
 212  * higher than the original image size. Same is valid for @p size_down.
 213  *
 214  * @see elm_image_resizable_get()
 215  *
 216  * @ingroup Image
 217  */
 218 EAPI void             elm_image_resizable_set(Evas_Object *obj, Eina_Bool size_up, Eina_Bool size_down);
 219 >>>>>>> remotes/origin/upstream
 220
 221 /**
 222  * Get if the object is (up/down) resizable.
 223  *
 224  * @param obj The image object
 225 <<<<<<< HEAD
 226  * @param scale_up A bool to set if the object is resizable up
 227  * @param scale_down A bool to set if the object is resizable down
 228  *
 229  * @see elm_image_scale_set()
 230  *
 231  * @ingroup Image
 232  */
 233 EAPI void             elm_image_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down);
 234 =======
 235  * @param size_up A bool to set if the object is resizable up
 236  * @param size_down A bool to set if the object is resizable down
 237  *
 238  * @see elm_image_resizable_set()
 239  *
 240  * @ingroup Image
 241  */
 242 EAPI void             elm_image_resizable_get(const Evas_Object *obj, Eina_Bool *size_up, Eina_Bool *size_down);
 243 >>>>>>> remotes/origin/upstream
 244
 245 /**
 246  * Set if the image fills the entire object area, when keeping the aspect ratio.
 247  *
 248  * @param obj The image object
 249  * @param fill_outside @c EINA_TRUE if the object is filled outside,
 250  * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 251  *
 252  * When the image should keep its aspect ratio even if resized to another
 253  * aspect ratio, there are two possibilities to resize it: keep the entire
 254  * image inside the limits of height and width of the object (@p fill_outside
 255  * is @c EINA_FALSE) or let the extra width or height go outside of the object,
 256  * and the image will fill the entire object (@p fill_outside is @c EINA_TRUE).
 257  *
 258  * @note This option will have no effect if
 259  * elm_image_aspect_fixed_set() is set to @c EINA_FALSE.
 260  *
 261  * @see elm_image_fill_outside_get()
 262  * @see elm_image_aspect_fixed_set()
 263  *
 264  * @ingroup Image
 265  */
 266 EAPI void             elm_image_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside);
 267
 268 /**
 269  * Get if the object is filled outside
 270  *
 271  * @param obj The image object
 272  * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
 273  *
 274  * @see elm_image_fill_outside_set()
 275  *
 276  * @ingroup Image
 277  */
 278 EAPI Eina_Bool        elm_image_fill_outside_get(const Evas_Object *obj);
 279
 280 /**
 281 <<<<<<< HEAD
 282 =======
 283  * Enable or disable preloading of the image
 284  *
 285  * @param obj The image object
 286  * @param disabled If EINA_TRUE, preloading will be disabled
 287  * @ingroup Icon
 288  */
 289 EAPI void                  elm_image_preload_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 290
 291 /**
 292 >>>>>>> remotes/origin/upstream
 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 <<<<<<< HEAD
 372  * Check if the image 'editable'.
 373 =======
 374  * Check if the image is 'editable'.
 375 >>>>>>> remotes/origin/upstream
 376  *
 377  * @param obj Image object.
 378  * @return Editability.
 379  *
 380  * A return value of EINA_TRUE means the image is a valid drag target
 381  * for drag and drop, and can be cut or pasted too.
 382  *
 383  * @ingroup Image
 384  */
 385 EAPI Eina_Bool        elm_image_editable_get(const Evas_Object *obj);
 386
 387 /**
 388 <<<<<<< HEAD
 389  * Get the basic Evas_Image object from this object (widget).
 390 =======
 391  * Get the inlined image object of the image widget.
 392 >>>>>>> remotes/origin/upstream
 393  *
 394  * @param obj The image object to get the inlined image from
 395  * @return The inlined image object, or NULL if none exists
 396  *
 397  * This function allows one to get the underlying @c Evas_Object of type
 398  * Image from this elementary widget. It can be useful to do things like get
 399  * the pixel data, save the image to a file, etc.
 400  *
 401  * @note Be careful to not manipulate it, as it is under control of
 402  * elementary.
 403  *
 404  * @ingroup Image
 405  */
 406 EAPI Evas_Object     *elm_image_object_get(const Evas_Object *obj);
 407
 408 /**
 409  * Set whether the original aspect ratio of the image should be kept on resize.
 410  *
 411  * @param obj The image object.
 412  * @param fixed @c EINA_TRUE if the image should retain the aspect,
 413  * @c EINA_FALSE otherwise.
 414  *
 415  * The original aspect ratio (width / height) of the image is usually
 416  * distorted to match the object's size. Enabling this option will retain
 417  * this original aspect, and the way that the image is fit into the object's
 418  * area depends on the option set by elm_image_fill_outside_set().
 419  *
 420  * @see elm_image_aspect_fixed_get()
 421  * @see elm_image_fill_outside_set()
 422  *
 423  * @ingroup Image
 424  */
 425 EAPI void             elm_image_aspect_fixed_set(Evas_Object *obj, Eina_Bool fixed);
 426
 427 /**
 428  * Get if the object retains the original aspect ratio.
 429  *
 430  * @param obj The image object.
 431  * @return @c EINA_TRUE if the object keeps the original aspect, @c EINA_FALSE
 432  * otherwise.
 433  *
 434  * @ingroup Image
 435  */
 436 EAPI Eina_Bool        elm_image_aspect_fixed_get(const Evas_Object *obj);
 437
 438 /**
 439  * @}
 440  */