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