Mercurial > pidgin.yaz
comparison libpurple/smiley.h @ 26760:78ef23551355
merge of '18a763ca3d80ae60e586ade3456b8d59196a7b8f'
and '54b44cf23dd4b4d1e79d9c5b04a1496758072127'
author | Paul Aurich <paul@darkrain42.org> |
---|---|
date | Mon, 20 Apr 2009 00:05:54 +0000 |
parents | d58fa4c34987 1af02540d7b3 |
children | 0c4976fb5f57 |
comparison
equal
deleted
inserted
replaced
26753:d58fa4c34987 | 26760:78ef23551355 |
---|---|
59 /** @name Custom Smiley API */ | 59 /** @name Custom Smiley API */ |
60 /**************************************************************************/ | 60 /**************************************************************************/ |
61 /*@{*/ | 61 /*@{*/ |
62 | 62 |
63 /** | 63 /** |
64 * GObject foo. | 64 * GObject-fu. |
65 * @internal. | 65 * @internal. |
66 */ | 66 */ |
67 GType purple_smiley_get_type(void); | 67 GType purple_smiley_get_type(void); |
68 | 68 |
69 /** | 69 /** |
70 * Creates a new custom smiley structure and populates it. | 70 * Creates a new custom smiley from a PurpleStoredImage. |
71 * | 71 * |
72 * If a custom smiley with the informed shortcut already exist, it | 72 * If a custom smiley with the given shortcut already exists, it |
73 * will be automaticaly returned. | 73 * will be automaticaly returned. |
74 * | 74 * |
75 * @param img The image associated with the smiley. | 75 * @param img The image associated with the smiley. |
76 * @param shortcut The custom smiley associated shortcut. | 76 * @param shortcut The associated shortcut (e.g. "(homer)"). |
77 * | 77 * |
78 * @return The custom smiley structure filled up. | 78 * @return The custom smiley. |
79 */ | 79 */ |
80 PurpleSmiley * | 80 PurpleSmiley * |
81 purple_smiley_new(PurpleStoredImage *img, const char *shortcut); | 81 purple_smiley_new(PurpleStoredImage *img, const char *shortcut); |
82 | 82 |
83 /** | 83 /** |
84 * Creates a new custom smiley structure and populates it. | 84 * Creates a new custom smiley, reading the image data from a file. |
85 * | 85 * |
86 * The data is retrieved from an already existent file. | 86 * If a custom smiley with the given shortcut already exists, it |
87 * | |
88 * If a custom smiley with the informed shortcut already exist, it | |
89 * will be automaticaly returned. | 87 * will be automaticaly returned. |
90 * | 88 * |
91 * @param shortcut The custom smiley associated shortcut. | 89 * @param shortcut The associated shortcut (e.g. "(homer)"). |
92 * @param filepath The image file to be imported to a | 90 * @param filepath The image file. |
93 * new custom smiley. | 91 * |
94 * | 92 * @return The custom smiley. |
95 * @return The custom smiley structure filled up. | |
96 */ | 93 */ |
97 PurpleSmiley * | 94 PurpleSmiley * |
98 purple_smiley_new_from_file(const char *shortcut, const char *filepath); | 95 purple_smiley_new_from_file(const char *shortcut, const char *filepath); |
99 | 96 |
100 /** | 97 /** |
101 * Destroy the custom smiley and release the associated resources. | 98 * Destroys the custom smiley and release the associated resources. |
102 * | 99 * |
103 * @param smiley The custom smiley. | 100 * @param smiley The custom smiley. |
104 */ | 101 */ |
105 void | 102 void |
106 purple_smiley_delete(PurpleSmiley *smiley); | 103 purple_smiley_delete(PurpleSmiley *smiley); |
107 | 104 |
108 /** | 105 /** |
109 * Changes the custom smiley's shortcut. | 106 * Changes the custom smiley's shortcut. |
110 * | 107 * |
111 * @param smiley The custom smiley. | 108 * @param smiley The custom smiley. |
112 * @param shortcut The custom smiley associated shortcut. | 109 * @param shortcut The new shortcut. A custom smiley with this shortcut |
113 * | 110 * cannot already be in use. |
114 * @return TRUE whether the shortcut is not associated with another | 111 * |
115 * custom smiley and the parameters are valid. FALSE otherwise. | 112 * @return TRUE if the shortcut was changed. FALSE otherwise. |
116 */ | 113 */ |
117 gboolean | 114 gboolean |
118 purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut); | 115 purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut); |
119 | 116 |
120 /** | 117 /** |
121 * Changes the custom smiley's data. | 118 * Changes the custom smiley's image data. |
122 * | |
123 * When the filename controling is made outside this API, the param | |
124 * #keepfilename must be TRUE. | |
125 * Otherwise, the file and filename will be regenerated, and the | |
126 * old one will be removed. | |
127 * | 119 * |
128 * @param smiley The custom smiley. | 120 * @param smiley The custom smiley. |
129 * @param smiley_data The custom smiley data. | 121 * @param smiley_data The custom smiley data, which the smiley code |
130 * @param smiley_data_len The custom smiley data length. | 122 * takes ownership of and will free. |
123 * @param smiley_data_len The length of the data in @a smiley_data. | |
131 */ | 124 */ |
132 void | 125 void |
133 purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data, | 126 purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data, |
134 size_t smiley_data_len); | 127 size_t smiley_data_len); |
135 | 128 |
136 /** | 129 /** |
137 * Returns the custom smiley's associated shortcut. | 130 * Returns the custom smiley's associated shortcut (e.g. "(homer)"). |
138 * | 131 * |
139 * @param smiley The custom smiley. | 132 * @param smiley The custom smiley. |
140 * | 133 * |
141 * @return The shortcut. | 134 * @return The shortcut. |
142 */ | 135 */ |
153 | 146 |
154 /** | 147 /** |
155 * Returns the PurpleStoredImage with the reference counter incremented. | 148 * Returns the PurpleStoredImage with the reference counter incremented. |
156 * | 149 * |
157 * The returned PurpleStoredImage reference counter must be decremented | 150 * The returned PurpleStoredImage reference counter must be decremented |
158 * after use. | 151 * when the caller is done using it. |
159 * | 152 * |
160 * @param smiley The custom smiley. | 153 * @param smiley The custom smiley. |
161 * | 154 * |
162 * @return A PurpleStoredImage reference. | 155 * @return A PurpleStoredImage. |
163 */ | 156 */ |
164 PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley); | 157 PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley); |
165 | 158 |
166 /** | 159 /** |
167 * Returns the custom smiley's data. | 160 * Returns the custom smiley's data. |
168 * | 161 * |
169 * @param smiley The custom smiley. | 162 * @param smiley The custom smiley. |
170 * @param len If not @c NULL, the length of the icon data returned | 163 * @param len If not @c NULL, the length of the image data returned |
171 * will be set in the location pointed to by this. | 164 * will be set in the location pointed to by this. |
172 * | 165 * |
173 * @return A pointer to the custom smiley data. | 166 * @return A pointer to the custom smiley data. |
174 */ | 167 */ |
175 gconstpointer purple_smiley_get_data(const PurpleSmiley *smiley, size_t *len); | 168 gconstpointer purple_smiley_get_data(const PurpleSmiley *smiley, size_t *len); |
192 * | 185 * |
193 * In general, it is not appropriate to be poking in the file cached | 186 * In general, it is not appropriate to be poking in the file cached |
194 * directly. If you find yourself wanting to use this function, think | 187 * directly. If you find yourself wanting to use this function, think |
195 * very long and hard about it, and then don't. | 188 * very long and hard about it, and then don't. |
196 * | 189 * |
190 * Think some more. | |
191 * | |
197 * @param smiley The custom smiley. | 192 * @param smiley The custom smiley. |
198 * | 193 * |
199 * @return A full path to the file, or @c NULL under various conditions. | 194 * @return A full path to the file, or @c NULL under various conditions. |
200 * The caller should use #g_free to free the returned string. | 195 * The caller should use #g_free to free the returned string. |
201 */ | 196 */ |
208 /** @name Custom Smiley Subsystem API */ | 203 /** @name Custom Smiley Subsystem API */ |
209 /**************************************************************************/ | 204 /**************************************************************************/ |
210 /*@{*/ | 205 /*@{*/ |
211 | 206 |
212 /** | 207 /** |
213 * Returns a list of all custom smileys. The caller should free the list. | 208 * Returns a list of all custom smileys. The caller is responsible for freeing |
209 * the list. | |
214 * | 210 * |
215 * @return A list of all custom smileys. | 211 * @return A list of all custom smileys. |
216 */ | 212 */ |
217 GList * | 213 GList * |
218 purple_smileys_get_all(void); | 214 purple_smileys_get_all(void); |
219 | 215 |
220 /** | 216 /** |
221 * Returns the custom smiley given it's shortcut. | 217 * Returns a custom smiley given its shortcut. |
222 * | 218 * |
223 * @param shortcut The custom smiley's shortcut. | 219 * @param shortcut The custom smiley's shortcut. |
224 * | 220 * |
225 * @return The custom smiley (with a reference for the caller) if found, | 221 * @return The custom smiley if found, or @c NULL if not found. |
226 * or @c NULL if not found. | |
227 */ | 222 */ |
228 PurpleSmiley * | 223 PurpleSmiley * |
229 purple_smileys_find_by_shortcut(const char *shortcut); | 224 purple_smileys_find_by_shortcut(const char *shortcut); |
230 | 225 |
231 /** | 226 /** |
232 * Returns the custom smiley given it's checksum. | 227 * Returns a custom smiley given its checksum. |
233 * | 228 * |
234 * @param checksum The custom smiley's checksum. | 229 * @param checksum The custom smiley's checksum. |
235 * | 230 * |
236 * @return The custom smiley (with a reference for the caller) if found, | 231 * @return The custom smiley if found, or @c NULL if not found. |
237 * or @c NULL if not found. | |
238 */ | 232 */ |
239 PurpleSmiley * | 233 PurpleSmiley * |
240 purple_smileys_find_by_checksum(const char *checksum); | 234 purple_smileys_find_by_checksum(const char *checksum); |
241 | 235 |
242 /** | 236 /** |
243 * Returns the directory used to store custom smiley cached files. | 237 * Returns the directory used to store custom smiley cached files. |
244 * | 238 * |
245 * The default directory is PURPLEDIR/smileys, unless otherwise specified | 239 * The default directory is PURPLEDIR/custom_smiley, unless otherwise specified |
246 * by purple_buddy_icons_set_cache_dir(). | 240 * by purple_buddy_icons_set_cache_dir(). |
247 * | 241 * |
248 * @return The directory to store custom smyles cached files to. | 242 * @return The directory in which to store custom smileys cached files. |
249 */ | 243 */ |
250 const char *purple_smileys_get_storing_dir(void); | 244 const char *purple_smileys_get_storing_dir(void); |
251 | 245 |
252 /** | 246 /** |
253 * Initializes the custom smiley subsystem. | 247 * Initializes the custom smiley subsystem. |