src/lib/elm_icon.h

   1 /**
   2  * @defgroup Icon Icon
   3  *
   4  * @image html img/widget/icon/preview-00.png
   5  * @image latex img/widget/icon/preview-00.eps
   6  *
   7  * An object that provides standard icon images (delete, edit, arrows, etc.)
   8  * or a custom file (PNG, JPG, EDJE, etc.) used for an icon.
   9  *
  10  * The icon image requested can be in the elementary theme, or in the
  11  * freedesktop.org paths. It's possible to set the order of preference from
  12  * where the image will be used.
  13  *
  14  * This API is very similar to @ref Image, but with ready to use images.
  15  *
  16  * Default images provided by the theme are described below.
  17  *
  18  * The first list contains icons that were first intended to be used in
  19  * toolbars, but can be used in many other places too:
  20  * @li home
  21  * @li close
  22  * @li apps
  23  * @li arrow_up
  24  * @li arrow_down
  25  * @li arrow_left
  26  * @li arrow_right
  27  * @li chat
  28  * @li clock
  29  * @li delete
  30  * @li edit
  31  * @li refresh
  32  * @li folder
  33  * @li file
  34  *
  35  * Now some icons that were designed to be used in menus (but again, you can
  36  * use them anywhere else):
  37  * @li menu/home
  38  * @li menu/close
  39  * @li menu/apps
  40  * @li menu/arrow_up
  41  * @li menu/arrow_down
  42  * @li menu/arrow_left
  43  * @li menu/arrow_right
  44  * @li menu/chat
  45  * @li menu/clock
  46  * @li menu/delete
  47  * @li menu/edit
  48  * @li menu/refresh
  49  * @li menu/folder
  50  * @li menu/file
  51  *
  52  * And here we have some media player specific icons:
  53  * @li media_player/forward
  54  * @li media_player/info
  55  * @li media_player/next
  56  * @li media_player/pause
  57  * @li media_player/play
  58  * @li media_player/prev
  59  * @li media_player/rewind
  60  * @li media_player/stop
  61  *
  62  * Signals that you can add callbacks for are:
  63  *
  64  * "clicked" - This is called when a user has clicked the icon
  65  *
  66  * An example of usage for this API follows:
  67  * @li @ref tutorial_icon
  68  */
  69
  70 /**
  71  * @addtogroup Icon
  72  * @{
  73  */
  74
  75 typedef enum
  76 {
  77    ELM_ICON_NONE,
  78    ELM_ICON_FILE,
  79    ELM_ICON_STANDARD
  80 } Elm_Icon_Type;
  81
  82 /**
  83  * @enum _Elm_Icon_Lookup_Order
  84  * @typedef Elm_Icon_Lookup_Order
  85  *
  86  * Lookup order used by elm_icon_standard_set(). Should look for icons in the
  87  * theme, FDO paths, or both?
  88  *
  89  * @ingroup Icon
  90  */
  91 typedef enum
  92 {
  93    ELM_ICON_LOOKUP_FDO_THEME, /**< icon look up order: freedesktop, theme */
  94    ELM_ICON_LOOKUP_THEME_FDO, /**< icon look up order: theme, freedesktop */
  95    ELM_ICON_LOOKUP_FDO, /**< icon look up order: freedesktop */
  96    ELM_ICON_LOOKUP_THEME /**< icon look up order: theme */
  97 } Elm_Icon_Lookup_Order;
  98
  99 /**
 100  * Add a new icon object to the parent.
 101  *
 102  * @param parent The parent object
 103  * @return The new object or NULL if it cannot be created
 104  *
 105  * @see elm_icon_file_set()
 106  *
 107  * @ingroup Icon
 108  */
 109 EAPI Evas_Object          *elm_icon_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
 110
 111 /**
 112  * Set the file that will be used as icon.
 113  *
 114  * @param obj The icon object
 115  * @param file The path to file that will be used as icon image
 116  * @param group The group that the icon belongs to an edje file
 117  *
 118  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 119  *
 120  * @note The icon image set by this function can be changed by
 121  * elm_icon_standard_set().
 122  *
 123  * @see elm_icon_file_get()
 124  *
 125  * @ingroup Icon
 126  */
 127 EAPI Eina_Bool             elm_icon_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
 128
 129 /**
 130  * Set a location in memory to be used as an icon
 131  *
 132  * @param obj The icon object
 133  * @param img The binary data that will be used as an image
 134  * @param size The size of binary data @p img
 135  * @param format Optional format of @p img to pass to the image loader
 136  * @param key Optional key of @p img to pass to the image loader (eg. if @p img is an edje file)
 137  *
 138  * The @p format string should be something like "png", "jpg", "tga",
 139  * "tiff", "bmp" etc. if it is provided (NULL if not). This improves
 140  * the loader performance as it tries the "correct" loader first before
 141  * trying a range of other possible loaders until one succeeds.
 142  *
 143  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 144  *
 145  * @note The icon image set by this function can be changed by
 146  * elm_icon_standard_set().
 147  *
 148  * @ingroup Icon
 149  */
 150 EAPI Eina_Bool             elm_icon_memfile_set(Evas_Object *obj, const void *img, size_t size, const char *format, const char *key) EINA_ARG_NONNULL(1, 2);
 151
 152 /**
 153  * Get the file that will be used as icon.
 154  *
 155  * @param obj The icon object
 156  * @param file The path to file that will be used as the icon image
 157  * @param group The group that the icon belongs to, in edje file
 158  *
 159  * @see elm_icon_file_set()
 160  *
 161  * @ingroup Icon
 162  */
 163 EAPI void                  elm_icon_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
 164
 165 /**
 166  * Set the file that will be used, but use a generated thumbnail.
 167  *
 168  * @param obj The icon object
 169  * @param file The path to file that will be used as icon image
 170  * @param group The group that the icon belongs to an edje file
 171  *
 172  * This functions like elm_icon_file_set() but requires the Ethumb library
 173  * support to be enabled successfully with elm_need_ethumb(). When set
 174  * the file indicated has a thumbnail generated and cached on disk for
 175  * future use or will directly use an existing cached thumbnail if it
 176  * is valid.
 177  *
 178  * @see elm_icon_file_set()
 179  *
 180  * @ingroup Icon
 181  */
 182 EAPI void                  elm_icon_thumb_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1, 2);
 183
 184 /**
 185  * Set the icon by icon standards names.
 186  *
 187  * @param obj The icon object
 188  * @param name The icon name
 189  *
 190  * @return (@c EINA_TRUE = success, @c EINA_FALSE = error)
 191  *
 192  * For example, freedesktop.org defines standard icon names such as "home",
 193  * "network", etc. There can be different icon sets to match those icon
 194  * keys. The @p name given as parameter is one of these "keys", and will be
 195  * used to look in the freedesktop.org paths and elementary theme. One can
 196  * change the lookup order with elm_icon_order_lookup_set().
 197  *
 198  * If name is not found in any of the expected locations and it is the
 199  * absolute path of an image file, this image will be used.
 200  *
 201  * @note The icon image set by this function can be changed by
 202  * elm_icon_file_set().
 203  *
 204  * @see elm_icon_standard_get()
 205  * @see elm_icon_file_set()
 206  *
 207  * @ingroup Icon
 208  */
 209 EAPI Eina_Bool             elm_icon_standard_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
 210
 211 /**
 212  * Get the icon name set by icon standard names.
 213  *
 214  * @param obj The icon object
 215  * @return The icon name
 216  *
 217  * If the icon image was set using elm_icon_file_set() instead of
 218  * elm_icon_standard_set(), then this function will return @c NULL.
 219  *
 220  * @see elm_icon_standard_set()
 221  *
 222  * @ingroup Icon
 223  */
 224 EAPI const char           *elm_icon_standard_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 225
 226 /**
 227  * Set the smooth scaling for an icon object.
 228  *
 229  * @param obj The icon object
 230  * @param smooth @c EINA_TRUE if smooth scaling should be used, @c EINA_FALSE
 231  * otherwise. Default is @c EINA_TRUE.
 232  *
 233  * Set the scaling algorithm to be used when scaling the icon image. Smooth
 234  * scaling provides a better resulting image, but is slower.
 235  *
 236  * The smooth scaling should be disabled when making animations that change
 237  * the icon size, since they will be faster. Animations that don't require
 238  * resizing of the icon can keep the smooth scaling enabled (even if the icon
 239  * is already scaled, since the scaled icon image will be cached).
 240  *
 241  * @see elm_icon_smooth_get()
 242  *
 243  * @ingroup Icon
 244  */
 245 EAPI void                  elm_icon_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1);
 246
 247 /**
 248  * Get whether smooth scaling is enabled for an icon object.
 249  *
 250  * @param obj The icon object
 251  * @return @c EINA_TRUE if smooth scaling is enabled, @c EINA_FALSE otherwise.
 252  *
 253  * @see elm_icon_smooth_set()
 254  *
 255  * @ingroup Icon
 256  */
 257 EAPI Eina_Bool             elm_icon_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 258
 259 /**
 260  * Disable scaling of this object.
 261  *
 262  * @param obj The icon object.
 263  * @param no_scale @c EINA_TRUE if the object is not scalable, @c EINA_FALSE
 264  * otherwise. Default is @c EINA_FALSE.
 265  *
 266  * This function disables scaling of the icon object through the function
 267  * elm_object_scale_set(). However, this does not affect the object
 268  * size/resize in any way. For that effect, take a look at
 269  * elm_icon_scale_set().
 270  *
 271  * @see elm_icon_no_scale_get()
 272  * @see elm_icon_scale_set()
 273  * @see elm_object_scale_set()
 274  *
 275  * @ingroup Icon
 276  */
 277 EAPI void                  elm_icon_no_scale_set(Evas_Object *obj, Eina_Bool no_scale) EINA_ARG_NONNULL(1);
 278
 279 /**
 280  * Get whether scaling is disabled on the object.
 281  *
 282  * @param obj The icon object
 283  * @return @c EINA_TRUE if scaling is disabled, @c EINA_FALSE otherwise
 284  *
 285  * @see elm_icon_no_scale_set()
 286  *
 287  * @ingroup Icon
 288  */
 289 EAPI Eina_Bool             elm_icon_no_scale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 290
 291 /**
 292  * Set if the object is (up/down) resizable.
 293  *
 294  * @param obj The icon object
 295  * @param scale_up A bool to set if the object is resizable up. Default is
 296  * @c EINA_TRUE.
 297  * @param scale_down A bool to set if the object is resizable down. Default
 298  * is @c EINA_TRUE.
 299  *
 300  * This function limits the icon object resize ability. If @p scale_up is set to
 301  * @c EINA_FALSE, the object can't have its height or width resized to a value
 302  * higher than the original icon size. Same is valid for @p scale_down.
 303  *
 304  * @see elm_icon_scale_get()
 305  *
 306  * @ingroup Icon
 307  */
 308 EAPI void                  elm_icon_scale_set(Evas_Object *obj, Eina_Bool scale_up, Eina_Bool scale_down) EINA_ARG_NONNULL(1);
 309
 310 /**
 311  * Get if the object is (up/down) resizable.
 312  *
 313  * @param obj The icon object
 314  * @param scale_up A bool to set if the object is resizable up
 315  * @param scale_down A bool to set if the object is resizable down
 316  *
 317  * @see elm_icon_scale_set()
 318  *
 319  * @ingroup Icon
 320  */
 321 EAPI void                  elm_icon_scale_get(const Evas_Object *obj, Eina_Bool *scale_up, Eina_Bool *scale_down) EINA_ARG_NONNULL(1);
 322
 323 /**
 324  * Get the object's image size
 325  *
 326  * @param obj The icon object
 327  * @param w A pointer to store the width in
 328  * @param h A pointer to store the height in
 329  *
 330  * @ingroup Icon
 331  */
 332 EAPI void                  elm_icon_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
 333
 334 /**
 335  * Set if the icon fill the entire object area.
 336  *
 337  * @param obj The icon object
 338  * @param fill_outside @c EINA_TRUE if the object is filled outside,
 339  * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 340  *
 341  * When the icon object is resized to a different aspect ratio from the
 342  * original icon image, the icon image will still keep its aspect. This flag
 343  * tells how the image should fill the object's area. They are: keep the
 344  * entire icon inside the limits of height and width of the object (@p
 345  * fill_outside is @c EINA_FALSE) or let the extra width or height go outside
 346  * of the object, and the icon will fill the entire object (@p fill_outside
 347  * is @c EINA_TRUE).
 348  *
 349  * @note Unlike @ref Image, there's no option in icon to set the aspect ratio
 350  * retain property to false. Thus, the icon image will always keep its
 351  * original aspect ratio.
 352  *
 353  * @see elm_icon_fill_outside_get()
 354  * @see elm_image_fill_outside_set()
 355  *
 356  * @ingroup Icon
 357  */
 358 EAPI void                  elm_icon_fill_outside_set(Evas_Object *obj, Eina_Bool fill_outside) EINA_ARG_NONNULL(1);
 359
 360 /**
 361  * Get if the object is filled outside.
 362  *
 363  * @param obj The icon object
 364  * @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
 365  *
 366  * @see elm_icon_fill_outside_set()
 367  *
 368  * @ingroup Icon
 369  */
 370 EAPI Eina_Bool             elm_icon_fill_outside_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 371
 372 /**
 373  * Set the prescale size for the icon.
 374  *
 375  * @param obj The icon object
 376  * @param size The prescale size. This value is used for both width and
 377  * height.
 378  *
 379  * This function sets a new size for pixmap representation of the given
 380  * icon. It allows the icon to be loaded already in the specified size,
 381  * reducing the memory usage and load time when loading a big icon with load
 382  * size set to a smaller size.
 383  *
 384  * It's equivalent to the elm_bg_load_size_set() function for bg.
 385  *
 386  * @note this is just a hint, the real size of the pixmap may differ
 387  * depending on the type of icon being loaded, being bigger than requested.
 388  *
 389  * @see elm_icon_prescale_get()
 390  * @see elm_bg_load_size_set()
 391  *
 392  * @ingroup Icon
 393  */
 394 EAPI void                  elm_icon_prescale_set(Evas_Object *obj, int size) EINA_ARG_NONNULL(1);
 395
 396 /**
 397  * Get the prescale size for the icon.
 398  *
 399  * @param obj The icon object
 400  * @return The prescale size
 401  *
 402  * @see elm_icon_prescale_set()
 403  *
 404  * @ingroup Icon
 405  */
 406 EAPI int                   elm_icon_prescale_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 407
 408 /**
 409  * Gets the image object of the icon. DO NOT MODIFY THIS.
 410  *
 411  * @param obj The icon object
 412  * @return The internal icon object
 413  *
 414  * @ingroup Icon
 415  */
 416 EAPI Evas_Object          *elm_icon_object_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
 417
 418 /**
 419  * Sets the icon lookup order used by elm_icon_standard_set().
 420  *
 421  * @param obj The icon object
 422  * @param order The icon lookup order (can be one of
 423  * ELM_ICON_LOOKUP_FDO_THEME, ELM_ICON_LOOKUP_THEME_FDO, ELM_ICON_LOOKUP_FDO
 424  * or ELM_ICON_LOOKUP_THEME)
 425  *
 426  * @see elm_icon_order_lookup_get()
 427  * @see Elm_Icon_Lookup_Order
 428  *
 429  * @ingroup Icon
 430  */
 431 EAPI void                  elm_icon_order_lookup_set(Evas_Object *obj, Elm_Icon_Lookup_Order order) EINA_ARG_NONNULL(1);
 432
 433 /**
 434  * Gets the icon lookup order.
 435  *
 436  * @param obj The icon object
 437  * @return The icon lookup order
 438  *
 439  * @see elm_icon_order_lookup_set()
 440  * @see Elm_Icon_Lookup_Order
 441  *
 442  * @ingroup Icon
 443  */
 444 EAPI Elm_Icon_Lookup_Order elm_icon_order_lookup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 445
 446 /**
 447  * Enable or disable preloading of the icon
 448  *
 449  * @param obj The icon object
 450  * @param disable If EINA_TRUE, preloading will be disabled
 451  * @ingroup Icon
 452  */
 453 EAPI void                  elm_icon_preload_set(Evas_Object *obj, Eina_Bool disable) EINA_ARG_NONNULL(1);
 454
 455 /**
 456  * Get if the icon supports animation or not.
 457  *
 458  * @param obj The icon object
 459  * @return @c EINA_TRUE if the icon supports animation,
 460  *         @c EINA_FALSE otherwise.
 461  *
 462  * Return if this elm icon's image can be animated. Currently Evas only
 463  * supports gif animation. If the return value is EINA_FALSE, other
 464  * elm_icon_animated_XXX APIs won't work.
 465  * @ingroup Icon
 466  */
 467 EAPI Eina_Bool             elm_icon_animated_available_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 468
 469 /**
 470  * Set animation mode of the icon.
 471  *
 472  * @param obj The icon object
 473  * @param anim @c EINA_TRUE if the object do animation job,
 474  * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 475  *
 476  * Since the default animation mode is set to EINA_FALSE,
 477  * the icon is shown without animation. Files like animated GIF files
 478  * can animate, and this is supported if you enable animated support
 479  * on the icon.
 480  * Set it to EINA_TRUE when the icon needs to be animated.
 481  * @ingroup Icon
 482  */
 483 EAPI void                  elm_icon_animated_set(Evas_Object *obj, Eina_Bool animated) EINA_ARG_NONNULL(1);
 484
 485 /**
 486  * Get animation mode of the icon.
 487  *
 488  * @param obj The icon object
 489  * @return The animation mode of the icon object
 490  * @see elm_icon_animated_set
 491  * @ingroup Icon
 492  */
 493 EAPI Eina_Bool             elm_icon_animated_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 494
 495 /**
 496  * Set animation play mode of the icon.
 497  *
 498  * @param obj The icon object
 499  * @param play @c EINA_TRUE the object play animation images,
 500  * @c EINA_FALSE otherwise. Default is @c EINA_FALSE.
 501  *
 502  * To play elm icon's animation, set play to EINA_TURE.
 503  * For example, you make gif player using this set/get API and click event.
 504  * This literally lets you control current play or paused state. To have
 505  * this work with animated GIF files for example, you first, before
 506  * setting the file have to use elm_icon_animated_set() to enable animation
 507  * at all on the icon.
 508  *
 509  * 1. Click event occurs
 510  * 2. Check play flag using elm_icon_animaged_play_get
 511  * 3. If elm icon was playing, set play to EINA_FALSE.
 512  *    Then animation will be stopped and vice versa
 513  * @ingroup Icon
 514  */
 515 EAPI void                  elm_icon_animated_play_set(Evas_Object *obj, Eina_Bool play) EINA_ARG_NONNULL(1);
 516
 517 /**
 518  * Get animation play mode of the icon.
 519  *
 520  * @param obj The icon object
 521  * @return The play mode of the icon object
 522  *
 523  * @see elm_icon_animated_play_get
 524  * @ingroup Icon
 525  */
 526 EAPI Eina_Bool             elm_icon_animated_play_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 527
 528 /**
 529  * @}
 530  */