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