src/lib/elm_icon.h

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