src/lib/efreet_icon.h

   1 #ifndef EFREET_ICON_H
   2 #define EFREET_ICON_H
   3
   4 /**
   5  * @file efreet_icon.h
   6  * @brief Contains the structures and methods used to support the FDO icon
   7  * theme specificiation.
   8  * @addtogroup Efreet_Icon Efreet_Icon: The FDO Icon Theme
   9  *                  Specification functions and structures
  10  *
  11  * @{
  12  */
  13
  14
  15 /**
  16  * Event id for cache update.
  17  */
  18 EAPI extern int EFREET_EVENT_ICON_CACHE_UPDATE;
  19
  20 /**
  21  * The possible contexts for an icon directory
  22  */
  23 typedef enum Efreet_Icon_Theme_Context
  24 {
  25     EFREET_ICON_THEME_CONTEXT_NONE,
  26     EFREET_ICON_THEME_CONTEXT_ACTIONS,
  27     EFREET_ICON_THEME_CONTEXT_DEVICES,
  28     EFREET_ICON_THEME_CONTEXT_FILESYSTEMS,
  29     EFREET_ICON_THEME_CONTEXT_MIMETYPES
  30 } Efreet_Icon_Theme_Context;
  31
  32 /**
  33  * The possible size types for an icon directory
  34  */
  35 typedef enum Efreet_Icon_Size_Type
  36 {
  37     EFREET_ICON_SIZE_TYPE_NONE,
  38     EFREET_ICON_SIZE_TYPE_FIXED,
  39     EFREET_ICON_SIZE_TYPE_SCALABLE,
  40     EFREET_ICON_SIZE_TYPE_THRESHOLD
  41 } Efreet_Icon_Size_Type;
  42
  43 /**
  44  * Efreet_Icon_Theme
  45  */
  46 typedef struct Efreet_Icon_Theme Efreet_Icon_Theme;
  47
  48 /**
  49  * Efreet_Icon_Theme
  50  * @brief contains all of the known information about a given theme
  51  */
  52 struct Efreet_Icon_Theme
  53 {
  54     struct
  55     {
  56         const char *internal;   /**< The internal theme name */
  57         const char *name;       /**< The user visible name */
  58     } name;                     /**< The different names for the theme */
  59
  60     const char *comment;        /**< String describing the theme */
  61     const char *example_icon;   /**< Icon to use as an example of the theme */
  62
  63     /* An icon theme can have multiple directories that store it's icons. We
  64      * need to be able to find a search each one. */
  65
  66     Eina_List *paths;           /**< The paths */
  67     Eina_List *inherits;        /**< Icon themes we inherit from */
  68     Eina_List *directories;     /**< List of subdirectories for this theme */
  69 };
  70
  71 /**
  72  * Efreet_Icon_Theme_Directory
  73  */
  74 typedef struct Efreet_Icon_Theme_Directory Efreet_Icon_Theme_Directory;
  75
  76 /**
  77  * Efreet_Icon_Theme_Directory
  78  * @brief Contains all the information about a sub-directory of a theme
  79  */
  80 struct Efreet_Icon_Theme_Directory
  81 {
  82     const char *name;               /**< The directory name */
  83     Efreet_Icon_Theme_Context context;  /**< The type of icons in the dir */
  84     Efreet_Icon_Size_Type type;     /**< The size type for the icons */
  85
  86     struct
  87     {
  88         unsigned int normal;        /**< The size for this directory */
  89         unsigned int min;           /**< The minimum size for this directory */
  90         unsigned int max;           /**< The maximum size for this directory */
  91         unsigned int threshold;     /**< Size difference threshold */
  92     } size;                         /**< The size settings for the icon theme */
  93 };
  94
  95 /**
  96  * Efreet_Icon
  97  */
  98 typedef struct Efreet_Icon Efreet_Icon;
  99
 100 /**
 101  * Efreet_Icon
 102  * @brief Contains all the information about a given icon
 103  */
 104 struct Efreet_Icon
 105 {
 106     const char *path;       /**< Full path to the icon */
 107     const char *name;       /**< Translated UTF8 string that can
 108                                     be used for the icon name */
 109
 110     struct
 111     {
 112         int x0,             /**< x0 position */
 113             y0,             /**< y0 position */
 114             x1,             /**< x1 position */
 115             y1;             /**< y1 position */
 116     } embedded_text_rectangle;  /**< Rectangle where text can
 117                                         be displayed on the icon */
 118
 119     Eina_List *attach_points; /**< List of points to be used as anchor
 120                                         points for emblems/overlays */
 121
 122     unsigned int ref_count;    /**< References to this icon */
 123     unsigned char has_embedded_text_rectangle:1; /**< Has the embedded
 124                                                         rectangle set */
 125 };
 126
 127 /**
 128  * Efreet_Icon_Point
 129  */
 130 typedef struct Efreet_Icon_Point Efreet_Icon_Point;
 131
 132 /**
 133  * Efreet_Icon_Point
 134  * @brief Stores an x, y point.
 135  */
 136 struct Efreet_Icon_Point
 137 {
 138     int x;          /**< x coord */
 139     int y;          /**< y coord */
 140 };
 141
 142 /**
 143  * @return Returns the user icon directory
 144  * @brief Returns the user icon directory
 145  */
 146 EAPI const char        *efreet_icon_user_dir_get(void);
 147
 148 /**
 149  * @return Returns the deprecated user icon directory
 150  * @brief Returns the deprecated user icon directory
 151  */
 152 EAPI const char        *efreet_icon_deprecated_user_dir_get(void);
 153
 154 /**
 155  * @param ext The extension to add to the list of checked extensions
 156  * @return Returns no value.
 157  * @brief Adds the given extension to the list of possible icon extensions
 158  */
 159 EAPI void               efreet_icon_extension_add(const char *ext);
 160
 161
 162 /**
 163  * @return Returns a list of strings that are paths to other icon directories
 164  * @brief Gets the list of all extra directories to look for icons. These
 165  * directories are used to look for icons after looking in the user icon dir
 166  * and before looking in standard system directories. The order of search is
 167  * from first to last directory in this list. the strings in the list should
 168  * be created with eina_stringshare_add().
 169  */
 170 EAPI Eina_List        **efreet_icon_extra_list_get(void);
 171
 172 /**
 173  * @return Returns a list of strings that are icon extensions to look for
 174  * @brief Gets the list of all icon extensions to look for
 175  */
 176 EAPI Eina_List         *efreet_icon_extensions_list_get(void);
 177
 178 /**
 179  * @return Returns a list of Efreet_Icon structs for all the non-hidden icon
 180  * themes
 181  * @brief Retrieves all of the non-hidden icon themes available on the system.
 182  * The returned list must be freed. Do not free the list data.
 183  */
 184 EAPI Eina_List         *efreet_icon_theme_list_get(void);
 185
 186 /**
 187  * @param theme_name The theme to look for
 188  * @return Returns the icon theme related to the given theme name or NULL if
 189  * none exists.
 190  * @brief Tries to get the icon theme structure for the given theme name
 191  */
 192 EAPI Efreet_Icon_Theme *efreet_icon_theme_find(const char *theme_name);
 193
 194 /**
 195  * @param theme_name The icon theme to look for
 196  * @param icon The icon to look for
 197  * @param size The icon size to look for
 198  * @return Returns the Efreet_Icon structure representing this icon or NULL
 199  * if the icon is not found
 200  * @brief Retrieves all of the information about the given icon.
 201  */
 202 EAPI Efreet_Icon       *efreet_icon_find(const char *theme_name,
 203                                             const char *icon,
 204                                             unsigned int size);
 205
 206 /**
 207  * @param theme_name The icon theme to look for
 208  * @param icons List of icons to look for
 209  * @param size; The icon size to look for
 210  * @return Returns the path representing first found icon or
 211  * NULL if none of the icons are found
 212  * @brief Retrieves all of the information about the first found icon in
 213  * the list.
 214  * @note This function will search the given theme for all icons before falling
 215  * back. This is useful when searching for mimetype icons.
 216  *
 217  * There is no guarantee for how long the pointer to the path will be valid.
 218  * If the pointer is to be kept, the user must create a copy of the path.
 219  */
 220 EAPI const char        *efreet_icon_list_find(const char *theme_name,
 221                                                 Eina_List *icons,
 222                                                 unsigned int size);
 223
 224 /**
 225  * @param theme_name The icon theme to look for
 226  * @param icon The icon to look for
 227  * @param size; The icon size to look for
 228  * @return Returns the path to the given icon or NULL if none found
 229  * @brief Retrives the path to the given icon.
 230  *
 231  * There is no guarantee for how long the pointer to the path will be valid.
 232  * If the pointer is to be kept, the user must create a copy of the path.
 233  */
 234 EAPI const char        *efreet_icon_path_find(const char *theme_name,
 235                                                 const char *icon,
 236                                                 unsigned int size);
 237
 238 /**
 239  * @param icon The Efreet_Icon to cleanup
 240  * @return Returns no value.
 241  * @brief Free's the given icon and all its internal data.
 242  */
 243 EAPI void               efreet_icon_free(Efreet_Icon *icon);
 244
 245 /**
 246  * @}
 247  */
 248
 249 #endif