src/lib/elm_icon.h

   1 /**
   2  * @defgroup Icon Icon
   3  * @ingroup elm_widget_group
   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 that follow (more or less) the @b Freedesktop icon naming
  38  * specification. Use of these names are @b preferred, at least if you want to
  39  * give your user the ability to use other themes. All these icons can be
  40  * seen in the elementary_test application, the test is called "Icon Standard".
  41  *
  42  * @li @c "folder" (since 1.13)
  43  * @li @c "user-home" (since 1.13)
  44  * @li @c "user-trash" (since 1.13)
  45  *
  46  * @li @c "view-close" (since 1.13)
  47  * @li @c "view-refresh" (since 1.13)
  48  *
  49  * @li @c "window-close" (since 1.13)
  50  *
  51  * @li @c "document-close" (since 1.13)
  52  * @li @c "document-edit" (since 1.13)
  53  *
  54  * @li @c "dialog-info" (since 1.13)
  55  * @li @c "dialog-close" (since 1.13)
  56  *
  57  * @li @c "arrow-up" (since 1.13)
  58  * @li @c "arrow-down" (since 1.13)
  59  * @li @c "arrow-left" (since 1.13)
  60  * @li @c "arrow-right" (since 1.13)
  61  * @li @c "arrow-up-left" (since 1.13)
  62  * @li @c "arrow-up-right" (since 1.13)
  63  * @li @c "arrow-down-left" (since 1.13)
  64  * @li @c "arrow-down-right" (since 1.13)
  65  *
  66  * @li @c "edit-delete" (since 1.13)
  67  *
  68  * @li @c "application-chat" (since 1.13)
  69  * @li @c "application-clock" (since 1.13)
  70  *
  71  * @li @c "media-seek-forward" (since 1.13)
  72  * @li @c "media-seek-backward" (since 1.13)
  73  * @li @c "media-skip-forward" (since 1.13)
  74  * @li @c "media-skip-backward" (since 1.13)
  75  * @li @c "media-playback-pause" (since 1.13)
  76  * @li @c "media-playback-start" (since 1.13)
  77  * @li @c "media-playback-stop" (since 1.13)
  78  * @li @c "media-eject" (since 1.13)
  79  *
  80  * @li @c "audio-volume" (since 1.13)
  81  * @li @c "audio-volume-muted" (since 1.13)
  82  *
  83  * These are names for icons that were first intended to be used in
  84  * toolbars, but can be used in many other places too:
  85  * @li @c "home"
  86  * @li @c "close"
  87  * @li @c "apps"
  88  * @li @c "arrow_up"
  89  * @li @c "arrow_down"
  90  * @li @c "arrow_left"
  91  * @li @c "arrow_right"
  92  * @li @c "chat"
  93  * @li @c "clock"
  94  * @li @c "delete"
  95  * @li @c "edit"
  96  * @li @c "refresh"
  97  * @li @c "folder"
  98  * @li @c "file"
  99  *
 100  * These are names for icons that were designed to be used in menus
 101  * (but again, you can use them anywhere else):
 102  * @li @c "menu/home"
 103  * @li @c "menu/close"
 104  * @li @c "menu/apps"
 105  * @li @c "menu/arrow_up"
 106  * @li @c "menu/arrow_down"
 107  * @li @c "menu/arrow_left"
 108  * @li @c "menu/arrow_right"
 109  * @li @c "menu/chat"
 110  * @li @c "menu/clock"
 111  * @li @c "menu/delete"
 112  * @li @c "menu/edit"
 113  * @li @c "menu/refresh"
 114  * @li @c "menu/folder"
 115  * @li @c "menu/file"
 116  *
 117  * And these are names for some media player specific icons:
 118  * @li @c "media_player/forward"
 119  * @li @c "media_player/info"
 120  * @li @c "media_player/next"
 121  * @li @c "media_player/pause"
 122  * @li @c "media_player/play"
 123  * @li @c "media_player/prev"
 124  * @li @c "media_player/rewind"
 125  * @li @c "media_player/stop"
 126  *
 127  * This widget emits the following signals, besides the ones sent from
 128  * @ref Image:
 129  * - @c "thumb,done" - elm_icon_thumb_set() has completed with success
 130  *                     (since 1.7)
 131  * - @c "thumb,error" - elm_icon_thumb_set() has failed (since 1.7)
 132  *
 133  * Elementary icon objects support the following API calls:
 134  * @li elm_object_signal_emit()
 135  * @li elm_object_signal_callback_add()
 136  * @li elm_object_signal_callback_del()
 137  * for emitting and listening to signals on the object, when the
 138  * internal image comes from an Edje object. This behavior was added
 139  * unintentionally, though, and is @b deprecated. Expect it to be
 140  * dropped on future releases.
 141  *
 142  * An example of usage for this API follows:
 143  * @li @ref tutorial_icon
 144  */
 145
 146 #ifdef EFL_EO_API_SUPPORT
 147 #include "elm_icon_eo.h"
 148 #endif
 149 #ifndef EFL_NOLEGACY_API_SUPPORT
 150 #include "elm_icon_legacy.h"
 151 #endif
 152 /**
 153  * @}
 154  */