Mercurial > pidgin3 / file comparison

comparison: src/notify.h

src/notify.h

changeset 14253
b63ebf84c42b
parent 14252
d10dda2777a9
child 14254
77edc7a6191a
equal deleted inserted replaced
14252:d10dda2777a9 14253:b63ebf84c42b
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_ */

Mercurial Repository: pidgin3

mercurial