Mercurial > pidgin.yaz

comparison libpurple/notify.h @ 15374:5fe8042783c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
author Sean Egan <seanegan@gmail.com>
date Sat, 20 Jan 2007 02:32:10 +0000
parents
children 32c366eeeb99
comparison
equal deleted inserted replaced
15373:f79e0f4df793 15374:5fe8042783c1
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 typedef struct _GaimNotifyUserInfoEntry GaimNotifyUserInfoEntry;
33 typedef struct _GaimNotifyUserInfo GaimNotifyUserInfo;
34
35 #include "connection.h"
36
37 /**
38 * Notification close callbacks.
39 */
40 typedef void (*GaimNotifyCloseCallback) (gpointer user_data);
41
42
43 /**
44 * Notification types.
45 */
46 typedef enum
47 {
48 GAIM_NOTIFY_MESSAGE = 0, /**< Message notification. */
49 GAIM_NOTIFY_EMAIL, /**< Single e-mail notification. */
50 GAIM_NOTIFY_EMAILS, /**< Multiple e-mail notification. */
51 GAIM_NOTIFY_FORMATTED, /**< Formatted text. */
52 GAIM_NOTIFY_SEARCHRESULTS, /**< Buddy search results. */
53 GAIM_NOTIFY_USERINFO, /**< Formatted userinfo text. */
54 GAIM_NOTIFY_URI /**< URI notification or display. */
55
56 } GaimNotifyType;
57
58
59 /**
60 * Notification message types.
61 */
62 typedef enum
63 {
64 GAIM_NOTIFY_MSG_ERROR = 0, /**< Error notification. */
65 GAIM_NOTIFY_MSG_WARNING, /**< Warning notification. */
66 GAIM_NOTIFY_MSG_INFO /**< Information notification. */
67
68 } GaimNotifyMsgType;
69
70
71 /**
72 * The types of buttons
73 */
74 typedef enum
75 {
76 GAIM_NOTIFY_BUTTON_LABELED = 0, /**< special use, see _button_add_labeled */
77 GAIM_NOTIFY_BUTTON_CONTINUE = 1,
78 GAIM_NOTIFY_BUTTON_ADD,
79 GAIM_NOTIFY_BUTTON_INFO,
80 GAIM_NOTIFY_BUTTON_IM,
81 GAIM_NOTIFY_BUTTON_JOIN,
82 GAIM_NOTIFY_BUTTON_INVITE
83 } GaimNotifySearchButtonType;
84
85
86 /**
87 * Search results object.
88 */
89 typedef struct
90 {
91 GList *columns; /**< List of the search column objects. */
92 GList *rows; /**< List of rows in the result. */
93 GList *buttons; /**< List of buttons to display. */
94
95 } GaimNotifySearchResults;
96
97 /**
98 * Types of GaimNotifyUserInfoEntry objects
99 */
100 typedef enum
101 {
102 GAIM_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
103 GAIM_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
104 GAIM_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
105 } GaimNotifyUserInfoEntryType;
106
107 /**
108 * Single column of a search result.
109 */
110 typedef struct
111 {
112 char *title; /**< Title of the column. */
113
114 } GaimNotifySearchColumn;
115
116
117 /**
118 * Callback for a button in a search result.
119 *
120 * @param c the GaimConnection passed to gaim_notify_searchresults
121 * @param row the contents of the selected row
122 * @param user_data User defined data.
123 */
124 typedef void (*GaimNotifySearchResultsCallback)(GaimConnection *c, GList *row,
125 gpointer user_data);
126
127
128 /**
129 * Definition of a button.
130 */
131 typedef struct
132 {
133 GaimNotifySearchButtonType type;
134 GaimNotifySearchResultsCallback callback; /**< Function to be called when clicked. */
135 char *label; /**< only for GAIM_NOTIFY_BUTTON_LABELED */
136 } GaimNotifySearchButton;
137
138
139 /**
140 * Notification UI operations.
141 */
142 typedef struct
143 {
144 void *(*notify_message)(GaimNotifyMsgType type, const char *title,
145 const char *primary, const char *secondary);
146
147 void *(*notify_email)(GaimConnection *gc,
148 const char *subject, const char *from,
149 const char *to, const char *url);
150
151 void *(*notify_emails)(GaimConnection *gc,
152 size_t count, gboolean detailed,
153 const char **subjects, const char **froms,
154 const char **tos, const char **urls);
155
156 void *(*notify_formatted)(const char *title, const char *primary,
157 const char *secondary, const char *text);
158
159 void *(*notify_searchresults)(GaimConnection *gc, const char *title,
160 const char *primary, const char *secondary,
161 GaimNotifySearchResults *results, gpointer user_data);
162
163 void (*notify_searchresults_new_rows)(GaimConnection *gc,
164 GaimNotifySearchResults *results,
165 void *data);
166
167 void *(*notify_userinfo)(GaimConnection *gc, const char *who,
168 GaimNotifyUserInfo *user_info);
169
170 void *(*notify_uri)(const char *uri);
171
172 void (*close_notify)(GaimNotifyType type, void *ui_handle);
173
174 } GaimNotifyUiOps;
175
176
177 #ifdef __cplusplus
178 extern "C" {
179 #endif
180
181
182 /**************************************************************************/
183 /** Search results notification API */
184 /**************************************************************************/
185 /*@{*/
186
187 /**
188 * Displays results from a buddy search. This can be, for example,
189 * a window with a list of all found buddies, where you are given the
190 * option of adding buddies to your buddy list.
191 *
192 * @param gc The GaimConnection handle associated with the information.
193 * @param title The title of the message. If this is NULL, the title
194 * will be "Search Results."
195 * @param primary The main point of the message.
196 * @param secondary The secondary information.
197 * @param results The GaimNotifySearchResults instance.
198 * @param cb The callback to call when the user closes
199 * the notification.
200 * @param user_data The data to pass to the close callback and any other
201 * callback associated with a button.
202 *
203 * @return A UI-specific handle.
204 */
205 void *gaim_notify_searchresults(GaimConnection *gc, const char *title,
206 const char *primary, const char *secondary,
207 GaimNotifySearchResults *results, GaimNotifyCloseCallback cb,
208 gpointer user_data);
209
210 void gaim_notify_searchresults_free(GaimNotifySearchResults *results);
211
212 /**
213 * Replace old rows with the new. Reuse an existing window.
214 *
215 * @param gc The GaimConnection structure.
216 * @param results The GaimNotifySearchResults structure.
217 * @param data Data returned by the gaim_notify_searchresults().
218 */
219 void gaim_notify_searchresults_new_rows(GaimConnection *gc,
220 GaimNotifySearchResults *results,
221 void *data);
222
223
224 /**
225 * Adds a stock button that will be displayed in the search results dialog.
226 *
227 * @param results The search results object.
228 * @param type Type of the button. (TODO: Only one button of a given type can be displayed.)
229 * @param cb Function that will be called on the click event.
230 */
231 void gaim_notify_searchresults_button_add(GaimNotifySearchResults *results,
232 GaimNotifySearchButtonType type,
233 GaimNotifySearchResultsCallback cb);
234
235
236 /**
237 * Adds a plain labelled button that will be displayed in the search results dialog.
238 *
239 * @param results The search results object
240 * @param label The label to display
241 * @param cb Function that will be called on the click event
242 */
243 void gaim_notify_searchresults_button_add_labeled(GaimNotifySearchResults *results,
244 const char *label,
245 GaimNotifySearchResultsCallback cb);
246
247
248 /**
249 * Returns a newly created search results object.
250 *
251 * @return The new search results object.
252 */
253 GaimNotifySearchResults *gaim_notify_searchresults_new(void);
254
255 /**
256 * Returns a newly created search result column object.
257 *
258 * @param title Title of the column. NOTE: Title will get g_strdup()ed.
259 *
260 * @return The new search column object.
261 */
262 GaimNotifySearchColumn *gaim_notify_searchresults_column_new(const char *title);
263
264 /**
265 * Adds a new column to the search result object.
266 *
267 * @param results The result object to which the column will be added.
268 * @param column The column that will be added to the result object.
269 */
270 void gaim_notify_searchresults_column_add(GaimNotifySearchResults *results,
271 GaimNotifySearchColumn *column);
272
273 /**
274 * Adds a new row of the results to the search results object.
275 *
276 * @param results The search results object.
277 * @param row The row of the results.
278 */
279 void gaim_notify_searchresults_row_add(GaimNotifySearchResults *results,
280 GList *row);
281
282 /**
283 * Returns a number of the rows in the search results object.
284 *
285 * @param results The search results object.
286 *
287 * @return Number of the result rows.
288 */
289 guint gaim_notify_searchresults_get_rows_count(GaimNotifySearchResults *results);
290
291 /**
292 * Returns a number of the columns in the search results object.
293 *
294 * @param results The search results object.
295 *
296 * @return Number of the columns.
297 */
298 guint gaim_notify_searchresults_get_columns_count(GaimNotifySearchResults *results);
299
300 /**
301 * Returns a row of the results from the search results object.
302 *
303 * @param results The search results object.
304 * @param row_id Index of the row to be returned.
305 *
306 * @return Row of the results.
307 */
308 GList *gaim_notify_searchresults_row_get(GaimNotifySearchResults *results,
309 unsigned int row_id);
310
311 /**
312 * Returns a title of the search results object's column.
313 *
314 * @param results The search results object.
315 * @param column_id Index of the column.
316 *
317 * @return Title of the column.
318 */
319 char *gaim_notify_searchresults_column_get_title(GaimNotifySearchResults *results,
320 unsigned int column_id);
321
322 /*@}*/
323
324 /**************************************************************************/
325 /** @name Notification API */
326 /**************************************************************************/
327 /*@{*/
328
329 /**
330 * Displays a notification message to the user.
331 *
332 * @param handle The plugin or connection handle.
333 * @param type The notification type.
334 * @param title The title of the message.
335 * @param primary The main point of the message.
336 * @param secondary The secondary information.
337 * @param cb The callback to call when the user closes
338 * the notification.
339 * @param user_data The data to pass to the callback.
340 *
341 * @return A UI-specific handle.
342 */
343 void *gaim_notify_message(void *handle, GaimNotifyMsgType type,
344 const char *title, const char *primary,
345 const char *secondary, GaimNotifyCloseCallback cb,
346 gpointer user_data);
347
348 /**
349 * Displays a single e-mail notification to the user.
350 *
351 * @param handle The plugin or connection handle.
352 * @param subject The subject of the e-mail.
353 * @param from The from address.
354 * @param to The destination address.
355 * @param url The URL where the message can be read.
356 * @param cb The callback to call when the user closes
357 * the notification.
358 * @param user_data The data to pass to the callback.
359 *
360 * @return A UI-specific handle.
361 */
362 void *gaim_notify_email(void *handle, const char *subject,
363 const char *from, const char *to,
364 const char *url, GaimNotifyCloseCallback cb,
365 gpointer user_data);
366
367 /**
368 * Displays a notification for multiple e-mails to the user.
369 *
370 * @param handle The plugin or connection handle.
371 * @param count The number of e-mails.
372 * @param detailed @c TRUE if there is information for each e-mail in the
373 * arrays.
374 * @param subjects The array of subjects.
375 * @param froms The array of from addresses.
376 * @param tos The array of destination addresses.
377 * @param urls The URLs where the messages can be read.
378 * @param cb The callback to call when the user closes
379 * the notification.
380 * @param user_data The data to pass to the callback.
381 *
382 * @return A UI-specific handle.
383 */
384 void *gaim_notify_emails(void *handle, size_t count, gboolean detailed,
385 const char **subjects, const char **froms,
386 const char **tos, const char **urls,
387 GaimNotifyCloseCallback cb, gpointer user_data);
388
389 /**
390 * Displays a notification with formatted text.
391 *
392 * The text is essentially a stripped-down format of HTML, the same that
393 * IMs may send.
394 *
395 * @param handle The plugin or connection handle.
396 * @param title The title of the message.
397 * @param primary The main point of the message.
398 * @param secondary The secondary information.
399 * @param text The formatted text.
400 * @param cb The callback to call when the user closes
401 * the notification.
402 * @param user_data The data to pass to the callback.
403 *
404 * @return A UI-specific handle.
405 */
406 void *gaim_notify_formatted(void *handle, const char *title,
407 const char *primary, const char *secondary,
408 const char *text, GaimNotifyCloseCallback cb, gpointer user_data);
409
410 /**
411 * Displays user information with formatted text, passing information giving
412 * the connection and username from which the user information came.
413 *
414 * The text is essentially a stripped-down format of HTML, the same that
415 * IMs may send.
416 *
417 * @param gc The GaimConnection handle associated with the information.
418 * @param who The username associated with the information.
419 * @param user_info The GaimNotifyUserInfo which contains the information
420 * @param cb The callback to call when the user closes
421 * the notification.
422 * @param user_data The data to pass to the callback.
423 *
424 * @return A UI-specific handle.
425 */
426 void *gaim_notify_userinfo(GaimConnection *gc, const char *who,
427 GaimNotifyUserInfo *user_info, GaimNotifyCloseCallback cb,
428 gpointer user_data);
429
430 /**
431 * Create a new GaimNotifyUserInfo which is suitable for passing to gaim_notify_userinfo()
432 *
433 * @return A new GaimNotifyUserInfo, which the caller must destroy when done
434 */
435 GaimNotifyUserInfo *gaim_notify_user_info_new(void);
436
437 /**
438 * Destroy a GaimNotifyUserInfo
439 *
440 * @param user_info The GaimNotifyUserInfo
441 */
442 void gaim_notify_user_info_destroy(GaimNotifyUserInfo *user_info);
443
444 /**
445 * Retrieve the array of GaimNotifyUserInfoEntry objects from a GaimNotifyUserInfo
446 *
447 * This GList may be manipulated directly with normal GList functions such as g_list_insert(). Only
448 * GaimNotifyUserInfoEntry are allowed in the list. If a GaimNotifyUserInfoEntry item is added to the list,
449 * it should not be g_free()'d by the caller; GaimNotifyUserInfo will g_free it when destroyed.
450 *
451 * To remove a GaimNotifyUserInfoEntry, use gaim_notify_user_info_remove_entry(). Do not use the GList directly.
452 *
453 * @param user_info The GaimNotifyUserInfo
454 *
455 * @result A GList of GaimNotifyUserInfoEntry objects
456 */
457 GList *gaim_notify_user_info_get_entries(GaimNotifyUserInfo *user_info);
458
459 /**
460 * Create a textual representation of a GaimNotifyUserInfo, separating entries with newline
461 *
462 * @param user_info The GaimNotifyUserInfo
463 * @param newline The separation character
464 */
465 char *gaim_notify_user_info_get_text_with_newline(GaimNotifyUserInfo *user_info, const char *newline);
466
467 /**
468 * Add a label/value pair to a GaimNotifyUserInfo object.
469 * GaimNotifyUserInfo keeps track of the order in which pairs are added.
470 *
471 * @param user_info The GaimNotifyUserInfo
472 * @param label A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
473 * If NULL, value will be displayed without a label.
474 * @param value The value, which might be displayed by a UI after the label.
475 * If NULL, label will still be displayed; the UI should then treat label as independent
476 * and not include a colon if it would otherwise.
477 */
478 void gaim_notify_user_info_add_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);
479
480 /**
481 * Prepend a label/value pair to a GaimNotifyUserInfo object
482 *
483 * @param user_info The GaimNotifyUserInfo
484 * @param label A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
485 * If NULL, value will be displayed without a label.
486 * @param value The value, which might be displayed by a UI after the label.
487 * If NULL, label will still be displayed; the UI should then treat label as independent
488 * and not include a colon if it would otherwise.
489 */
490 void gaim_notify_user_info_prepend_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);
491
492 /**
493 * Remove a GaimNotifyUserInfoEntry from a GaimNotifyUserInfo object
494 *
495 * @param user_info The GaimNotifyUserInfo
496 * @param user_info_entry The GaimNotifyUserInfoEntry
497 */
498 void gaim_notify_user_info_remove_entry(GaimNotifyUserInfo *user_info, GaimNotifyUserInfoEntry *user_info_entry);
499 /**
500 * Create a new GaimNotifyUserInfoEntry
501 *
502 * If added to a GaimNotifyUserInfo object, this should not be free()'d, as GaimNotifyUserInfo will do so
503 * when destroyed. gaim_notify_user_info_add_pair() and gaim_notify_user_info_prepend_pair() are convenience
504 * methods for creating entries and adding them to a GaimNotifyUserInfo.
505 *
506 * @param label A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
507 * If NULL, value will be displayed without a label.
508 * @param value The value, which might be displayed by a UI after the label.
509 * If NULL, label will still be displayed; the UI should then treat label as independent
510 * and not include a colon if it would otherwise.
511 *
512 * @result A new GaimNotifyUserInfoEntry
513 */
514 GaimNotifyUserInfoEntry *gaim_notify_user_info_entry_new(const char *label, const char *value);
515
516 /**
517 * Add a section break. A UI might display this as a horizontal line.
518 *
519 * @param user_info The GaimNotifyUserInfo
520 */
521 void gaim_notify_user_info_add_section_break(GaimNotifyUserInfo *user_info);
522
523 /**
524 * Add a section header. A UI might display this in a different font from other text.
525 *
526 * @param user_info The GaimNotifyUserInfo
527 * @param label The name of the section
528 */
529 void gaim_notify_user_info_add_section_header(GaimNotifyUserInfo *user_info, const char *label);
530
531 /**
532 * Remove the last item which was added to a GaimNotifyUserInfo. This could be used to remove a section header which is not needed.
533 */
534 void gaim_notify_user_info_remove_last_item(GaimNotifyUserInfo *user_info);
535
536 /**
537 * Get the label for a GaimNotifyUserInfoEntry
538 *
539 * @param user_info_entry The GaimNotifyUserInfoEntry
540 *
541 * @result The label
542 */
543 gchar *gaim_notify_user_info_entry_get_label(GaimNotifyUserInfoEntry *user_info_entry);
544
545 /**
546 * Set the label for a GaimNotifyUserInfoEntry
547 *
548 * @param user_info_entry The GaimNotifyUserInfoEntry
549 * @param label The label
550 */
551 void gaim_notify_user_info_entry_set_label(GaimNotifyUserInfoEntry *user_info_entry, const char *label);
552
553 /**
554 * Get the value for a GaimNotifyUserInfoEntry
555 *
556 * @param user_info_entry The GaimNotifyUserInfoEntry
557 *
558 * @result The value
559 */
560 gchar *gaim_notify_user_info_entry_get_value(GaimNotifyUserInfoEntry *user_info_entry);
561
562 /**
563 * Set the value for a GaimNotifyUserInfoEntry
564 *
565 * @param user_info_entry The GaimNotifyUserInfoEntry
566 * @param value The value
567 */
568 void gaim_notify_user_info_entry_set_value(GaimNotifyUserInfoEntry *user_info_entry, const char *value);
569
570
571 /**
572 * Get the type of a GaimNotifyUserInfoEntry
573 *
574 * @param user_info_entry The GaimNotifyUserInfoEntry
575 *
576 * @result The GaimNotifyUserInfoEntryType
577 */
578 GaimNotifyUserInfoEntryType gaim_notify_user_info_entry_get_type(GaimNotifyUserInfoEntry *user_info_entry);
579
580 /**
581 * Set the type of a GaimNotifyUserInfoEntry
582 *
583 * @param user_info_entry The GaimNotifyUserInfoEntry
584 * @param The GaimNotifyUserInfoEntryType
585 */
586 void gaim_notify_user_info_entry_set_type(GaimNotifyUserInfoEntry *user_info_entry,
587 GaimNotifyUserInfoEntryType type);
588
589 /**
590 * Opens a URI or somehow presents it to the user.
591 *
592 * @param handle The plugin or connection handle.
593 * @param uri The URI to display or go to.
594 *
595 * @return A UI-specific handle, if any. This may only be presented if
596 * the UI code displays a dialog instead of a webpage, or something
597 * similar.
598 */
599 void *gaim_notify_uri(void *handle, const char *uri);
600
601 /**
602 * Closes a notification.
603 *
604 * This should be used only by the UI operation functions and part of the
605 * core.
606 *
607 * @param type The notification type.
608 * @param ui_handle The notification UI handle.
609 */
610 void gaim_notify_close(GaimNotifyType type, void *ui_handle);
611
612 /**
613 * Closes all notifications registered with the specified handle.
614 *
615 * @param handle The handle.
616 */
617 void gaim_notify_close_with_handle(void *handle);
618
619 /**
620 * A wrapper for gaim_notify_message that displays an information message.
621 */
622 #define gaim_notify_info(handle, title, primary, secondary) \
623 gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \
624 (primary), (secondary), NULL, NULL)
625
626 /**
627 * A wrapper for gaim_notify_message that displays a warning message.
628 */
629 #define gaim_notify_warning(handle, title, primary, secondary) \
630 gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \
631 (primary), (secondary), NULL, NULL)
632
633 /**
634 * A wrapper for gaim_notify_message that displays an error message.
635 */
636 #define gaim_notify_error(handle, title, primary, secondary) \
637 gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \
638 (primary), (secondary), NULL, NULL)
639
640 /*@}*/
641
642 /**************************************************************************/
643 /** @name UI Registration Functions */
644 /**************************************************************************/
645 /*@{*/
646
647 /**
648 * Sets the UI operations structure to be used when displaying a
649 * notification.
650 *
651 * @param ops The UI operations structure.
652 */
653 void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops);
654
655 /**
656 * Returns the UI operations structure to be used when displaying a
657 * notification.
658 *
659 * @return The UI operations structure.
660 */
661 GaimNotifyUiOps *gaim_notify_get_ui_ops(void);
662
663 /*@}*/
664
665 /**************************************************************************/
666 /** @name Notify Subsystem */
667 /**************************************************************************/
668 /*@{*/
669
670 /**
671 * Returns the notify subsystem handle.
672 *
673 * @return The notify subsystem handle.
674 */
675 void *gaim_notify_get_handle(void);
676
677 /**
678 * Initializes the notify subsystem.
679 */
680 void gaim_notify_init(void);
681
682 /**
683 * Uninitializes the notify subsystem.
684 */
685 void gaim_notify_uninit(void);
686
687 /*@}*/
688
689
690 #ifdef __cplusplus
691 }
692 #endif
693
694 #endif /* _GAIM_NOTIFY_H_ */