src/lib/elm_image.h

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