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 _Elm_Icon_Type
  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 _Elm_Icon_Lookup_Order
  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     */
 531