src/lib/elm_icon.h

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