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