Mercurial > pidgin.yaz
comparison libgaim/notify.h @ 14192:60b1bc8dbf37
[gaim-migrate @ 16863]
Renamed 'core' to 'libgaim'
committer: Tailor Script <tailor@pidgin.im>
author | Evan Schoenberg <evan.s@dreskin.net> |
---|---|
date | Sat, 19 Aug 2006 01:50:10 +0000 |
parents | |
children | b81e4e44b509 |
comparison
equal
deleted
inserted
replaced
14191:009db0b357b5 | 14192:60b1bc8dbf37 |
---|---|
1 /** | |
2 * @file notify.h Notification API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
25 #ifndef _GAIM_NOTIFY_H_ | |
26 #define _GAIM_NOTIFY_H_ | |
27 | |
28 #include <stdlib.h> | |
29 #include <glib-object.h> | |
30 #include <glib.h> | |
31 | |
32 #include "connection.h" | |
33 | |
34 | |
35 /** | |
36 * Notification close callbacks. | |
37 */ | |
38 typedef void (*GaimNotifyCloseCallback) (gpointer user_data); | |
39 | |
40 | |
41 /** | |
42 * Notification types. | |
43 */ | |
44 typedef enum | |
45 { | |
46 GAIM_NOTIFY_MESSAGE = 0, /**< Message notification. */ | |
47 GAIM_NOTIFY_EMAIL, /**< Single e-mail notification. */ | |
48 GAIM_NOTIFY_EMAILS, /**< Multiple e-mail notification. */ | |
49 GAIM_NOTIFY_FORMATTED, /**< Formatted text. */ | |
50 GAIM_NOTIFY_SEARCHRESULTS, /**< Buddy search results. */ | |
51 GAIM_NOTIFY_USERINFO, /**< Formatted userinfo text. */ | |
52 GAIM_NOTIFY_URI /**< URI notification or display. */ | |
53 | |
54 } GaimNotifyType; | |
55 | |
56 | |
57 /** | |
58 * Notification message types. | |
59 */ | |
60 typedef enum | |
61 { | |
62 GAIM_NOTIFY_MSG_ERROR = 0, /**< Error notification. */ | |
63 GAIM_NOTIFY_MSG_WARNING, /**< Warning notification. */ | |
64 GAIM_NOTIFY_MSG_INFO /**< Information notification. */ | |
65 | |
66 } GaimNotifyMsgType; | |
67 | |
68 | |
69 /** | |
70 * The types of buttons | |
71 */ | |
72 typedef enum | |
73 { | |
74 GAIM_NOTIFY_BUTTON_LABELED = 0, /**< special use, see _button_add_labeled */ | |
75 GAIM_NOTIFY_BUTTON_CONTINUE = 1, | |
76 GAIM_NOTIFY_BUTTON_ADD, | |
77 GAIM_NOTIFY_BUTTON_INFO, | |
78 GAIM_NOTIFY_BUTTON_IM, | |
79 GAIM_NOTIFY_BUTTON_JOIN, | |
80 GAIM_NOTIFY_BUTTON_INVITE | |
81 } GaimNotifySearchButtonType; | |
82 | |
83 | |
84 /** | |
85 * Search results object. | |
86 */ | |
87 typedef struct | |
88 { | |
89 GList *columns; /**< List of the search column objects. */ | |
90 GList *rows; /**< List of rows in the result. */ | |
91 GList *buttons; /**< List of buttons to display. */ | |
92 | |
93 } GaimNotifySearchResults; | |
94 | |
95 | |
96 /** | |
97 * Single column of a search result. | |
98 */ | |
99 typedef struct | |
100 { | |
101 char *title; /**< Title of the column. */ | |
102 | |
103 } GaimNotifySearchColumn; | |
104 | |
105 | |
106 /** | |
107 * Callback for a button in a search result. | |
108 * | |
109 * @param c the GaimConnection passed to gaim_notify_searchresults | |
110 * @param row the contents of the selected row | |
111 * @param user_data User defined data. | |
112 */ | |
113 typedef void (*GaimNotifySearchResultsCallback)(GaimConnection *c, GList *row, | |
114 gpointer user_data); | |
115 | |
116 | |
117 /** | |
118 * Definition of a button. | |
119 */ | |
120 typedef struct | |
121 { | |
122 GaimNotifySearchButtonType type; | |
123 GaimNotifySearchResultsCallback callback; /**< Function to be called when clicked. */ | |
124 char *label; /**< only for GAIM_NOTIFY_BUTTON_LABELED */ | |
125 } GaimNotifySearchButton; | |
126 | |
127 | |
128 /** | |
129 * Notification UI operations. | |
130 */ | |
131 typedef struct | |
132 { | |
133 void *(*notify_message)(GaimNotifyMsgType type, const char *title, | |
134 const char *primary, const char *secondary); | |
135 | |
136 void *(*notify_email)(GaimConnection *gc, | |
137 const char *subject, const char *from, | |
138 const char *to, const char *url); | |
139 | |
140 void *(*notify_emails)(GaimConnection *gc, | |
141 size_t count, gboolean detailed, | |
142 const char **subjects, const char **froms, | |
143 const char **tos, const char **urls); | |
144 | |
145 void *(*notify_formatted)(const char *title, const char *primary, | |
146 const char *secondary, const char *text); | |
147 | |
148 void *(*notify_searchresults)(GaimConnection *gc, const char *title, | |
149 const char *primary, const char *secondary, | |
150 GaimNotifySearchResults *results, gpointer user_data); | |
151 | |
152 void (*notify_searchresults_new_rows)(GaimConnection *gc, | |
153 GaimNotifySearchResults *results, | |
154 void *data); | |
155 | |
156 void *(*notify_userinfo)(GaimConnection *gc, const char *who, | |
157 const char *text); | |
158 | |
159 void *(*notify_uri)(const char *uri); | |
160 | |
161 void (*close_notify)(GaimNotifyType type, void *ui_handle); | |
162 | |
163 } GaimNotifyUiOps; | |
164 | |
165 | |
166 #ifdef __cplusplus | |
167 extern "C" { | |
168 #endif | |
169 | |
170 | |
171 /**************************************************************************/ | |
172 /** Search results notification API */ | |
173 /**************************************************************************/ | |
174 /*@{*/ | |
175 | |
176 /** | |
177 * Displays results from a buddy search. This can be, for example, | |
178 * a window with a list of all found buddies, where you are given the | |
179 * option of adding buddies to your buddy list. | |
180 * | |
181 * @param gc The GaimConnection handle associated with the information. | |
182 * @param title The title of the message. If this is NULL, the title | |
183 * will be "Search Results." | |
184 * @param primary The main point of the message. | |
185 * @param secondary The secondary information. | |
186 * @param results The GaimNotifySearchResults instance. | |
187 * @param cb The callback to call when the user closes | |
188 * the notification. | |
189 * @param user_data The data to pass to the close callback and any other | |
190 * callback associated with a button. | |
191 * | |
192 * @return A UI-specific handle. | |
193 */ | |
194 void *gaim_notify_searchresults(GaimConnection *gc, const char *title, | |
195 const char *primary, const char *secondary, | |
196 GaimNotifySearchResults *results, GaimNotifyCloseCallback cb, | |
197 gpointer user_data); | |
198 | |
199 void gaim_notify_searchresults_free(GaimNotifySearchResults *results); | |
200 | |
201 /** | |
202 * Replace old rows with the new. Reuse an existing window. | |
203 * | |
204 * @param gc The GaimConnection structure. | |
205 * @param results The GaimNotifySearchResults structure. | |
206 * @param data Data returned by the gaim_notify_searchresults(). | |
207 */ | |
208 void gaim_notify_searchresults_new_rows(GaimConnection *gc, | |
209 GaimNotifySearchResults *results, | |
210 void *data); | |
211 | |
212 | |
213 /** | |
214 * Adds a stock button that will be displayed in the search results dialog. | |
215 * | |
216 * @param results The search results object. | |
217 * @param type Type of the button. (TODO: Only one button of a given type can be displayed.) | |
218 * @param cb Function that will be called on the click event. | |
219 */ | |
220 void gaim_notify_searchresults_button_add(GaimNotifySearchResults *results, | |
221 GaimNotifySearchButtonType type, | |
222 GaimNotifySearchResultsCallback cb); | |
223 | |
224 | |
225 /** | |
226 * Adds a plain labelled button that will be displayed in the search results dialog. | |
227 * | |
228 * @param results The search results object | |
229 * @param label The label to display | |
230 * @param cb Function that will be called on the click event | |
231 */ | |
232 void gaim_notify_searchresults_button_add_labeled(GaimNotifySearchResults *results, | |
233 const char *label, | |
234 GaimNotifySearchResultsCallback cb); | |
235 | |
236 | |
237 /** | |
238 * Returns a newly created search results object. | |
239 * | |
240 * @return The new search results object. | |
241 */ | |
242 GaimNotifySearchResults *gaim_notify_searchresults_new(void); | |
243 | |
244 /** | |
245 * Returns a newly created search result column object. | |
246 * | |
247 * @param title Title of the column. NOTE: Title will get g_strdup()ed. | |
248 * | |
249 * @return The new search column object. | |
250 */ | |
251 GaimNotifySearchColumn *gaim_notify_searchresults_column_new(const char *title); | |
252 | |
253 /** | |
254 * Adds a new column to the search result object. | |
255 * | |
256 * @param results The result object to which the column will be added. | |
257 * @param column The column that will be added to the result object. | |
258 */ | |
259 void gaim_notify_searchresults_column_add(GaimNotifySearchResults *results, | |
260 GaimNotifySearchColumn *column); | |
261 | |
262 /** | |
263 * Adds a new row of the results to the search results object. | |
264 * | |
265 * @param results The search results object. | |
266 * @param row The row of the results. | |
267 */ | |
268 void gaim_notify_searchresults_row_add(GaimNotifySearchResults *results, | |
269 GList *row); | |
270 | |
271 /** | |
272 * Returns a number of the rows in the search results object. | |
273 * | |
274 * @param results The search results object. | |
275 * | |
276 * @return Number of the result rows. | |
277 */ | |
278 guint gaim_notify_searchresults_get_rows_count(GaimNotifySearchResults *results); | |
279 | |
280 /** | |
281 * Returns a number of the columns in the search results object. | |
282 * | |
283 * @param results The search results object. | |
284 * | |
285 * @return Number of the columns. | |
286 */ | |
287 guint gaim_notify_searchresults_get_columns_count(GaimNotifySearchResults *results); | |
288 | |
289 /** | |
290 * Returns a row of the results from the search results object. | |
291 * | |
292 * @param results The search results object. | |
293 * @param row_id Index of the row to be returned. | |
294 * | |
295 * @return Row of the results. | |
296 */ | |
297 GList *gaim_notify_searchresults_row_get(GaimNotifySearchResults *results, | |
298 unsigned int row_id); | |
299 | |
300 /** | |
301 * Returns a title of the search results object's column. | |
302 * | |
303 * @param results The search results object. | |
304 * @param column_id Index of the column. | |
305 * | |
306 * @return Title of the column. | |
307 */ | |
308 char *gaim_notify_searchresults_column_get_title(GaimNotifySearchResults *results, | |
309 unsigned int column_id); | |
310 | |
311 /*@}*/ | |
312 | |
313 /**************************************************************************/ | |
314 /** @name Notification API */ | |
315 /**************************************************************************/ | |
316 /*@{*/ | |
317 | |
318 /** | |
319 * Displays a notification message to the user. | |
320 * | |
321 * @param handle The plugin or connection handle. | |
322 * @param type The notification type. | |
323 * @param title The title of the message. | |
324 * @param primary The main point of the message. | |
325 * @param secondary The secondary information. | |
326 * @param cb The callback to call when the user closes | |
327 * the notification. | |
328 * @param user_data The data to pass to the callback. | |
329 * | |
330 * @return A UI-specific handle. | |
331 */ | |
332 void *gaim_notify_message(void *handle, GaimNotifyMsgType type, | |
333 const char *title, const char *primary, | |
334 const char *secondary, GaimNotifyCloseCallback cb, | |
335 gpointer user_data); | |
336 | |
337 /** | |
338 * Displays a single e-mail notification to the user. | |
339 * | |
340 * @param handle The plugin or connection handle. | |
341 * @param subject The subject of the e-mail. | |
342 * @param from The from address. | |
343 * @param to The destination address. | |
344 * @param url The URL where the message can be read. | |
345 * @param cb The callback to call when the user closes | |
346 * the notification. | |
347 * @param user_data The data to pass to the callback. | |
348 * | |
349 * @return A UI-specific handle. | |
350 */ | |
351 void *gaim_notify_email(void *handle, const char *subject, | |
352 const char *from, const char *to, | |
353 const char *url, GaimNotifyCloseCallback cb, | |
354 gpointer user_data); | |
355 | |
356 /** | |
357 * Displays a notification for multiple e-mails to the user. | |
358 * | |
359 * @param handle The plugin or connection handle. | |
360 * @param count The number of e-mails. | |
361 * @param detailed @c TRUE if there is information for each e-mail in the | |
362 * arrays. | |
363 * @param subjects The array of subjects. | |
364 * @param froms The array of from addresses. | |
365 * @param tos The array of destination addresses. | |
366 * @param urls The URLs where the messages can be read. | |
367 * @param cb The callback to call when the user closes | |
368 * the notification. | |
369 * @param user_data The data to pass to the callback. | |
370 * | |
371 * @return A UI-specific handle. | |
372 */ | |
373 void *gaim_notify_emails(void *handle, size_t count, gboolean detailed, | |
374 const char **subjects, const char **froms, | |
375 const char **tos, const char **urls, | |
376 GaimNotifyCloseCallback cb, gpointer user_data); | |
377 | |
378 /** | |
379 * Displays a notification with formatted text. | |
380 * | |
381 * The text is essentially a stripped-down format of HTML, the same that | |
382 * IMs may send. | |
383 * | |
384 * @param handle The plugin or connection handle. | |
385 * @param title The title of the message. | |
386 * @param primary The main point of the message. | |
387 * @param secondary The secondary information. | |
388 * @param text The formatted text. | |
389 * @param cb The callback to call when the user closes | |
390 * the notification. | |
391 * @param user_data The data to pass to the callback. | |
392 * | |
393 * @return A UI-specific handle. | |
394 */ | |
395 void *gaim_notify_formatted(void *handle, const char *title, | |
396 const char *primary, const char *secondary, | |
397 const char *text, GaimNotifyCloseCallback cb, gpointer user_data); | |
398 | |
399 /** | |
400 * Displays user information with formatted text, passing information giving | |
401 * the connection and username from which the user information came. | |
402 * | |
403 * The text is essentially a stripped-down format of HTML, the same that | |
404 * IMs may send. | |
405 * | |
406 * @param gc The GaimConnection handle associated with the information. | |
407 * @param who The username associated with the information. | |
408 * @param text The formatted text. | |
409 * @param cb The callback to call when the user closes | |
410 * the notification. | |
411 * @param user_data The data to pass to the callback. | |
412 * | |
413 * @return A UI-specific handle. | |
414 */ | |
415 void *gaim_notify_userinfo(GaimConnection *gc, const char *who, | |
416 const char *text, GaimNotifyCloseCallback cb, | |
417 gpointer user_data); | |
418 | |
419 /** | |
420 * Opens a URI or somehow presents it to the user. | |
421 * | |
422 * @param handle The plugin or connection handle. | |
423 * @param uri The URI to display or go to. | |
424 * | |
425 * @return A UI-specific handle, if any. This may only be presented if | |
426 * the UI code displays a dialog instead of a webpage, or something | |
427 * similar. | |
428 */ | |
429 void *gaim_notify_uri(void *handle, const char *uri); | |
430 | |
431 /** | |
432 * Closes a notification. | |
433 * | |
434 * This should be used only by the UI operation functions and part of the | |
435 * core. | |
436 * | |
437 * @param type The notification type. | |
438 * @param ui_handle The notification UI handle. | |
439 */ | |
440 void gaim_notify_close(GaimNotifyType type, void *ui_handle); | |
441 | |
442 /** | |
443 * Closes all notifications registered with the specified handle. | |
444 * | |
445 * @param handle The handle. | |
446 */ | |
447 void gaim_notify_close_with_handle(void *handle); | |
448 | |
449 /** | |
450 * A wrapper for gaim_notify_message that displays an information message. | |
451 */ | |
452 #define gaim_notify_info(handle, title, primary, secondary) \ | |
453 gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \ | |
454 (primary), (secondary), NULL, NULL) | |
455 | |
456 /** | |
457 * A wrapper for gaim_notify_message that displays a warning message. | |
458 */ | |
459 #define gaim_notify_warning(handle, title, primary, secondary) \ | |
460 gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \ | |
461 (primary), (secondary), NULL, NULL) | |
462 | |
463 /** | |
464 * A wrapper for gaim_notify_message that displays an error message. | |
465 */ | |
466 #define gaim_notify_error(handle, title, primary, secondary) \ | |
467 gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \ | |
468 (primary), (secondary), NULL, NULL) | |
469 | |
470 /*@}*/ | |
471 | |
472 /**************************************************************************/ | |
473 /** @name UI Registration Functions */ | |
474 /**************************************************************************/ | |
475 /*@{*/ | |
476 | |
477 /** | |
478 * Sets the UI operations structure to be used when displaying a | |
479 * notification. | |
480 * | |
481 * @param ops The UI operations structure. | |
482 */ | |
483 void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops); | |
484 | |
485 /** | |
486 * Returns the UI operations structure to be used when displaying a | |
487 * notification. | |
488 * | |
489 * @return The UI operations structure. | |
490 */ | |
491 GaimNotifyUiOps *gaim_notify_get_ui_ops(void); | |
492 | |
493 /*@}*/ | |
494 | |
495 /**************************************************************************/ | |
496 /** @name Notify Subsystem */ | |
497 /**************************************************************************/ | |
498 /*@{*/ | |
499 | |
500 /** | |
501 * Returns the notify subsystem handle. | |
502 * | |
503 * @return The notify subsystem handle. | |
504 */ | |
505 void *gaim_notify_get_handle(void); | |
506 | |
507 /** | |
508 * Initializes the notify subsystem. | |
509 */ | |
510 void gaim_notify_init(void); | |
511 | |
512 /** | |
513 * Uninitializes the notify subsystem. | |
514 */ | |
515 void gaim_notify_uninit(void); | |
516 | |
517 /*@}*/ | |
518 | |
519 | |
520 #ifdef __cplusplus | |
521 } | |
522 #endif | |
523 | |
524 #endif /* _GAIM_NOTIFY_H_ */ |