aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/efreet/efreet_icon.h
blob: 89a657cdd6cbdd1f1ba738ff5d911454edb97860 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
#ifndef EFREET_ICON_H
#define EFREET_ICON_H

/**
 * @file efreet_icon.h
 * @brief Contains the structures and methods used to support the FDO icon
 * theme specificiation.
 *
 * @internal
 * @defgroup Efreet_Icon_Group Efreet_Icon: The FDO Icon Theme
 *           Specification functions and structures
 * @ingroup Efreet_Group
 *
 * @{
 */


/**
 * Event id for cache update.
 */
EAPI extern int EFREET_EVENT_ICON_CACHE_UPDATE;

/**
 * The possible contexts for an icon directory
 */
typedef enum Efreet_Icon_Theme_Context
{
    EFREET_ICON_THEME_CONTEXT_NONE,
    EFREET_ICON_THEME_CONTEXT_ACTIONS,
    EFREET_ICON_THEME_CONTEXT_DEVICES,
    EFREET_ICON_THEME_CONTEXT_FILESYSTEMS,
    EFREET_ICON_THEME_CONTEXT_MIMETYPES
} Efreet_Icon_Theme_Context;

/**
 * The possible size types for an icon directory
 */
typedef enum Efreet_Icon_Size_Type
{
    EFREET_ICON_SIZE_TYPE_NONE,
    EFREET_ICON_SIZE_TYPE_FIXED,
    EFREET_ICON_SIZE_TYPE_SCALABLE,
    EFREET_ICON_SIZE_TYPE_THRESHOLD
} Efreet_Icon_Size_Type;

/**
 * Efreet_Icon_Theme
 */
typedef struct Efreet_Icon_Theme Efreet_Icon_Theme;

/**
 * Efreet_Icon_Theme
 * @brief contains all of the known information about a given theme
 */
struct Efreet_Icon_Theme
{
    struct
    {
        const char *internal;   /**< The internal theme name */
        const char *name;       /**< The user visible name */
    } name;                     /**< The different names for the theme */

    const char *comment;        /**< String describing the theme */
    const char *example_icon;   /**< Icon to use as an example of the theme */

    /* An icon theme can have multiple directories that store it's icons. We
     * need to be able to find a search each one. */

    Eina_List *paths;           /**< The paths */
    Eina_List *inherits;        /**< Icon themes we inherit from */
    Eina_List *directories;     /**< List of subdirectories for this theme */
};

/**
 * Efreet_Icon_Theme_Directory
 */
typedef struct Efreet_Icon_Theme_Directory Efreet_Icon_Theme_Directory;

/**
 * Efreet_Icon_Theme_Directory
 * @brief Contains all the information about a sub-directory of a theme
 */
struct Efreet_Icon_Theme_Directory
{
    const char *name;               /**< The directory name */
    Efreet_Icon_Theme_Context context;  /**< The type of icons in the dir */
    Efreet_Icon_Size_Type type;     /**< The size type for the icons */

    struct
    {
        unsigned int normal;        /**< The size for this directory */
        unsigned int min;           /**< The minimum size for this directory */
        unsigned int max;           /**< The maximum size for this directory */
        unsigned int threshold;     /**< Size difference threshold */
    } size;                         /**< The size settings for the icon theme */
};

/**
 * Efreet_Icon
 */
typedef struct Efreet_Icon Efreet_Icon;

/**
 * Efreet_Icon
 * @brief Contains all the information about a given icon
 */
struct Efreet_Icon
{
    const char *path;       /**< Full path to the icon */
    const char *name;       /**< Translated UTF8 string that can
                                    be used for the icon name */

    struct
    {
        int x0,             /**< x0 position */
            y0,             /**< y0 position */
            x1,             /**< x1 position */
            y1;             /**< y1 position */
    } embedded_text_rectangle;  /**< Rectangle where text can
                                        be displayed on the icon */

    Eina_List *attach_points; /**< List of points to be used as anchor
                                        points for emblems/overlays */

    unsigned int ref_count;    /**< References to this icon */
    unsigned char has_embedded_text_rectangle:1; /**< Has the embedded
                                                        rectangle set */
};

/**
 * Efreet_Icon_Point
 */
typedef struct Efreet_Icon_Point Efreet_Icon_Point;

/**
 * Efreet_Icon_Point
 * @brief Stores an x, y point.
 */
struct Efreet_Icon_Point
{
    int x;          /**< x coord */
    int y;          /**< y coord */
};

/**
 * @brief Returns the user icon directory
 *
 * @return Returns the user icon directory
 */
EAPI const char        *efreet_icon_user_dir_get(void);

/**
 * @brief Returns the deprecated user icon directory
 *
 * @return Returns the deprecated user icon directory
 */
EAPI const char        *efreet_icon_deprecated_user_dir_get(void);

/**
 * @brief Adds the given extension to the list of possible icon extensions
 *
 * @param[in] ext The extension to add to the list of checked extensions
 * @return Returns no value.
 */
EAPI void               efreet_icon_extension_add(const char *ext);


/**
 * @brief Gets the list of all extra directories to look for icons. These
 * directories are used to look for icons after looking in the user icon dir
 * and before looking in standard system directories. The order of search is
 * from first to last directory in this list. the strings in the list should
 * be created with eina_stringshare_add().
 *
 * @return Returns a list of strings that are paths to other icon directories
 */
EAPI Eina_List        **efreet_icon_extra_list_get(void);

/**
 * @brief Gets the list of all icon extensions to look for
 *
 * @return Returns a list of strings that are icon extensions to look for
 */
EAPI Eina_List         *efreet_icon_extensions_list_get(void);

/**
 * @brief Retrieves all of the non-hidden icon themes available on the system.
 * The returned list must be freed. Do not free the list data.
 *
 * @return Returns a list of Efreet_Icon structs for all the non-hidden icon
 * themes
 */
EAPI Eina_List         *efreet_icon_theme_list_get(void);

/**
 * @brief Tries to get the icon theme structure for the given theme name
 *
 * @param[in] theme_name The theme to look for
 * @return Returns the icon theme related to the given theme name or NULL if
 * none exists.
 */
EAPI Efreet_Icon_Theme *efreet_icon_theme_find(const char *theme_name);

/**
 * @brief Retrieves all of the information about the given icon.
 *
 * @param[in] theme_name The icon theme to look for
 * @param[in] icon The icon to look for
 * @param[in] size The icon size to look for
 * @return Returns the Efreet_Icon structure representing this icon or NULL
 * if the icon is not found
 */
EAPI Efreet_Icon       *efreet_icon_find(const char *theme_name,
                                            const char *icon,
                                            unsigned int size);

/**
 * @brief Retrieves all of the information about the first found icon in
 * the list.
 *
 * @param[in] theme_name The icon theme to look for
 * @param[in] icons List of icons to look for
 * @param[in] size; The icon size to look for
 * @return Returns the path representing first found icon or
 * NULL if none of the icons are found
 * @note This function will search the given theme for all icons before falling
 * back. This is useful when searching for mimetype icons.
 *
 * There is no guarantee for how long the pointer to the path will be valid.
 * If the pointer is to be kept, the user must create a copy of the path.
 */
EAPI const char        *efreet_icon_list_find(const char *theme_name,
                                                Eina_List *icons,
                                                unsigned int size);

/**
 * @brief Retrives the path to the given icon.
 *
 * @param[in] theme_name The icon theme to look for
 * @param[in] icon The icon to look for
 * @param[in] size; The icon size to look for
 * @return Returns the path to the given icon or NULL if none found
 *
 * There is no guarantee for how long the pointer to the path will be valid.
 * If the pointer is to be kept, the user must create a copy of the path.
 */
EAPI const char        *efreet_icon_path_find(const char *theme_name,
                                                const char *icon,
                                                unsigned int size);

/**
 * @brief Free's the given icon and all its internal data.
 *
 * @param[in] icon The Efreet_Icon to cleanup
 * @return Returns no value.
 */
EAPI void               efreet_icon_free(Efreet_Icon *icon);

/**
 * @}
 */

#endif