Mercurial > pidgin3 / file comparison

comparison: libgaim/request.h

libgaim/request.h

changeset 14254
77edc7a6191a
parent 14253
b63ebf84c42b
child 15356
a5ad506222a1
equal deleted inserted replaced
14253:b63ebf84c42b 14254:77edc7a6191a
1 /**
2 * @file request.h Request 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_REQUEST_H_
26 #define _GAIM_REQUEST_H_
27
28 #include <stdlib.h>
29 #include <glib-object.h>
30 #include <glib.h>
31
32 #include "account.h"
33
34 #define GAIM_DEFAULT_ACTION_NONE -1
35
36 /**
37 * Request types.
38 */
39 typedef enum
40 {
41 GAIM_REQUEST_INPUT = 0, /**< Text input request. */
42 GAIM_REQUEST_CHOICE, /**< Multiple-choice request. */
43 GAIM_REQUEST_ACTION, /**< Action request. */
44 GAIM_REQUEST_FIELDS, /**< Multiple fields request. */
45 GAIM_REQUEST_FILE, /**< File open or save request. */
46 GAIM_REQUEST_FOLDER /**< Folder selection request. */
47
48 } GaimRequestType;
49
50 /**
51 * A type of field.
52 */
53 typedef enum
54 {
55 GAIM_REQUEST_FIELD_NONE,
56 GAIM_REQUEST_FIELD_STRING,
57 GAIM_REQUEST_FIELD_INTEGER,
58 GAIM_REQUEST_FIELD_BOOLEAN,
59 GAIM_REQUEST_FIELD_CHOICE,
60 GAIM_REQUEST_FIELD_LIST,
61 GAIM_REQUEST_FIELD_LABEL,
62 GAIM_REQUEST_FIELD_IMAGE,
63 GAIM_REQUEST_FIELD_ACCOUNT
64
65 } GaimRequestFieldType;
66
67 /**
68 * Multiple fields request data.
69 */
70 typedef struct
71 {
72 GList *groups;
73
74 GHashTable *fields;
75
76 GList *required_fields;
77
78 void *ui_data;
79
80 } GaimRequestFields;
81
82 /**
83 * A group of fields with a title.
84 */
85 typedef struct
86 {
87 GaimRequestFields *fields_list;
88
89 char *title;
90
91 GList *fields;
92
93 } GaimRequestFieldGroup;
94
95 /**
96 * A request field.
97 */
98 typedef struct
99 {
100 GaimRequestFieldType type;
101 GaimRequestFieldGroup *group;
102
103 char *id;
104 char *label;
105 char *type_hint;
106
107 gboolean visible;
108 gboolean required;
109
110 union
111 {
112 struct
113 {
114 gboolean multiline;
115 gboolean masked;
116 gboolean editable;
117 char *default_value;
118 char *value;
119
120 } string;
121
122 struct
123 {
124 int default_value;
125 int value;
126
127 } integer;
128
129 struct
130 {
131 gboolean default_value;
132 gboolean value;
133
134 } boolean;
135
136 struct
137 {
138 int default_value;
139 int value;
140
141 GList *labels;
142
143 } choice;
144
145 struct
146 {
147 GList *items;
148 GHashTable *item_data;
149 GList *selected;
150 GHashTable *selected_table;
151
152 gboolean multiple_selection;
153
154 } list;
155
156 struct
157 {
158 GaimAccount *default_account;
159 GaimAccount *account;
160 gboolean show_all;
161
162 GaimFilterAccountFunc filter_func;
163
164 } account;
165
166 struct
167 {
168 unsigned int scale_x;
169 unsigned int scale_y;
170 const char *buffer;
171 gsize size;
172 } image;
173
174 } u;
175
176 void *ui_data;
177
178 } GaimRequestField;
179
180 /**
181 * Request UI operations.
182 */
183 typedef struct
184 {
185 void *(*request_input)(const char *title, const char *primary,
186 const char *secondary, const char *default_value,
187 gboolean multiline, gboolean masked, gchar *hint,
188 const char *ok_text, GCallback ok_cb,
189 const char *cancel_text, GCallback cancel_cb,
190 void *user_data);
191 void *(*request_choice)(const char *title, const char *primary,
192 const char *secondary, unsigned int default_value,
193 const char *ok_text, GCallback ok_cb,
194 const char *cancel_text, GCallback cancel_cb,
195 void *user_data, va_list choices);
196 void *(*request_action)(const char *title, const char *primary,
197 const char *secondary, unsigned int default_action,
198 void *user_data, size_t action_count,
199 va_list actions);
200 void *(*request_fields)(const char *title, const char *primary,
201 const char *secondary, GaimRequestFields *fields,
202 const char *ok_text, GCallback ok_cb,
203 const char *cancel_text, GCallback cancel_cb,
204 void *user_data);
205 void *(*request_file)(const char *title, const char *filename,
206 gboolean savedialog, GCallback ok_cb,
207 GCallback cancel_cb, void *user_data);
208 void (*close_request)(GaimRequestType type, void *ui_handle);
209 void *(*request_folder)(const char *title, const char *dirname,
210 GCallback ok_cb, GCallback cancel_cb,
211 void *user_data);
212 } GaimRequestUiOps;
213
214 typedef void (*GaimRequestInputCb)(void *, const char *);
215 typedef void (*GaimRequestActionCb)(void *, int);
216 typedef void (*GaimRequestChoiceCb)(void *, int);
217 typedef void (*GaimRequestFieldsCb)(void *, GaimRequestFields *fields);
218 typedef void (*GaimRequestFileCb)(void *, const char *filename);
219
220 #ifdef __cplusplus
221 extern "C" {
222 #endif
223
224 /**************************************************************************/
225 /** @name Field List API */
226 /**************************************************************************/
227 /*@{*/
228
229 /**
230 * Creates a list of fields to pass to gaim_request_fields().
231 *
232 * @return A GaimRequestFields structure.
233 */
234 GaimRequestFields *gaim_request_fields_new(void);
235
236 /**
237 * Destroys a list of fields.
238 *
239 * @param fields The list of fields to destroy.
240 */
241 void gaim_request_fields_destroy(GaimRequestFields *fields);
242
243 /**
244 * Adds a group of fields to the list.
245 *
246 * @param fields The fields list.
247 * @param group The group to add.
248 */
249 void gaim_request_fields_add_group(GaimRequestFields *fields,
250 GaimRequestFieldGroup *group);
251
252 /**
253 * Returns a list of all groups in a field list.
254 *
255 * @param fields The fields list.
256 *
257 * @return A list of groups.
258 */
259 GList *gaim_request_fields_get_groups(const GaimRequestFields *fields);
260
261 /**
262 * Returns whether or not the field with the specified ID exists.
263 *
264 * @param fields The fields list.
265 * @param id The ID of the field.
266 *
267 * @return TRUE if the field exists, or FALSE.
268 */
269 gboolean gaim_request_fields_exists(const GaimRequestFields *fields,
270 const char *id);
271
272 /**
273 * Returns a list of all required fields.
274 *
275 * @param fields The fields list.
276 *
277 * @return The list of required fields.
278 */
279 const GList *gaim_request_fields_get_required(const GaimRequestFields *fields);
280
281 /**
282 * Returns whether or not a field with the specified ID is required.
283 *
284 * @param fields The fields list.
285 * @param id The field ID.
286 *
287 * @return TRUE if the specified field is required, or FALSE.
288 */
289 gboolean gaim_request_fields_is_field_required(const GaimRequestFields *fields,
290 const char *id);
291
292 /**
293 * Returns whether or not all required fields have values.
294 *
295 * @param fields The fields list.
296 *
297 * @return TRUE if all required fields have values, or FALSE.
298 */
299 gboolean gaim_request_fields_all_required_filled(
300 const GaimRequestFields *fields);
301
302 /**
303 * Return the field with the specified ID.
304 *
305 * @param fields The fields list.
306 * @param id The ID of the field.
307 *
308 * @return The field, if found.
309 */
310 GaimRequestField *gaim_request_fields_get_field(
311 const GaimRequestFields *fields, const char *id);
312
313 /**
314 * Returns the string value of a field with the specified ID.
315 *
316 * @param fields The fields list.
317 * @param id The ID of the field.
318 *
319 * @return The string value, if found, or @c NULL otherwise.
320 */
321 const char *gaim_request_fields_get_string(const GaimRequestFields *fields,
322 const char *id);
323
324 /**
325 * Returns the integer value of a field with the specified ID.
326 *
327 * @param fields The fields list.
328 * @param id The ID of the field.
329 *
330 * @return The integer value, if found, or 0 otherwise.
331 */
332 int gaim_request_fields_get_integer(const GaimRequestFields *fields,
333 const char *id);
334
335 /**
336 * Returns the boolean value of a field with the specified ID.
337 *
338 * @param fields The fields list.
339 * @param id The ID of the field.
340 *
341 * @return The boolean value, if found, or @c FALSE otherwise.
342 */
343 gboolean gaim_request_fields_get_bool(const GaimRequestFields *fields,
344 const char *id);
345
346 /**
347 * Returns the choice index of a field with the specified ID.
348 *
349 * @param fields The fields list.
350 * @param id The ID of the field.
351 *
352 * @return The choice index, if found, or -1 otherwise.
353 */
354 int gaim_request_fields_get_choice(const GaimRequestFields *fields,
355 const char *id);
356
357 /**
358 * Returns the account of a field with the specified ID.
359 *
360 * @param fields The fields list.
361 * @param id The ID of the field.
362 *
363 * @return The account value, if found, or NULL otherwise.
364 */
365 GaimAccount *gaim_request_fields_get_account(const GaimRequestFields *fields,
366 const char *id);
367
368 /*@}*/
369
370 /**************************************************************************/
371 /** @name Fields Group API */
372 /**************************************************************************/
373 /*@{*/
374
375 /**
376 * Creates a fields group with an optional title.
377 *
378 * @param title The optional title to give the group.
379 *
380 * @return A new fields group
381 */
382 GaimRequestFieldGroup *gaim_request_field_group_new(const char *title);
383
384 /**
385 * Destroys a fields group.
386 *
387 * @param group The group to destroy.
388 */
389 void gaim_request_field_group_destroy(GaimRequestFieldGroup *group);
390
391 /**
392 * Adds a field to the group.
393 *
394 * @param group The group to add the field to.
395 * @param field The field to add to the group.
396 */
397 void gaim_request_field_group_add_field(GaimRequestFieldGroup *group,
398 GaimRequestField *field);
399
400 /**
401 * Returns the title of a fields group.
402 *
403 * @param group The group.
404 *
405 * @return The title, if set.
406 */
407 const char *gaim_request_field_group_get_title(
408 const GaimRequestFieldGroup *group);
409
410 /**
411 * Returns a list of all fields in a group.
412 *
413 * @param group The group.
414 *
415 * @return The list of fields in the group.
416 */
417 GList *gaim_request_field_group_get_fields(
418 const GaimRequestFieldGroup *group);
419
420 /*@}*/
421
422 /**************************************************************************/
423 /** @name Field API */
424 /**************************************************************************/
425 /*@{*/
426
427 /**
428 * Creates a field of the specified type.
429 *
430 * @param id The field ID.
431 * @param text The text label of the field.
432 * @param type The type of field.
433 *
434 * @return The new field.
435 */
436 GaimRequestField *gaim_request_field_new(const char *id, const char *text,
437 GaimRequestFieldType type);
438
439 /**
440 * Destroys a field.
441 *
442 * @param field The field to destroy.
443 */
444 void gaim_request_field_destroy(GaimRequestField *field);
445
446 /**
447 * Sets the label text of a field.
448 *
449 * @param field The field.
450 * @param label The text label.
451 */
452 void gaim_request_field_set_label(GaimRequestField *field, const char *label);
453
454 /**
455 * Sets whether or not a field is visible.
456 *
457 * @param field The field.
458 * @param visible TRUE if visible, or FALSE if not.
459 */
460 void gaim_request_field_set_visible(GaimRequestField *field, gboolean visible);
461
462 /**
463 * Sets the type hint for the field.
464 *
465 * This is optionally used by the UIs to provide such features as
466 * auto-completion for type hints like "account" and "screenname".
467 *
468 * @param field The field.
469 * @param type_hint The type hint.
470 */
471 void gaim_request_field_set_type_hint(GaimRequestField *field,
472 const char *type_hint);
473
474 /**
475 * Sets whether or not a field is required.
476 *
477 * @param field The field.
478 * @param required TRUE if required, or FALSE.
479 */
480 void gaim_request_field_set_required(GaimRequestField *field,
481 gboolean required);
482
483 /**
484 * Returns the type of a field.
485 *
486 * @param field The field.
487 *
488 * @return The field's type.
489 */
490 GaimRequestFieldType gaim_request_field_get_type(const GaimRequestField *field);
491
492 /**
493 * Returns the ID of a field.
494 *
495 * @param field The field.
496 *
497 * @return The ID
498 */
499 const char *gaim_request_field_get_id(const GaimRequestField *field);
500
501 /**
502 * Returns the label text of a field.
503 *
504 * @param field The field.
505 *
506 * @return The label text.
507 */
508 const char *gaim_request_field_get_label(const GaimRequestField *field);
509
510 /**
511 * Returns whether or not a field is visible.
512 *
513 * @param field The field.
514 *
515 * @return TRUE if the field is visible. FALSE otherwise.
516 */
517 gboolean gaim_request_field_is_visible(const GaimRequestField *field);
518
519 /**
520 * Returns the field's type hint.
521 *
522 * @param field The field.
523 *
524 * @return The field's type hint.
525 */
526 const char *gaim_request_field_get_type_hint(const GaimRequestField *field);
527
528 /**
529 * Returns whether or not a field is required.
530 *
531 * @param field The field.
532 *
533 * @return TRUE if the field is required, or FALSE.
534 */
535 gboolean gaim_request_field_is_required(const GaimRequestField *field);
536
537 /*@}*/
538
539 /**************************************************************************/
540 /** @name String Field API */
541 /**************************************************************************/
542 /*@{*/
543
544 /**
545 * Creates a string request field.
546 *
547 * @param id The field ID.
548 * @param text The text label of the field.
549 * @param default_value The optional default value.
550 * @param multiline Whether or not this should be a multiline string.
551 *
552 * @return The new field.
553 */
554 GaimRequestField *gaim_request_field_string_new(const char *id,
555 const char *text,
556 const char *default_value,
557 gboolean multiline);
558
559 /**
560 * Sets the default value in a string field.
561 *
562 * @param field The field.
563 * @param default_value The default value.
564 */
565 void gaim_request_field_string_set_default_value(GaimRequestField *field,
566 const char *default_value);
567
568 /**
569 * Sets the value in a string field.
570 *
571 * @param field The field.
572 * @param value The value.
573 */
574 void gaim_request_field_string_set_value(GaimRequestField *field,
575 const char *value);
576
577 /**
578 * Sets whether or not a string field is masked
579 * (commonly used for password fields).
580 *
581 * @param field The field.
582 * @param masked The masked value.
583 */
584 void gaim_request_field_string_set_masked(GaimRequestField *field,
585 gboolean masked);
586
587 /**
588 * Sets whether or not a string field is editable.
589 *
590 * @param field The field.
591 * @param editable The editable value.
592 */
593 void gaim_request_field_string_set_editable(GaimRequestField *field,
594 gboolean editable);
595
596 /**
597 * Returns the default value in a string field.
598 *
599 * @param field The field.
600 *
601 * @return The default value.
602 */
603 const char *gaim_request_field_string_get_default_value(
604 const GaimRequestField *field);
605
606 /**
607 * Returns the user-entered value in a string field.
608 *
609 * @param field The field.
610 *
611 * @return The value.
612 */
613 const char *gaim_request_field_string_get_value(const GaimRequestField *field);
614
615 /**
616 * Returns whether or not a string field is multi-line.
617 *
618 * @param field The field.
619 *
620 * @return @c TRUE if the field is mulit-line, or @c FALSE otherwise.
621 */
622 gboolean gaim_request_field_string_is_multiline(const GaimRequestField *field);
623
624 /**
625 * Returns whether or not a string field is masked.
626 *
627 * @param field The field.
628 *
629 * @return @c TRUE if the field is masked, or @c FALSE otherwise.
630 */
631 gboolean gaim_request_field_string_is_masked(const GaimRequestField *field);
632
633 /**
634 * Returns whether or not a string field is editable.
635 *
636 * @param field The field.
637 *
638 * @return @c TRUE if the field is editable, or @c FALSE otherwise.
639 */
640 gboolean gaim_request_field_string_is_editable(const GaimRequestField *field);
641
642 /*@}*/
643
644 /**************************************************************************/
645 /** @name Integer Field API */
646 /**************************************************************************/
647 /*@{*/
648
649 /**
650 * Creates an integer field.
651 *
652 * @param id The field ID.
653 * @param text The text label of the field.
654 * @param default_value The default value.
655 *
656 * @return The new field.
657 */
658 GaimRequestField *gaim_request_field_int_new(const char *id,
659 const char *text,
660 int default_value);
661
662 /**
663 * Sets the default value in an integer field.
664 *
665 * @param field The field.
666 * @param default_value The default value.
667 */
668 void gaim_request_field_int_set_default_value(GaimRequestField *field,
669 int default_value);
670
671 /**
672 * Sets the value in an integer field.
673 *
674 * @param field The field.
675 * @param value The value.
676 */
677 void gaim_request_field_int_set_value(GaimRequestField *field, int value);
678
679 /**
680 * Returns the default value in an integer field.
681 *
682 * @param field The field.
683 *
684 * @return The default value.
685 */
686 int gaim_request_field_int_get_default_value(const GaimRequestField *field);
687
688 /**
689 * Returns the user-entered value in an integer field.
690 *
691 * @param field The field.
692 *
693 * @return The value.
694 */
695 int gaim_request_field_int_get_value(const GaimRequestField *field);
696
697 /*@}*/
698
699 /**************************************************************************/
700 /** @name Boolean Field API */
701 /**************************************************************************/
702 /*@{*/
703
704 /**
705 * Creates a boolean field.
706 *
707 * This is often represented as a checkbox.
708 *
709 * @param id The field ID.
710 * @param text The text label of the field.
711 * @param default_value The default value.
712 *
713 * @return The new field.
714 */
715 GaimRequestField *gaim_request_field_bool_new(const char *id,
716 const char *text,
717 gboolean default_value);
718
719 /**
720 * Sets the default value in an boolean field.
721 *
722 * @param field The field.
723 * @param default_value The default value.
724 */
725 void gaim_request_field_bool_set_default_value(GaimRequestField *field,
726 gboolean default_value);
727
728 /**
729 * Sets the value in an boolean field.
730 *
731 * @param field The field.
732 * @param value The value.
733 */
734 void gaim_request_field_bool_set_value(GaimRequestField *field,
735 gboolean value);
736
737 /**
738 * Returns the default value in an boolean field.
739 *
740 * @param field The field.
741 *
742 * @return The default value.
743 */
744 gboolean gaim_request_field_bool_get_default_value(
745 const GaimRequestField *field);
746
747 /**
748 * Returns the user-entered value in an boolean field.
749 *
750 * @param field The field.
751 *
752 * @return The value.
753 */
754 gboolean gaim_request_field_bool_get_value(const GaimRequestField *field);
755
756 /*@}*/
757
758 /**************************************************************************/
759 /** @name Choice Field API */
760 /**************************************************************************/
761 /*@{*/
762
763 /**
764 * Creates a multiple choice field.
765 *
766 * This is often represented as a group of radio buttons.
767 *
768 * @param id The field ID.
769 * @param text The optional label of the field.
770 * @param default_value The default choice.
771 *
772 * @return The new field.
773 */
774 GaimRequestField *gaim_request_field_choice_new(const char *id,
775 const char *text,
776 int default_value);
777
778 /**
779 * Adds a choice to a multiple choice field.
780 *
781 * @param field The choice field.
782 * @param label The choice label.
783 */
784 void gaim_request_field_choice_add(GaimRequestField *field,
785 const char *label);
786
787 /**
788 * Sets the default value in an choice field.
789 *
790 * @param field The field.
791 * @param default_value The default value.
792 */
793 void gaim_request_field_choice_set_default_value(GaimRequestField *field,
794 int default_value);
795
796 /**
797 * Sets the value in an choice field.
798 *
799 * @param field The field.
800 * @param value The value.
801 */
802 void gaim_request_field_choice_set_value(GaimRequestField *field, int value);
803
804 /**
805 * Returns the default value in an choice field.
806 *
807 * @param field The field.
808 *
809 * @return The default value.
810 */
811 int gaim_request_field_choice_get_default_value(const GaimRequestField *field);
812
813 /**
814 * Returns the user-entered value in an choice field.
815 *
816 * @param field The field.
817 *
818 * @return The value.
819 */
820 int gaim_request_field_choice_get_value(const GaimRequestField *field);
821
822 /**
823 * Returns a list of labels in a choice field.
824 *
825 * @param field The field.
826 *
827 * @return The list of labels.
828 */
829 GList *gaim_request_field_choice_get_labels(const GaimRequestField *field);
830
831 /*@}*/
832
833 /**************************************************************************/
834 /** @name List Field API */
835 /**************************************************************************/
836 /*@{*/
837
838 /**
839 * Creates a multiple list item field.
840 *
841 * @param id The field ID.
842 * @param text The optional label of the field.
843 *
844 * @return The new field.
845 */
846 GaimRequestField *gaim_request_field_list_new(const char *id, const char *text);
847
848 /**
849 * Sets whether or not a list field allows multiple selection.
850 *
851 * @param field The list field.
852 * @param multi_select TRUE if multiple selection is enabled,
853 * or FALSE otherwise.
854 */
855 void gaim_request_field_list_set_multi_select(GaimRequestField *field,
856 gboolean multi_select);
857
858 /**
859 * Returns whether or not a list field allows multiple selection.
860 *
861 * @param field The list field.
862 *
863 * @return TRUE if multiple selection is enabled, or FALSE otherwise.
864 */
865 gboolean gaim_request_field_list_get_multi_select(
866 const GaimRequestField *field);
867
868 /**
869 * Returns the data for a particular item.
870 *
871 * @param field The list field.
872 * @param text The item text.
873 *
874 * @return The data associated with the item.
875 */
876 void *gaim_request_field_list_get_data(const GaimRequestField *field,
877 const char *text);
878
879 /**
880 * Adds an item to a list field.
881 *
882 * @param field The list field.
883 * @param item The list item.
884 * @param data The associated data.
885 */
886 void gaim_request_field_list_add(GaimRequestField *field,
887 const char *item, void *data);
888
889 /**
890 * Adds a selected item to the list field.
891 *
892 * @param field The field.
893 * @param item The item to add.
894 */
895 void gaim_request_field_list_add_selected(GaimRequestField *field,
896 const char *item);
897
898 /**
899 * Clears the list of selected items in a list field.
900 *
901 * @param field The field.
902 */
903 void gaim_request_field_list_clear_selected(GaimRequestField *field);
904
905 /**
906 * Sets a list of selected items in a list field.
907 *
908 * @param field The field.
909 * @param items The list of selected items.
910 */
911 void gaim_request_field_list_set_selected(GaimRequestField *field,
912 const GList *items);
913
914 /**
915 * Returns whether or not a particular item is selected in a list field.
916 *
917 * @param field The field.
918 * @param item The item.
919 *
920 * @return TRUE if the item is selected. FALSE otherwise.
921 */
922 gboolean gaim_request_field_list_is_selected(const GaimRequestField *field,
923 const char *item);
924
925 /**
926 * Returns a list of selected items in a list field.
927 *
928 * To retrieve the data for each item, use
929 * gaim_request_field_list_get_data().
930 *
931 * @param field The field.
932 *
933 * @return The list of selected items.
934 */
935 const GList *gaim_request_field_list_get_selected(
936 const GaimRequestField *field);
937
938 /**
939 * Returns a list of items in a list field.
940 *
941 * @param field The field.
942 *
943 * @return The list of items.
944 */
945 const GList *gaim_request_field_list_get_items(const GaimRequestField *field);
946
947 /*@}*/
948
949 /**************************************************************************/
950 /** @name Label Field API */
951 /**************************************************************************/
952 /*@{*/
953
954 /**
955 * Creates a label field.
956 *
957 * @param id The field ID.
958 * @param text The label of the field.
959 *
960 * @return The new field.
961 */
962 GaimRequestField *gaim_request_field_label_new(const char *id,
963 const char *text);
964
965 /*@}*/
966
967 /**************************************************************************/
968 /** @name Image Field API */
969 /**************************************************************************/
970 /*@{*/
971
972 /**
973 * Creates an image field.
974 *
975 * @param id The field ID.
976 * @param text The label of the field.
977 * @param buf The image data.
978 * @param size The size of the data in @a buffer.
979 *
980 * @return The new field.
981 */
982 GaimRequestField *gaim_request_field_image_new(const char *id, const char *text,
983 const char *buf, gsize size);
984
985 /**
986 * Sets the scale factors of an image field.
987 *
988 * @param field The image field.
989 * @param x The x scale factor.
990 * @param y The y scale factor.
991 */
992 void gaim_request_field_image_set_scale(GaimRequestField *field, unsigned int x, unsigned int y);
993
994 /**
995 * Returns pointer to the image.
996 *
997 * @param field The image field.
998 *
999 * @return Pointer to the image.
1000 */
1001 const char *gaim_request_field_image_get_buffer(GaimRequestField *field);
1002
1003 /**
1004 * Returns size (in bytes) of the image.
1005 *
1006 * @param field The image field.
1007 *
1008 * @return Size of the image.
1009 */
1010 gsize gaim_request_field_image_get_size(GaimRequestField *field);
1011
1012 /**
1013 * Returns X scale coefficient of the image.
1014 *
1015 * @param field The image field.
1016 *
1017 * @return X scale coefficient of the image.
1018 */
1019 unsigned int gaim_request_field_image_get_scale_x(GaimRequestField *field);
1020
1021 /**
1022 * Returns Y scale coefficient of the image.
1023 *
1024 * @param field The image field.
1025 *
1026 * @return Y scale coefficient of the image.
1027 */
1028 unsigned int gaim_request_field_image_get_scale_y(GaimRequestField *field);
1029
1030 /*@}*/
1031
1032 /**************************************************************************/
1033 /** @name Account Field API */
1034 /**************************************************************************/
1035 /*@{*/
1036
1037 /**
1038 * Creates an account field.
1039 *
1040 * By default, this field will not show offline accounts.
1041 *
1042 * @param id The field ID.
1043 * @param text The text label of the field.
1044 * @param account The optional default account.
1045 *
1046 * @return The new field.
1047 */
1048 GaimRequestField *gaim_request_field_account_new(const char *id,
1049 const char *text,
1050 GaimAccount *account);
1051
1052 /**
1053 * Sets the default account on an account field.
1054 *
1055 * @param field The account field.
1056 * @param default_value The default account.
1057 */
1058 void gaim_request_field_account_set_default_value(GaimRequestField *field,
1059 GaimAccount *default_value);
1060
1061 /**
1062 * Sets the account in an account field.
1063 *
1064 * @param field The account field.
1065 * @param value The account.
1066 */
1067 void gaim_request_field_account_set_value(GaimRequestField *field,
1068 GaimAccount *value);
1069
1070 /**
1071 * Sets whether or not to show all accounts in an account field.
1072 *
1073 * If TRUE, all accounts, online or offline, will be shown. If FALSE,
1074 * only online accounts will be shown.
1075 *
1076 * @param field The account field.
1077 * @param show_all Whether or not to show all accounts.
1078 */
1079 void gaim_request_field_account_set_show_all(GaimRequestField *field,
1080 gboolean show_all);
1081
1082 /**
1083 * Sets the account filter function in an account field.
1084 *
1085 * This function will determine which accounts get displayed and which
1086 * don't.
1087 *
1088 * @param field The account field.
1089 * @param filter_func The account filter function.
1090 */
1091 void gaim_request_field_account_set_filter(GaimRequestField *field,
1092 GaimFilterAccountFunc filter_func);
1093
1094 /**
1095 * Returns the default account in an account field.
1096 *
1097 * @param field The field.
1098 *
1099 * @return The default account.
1100 */
1101 GaimAccount *gaim_request_field_account_get_default_value(
1102 const GaimRequestField *field);
1103
1104 /**
1105 * Returns the user-entered account in an account field.
1106 *
1107 * @param field The field.
1108 *
1109 * @return The user-entered account.
1110 */
1111 GaimAccount *gaim_request_field_account_get_value(
1112 const GaimRequestField *field);
1113
1114 /**
1115 * Returns whether or not to show all accounts in an account field.
1116 *
1117 * If TRUE, all accounts, online or offline, will be shown. If FALSE,
1118 * only online accounts will be shown.
1119 *
1120 * @param field The account field.
1121 * @return Whether or not to show all accounts.
1122 */
1123 gboolean gaim_request_field_account_get_show_all(
1124 const GaimRequestField *field);
1125
1126 /**
1127 * Returns the account filter function in an account field.
1128 *
1129 * This function will determine which accounts get displayed and which
1130 * don't.
1131 *
1132 * @param field The account field.
1133 *
1134 * @return The account filter function.
1135 */
1136 GaimFilterAccountFunc gaim_request_field_account_get_filter(
1137 const GaimRequestField *field);
1138
1139 /*@}*/
1140
1141 /**************************************************************************/
1142 /** @name Request API */
1143 /**************************************************************************/
1144 /*@{*/
1145
1146 /**
1147 * Prompts the user for text input.
1148 *
1149 * @param handle The plugin or connection handle. For some
1150 * things this is EXTREMELY important. The
1151 * handle is used to programmatically close
1152 * the request dialog when it is no longer
1153 * needed. For PRPLs this is often a pointer
1154 * to the GaimConnection instance. For plugins
1155 * this should be a similar, unique memory
1156 * location. This value is important because
1157 * it allows a request to be closed, say, when
1158 * you sign offline. If the request is NOT
1159 * closed it is VERY likely to cause a crash
1160 * whenever the callback handler functions are
1161 * triggered.
1162 * @param title The title of the message.
1163 * @param primary The main point of the message.
1164 * @param secondary The secondary information.
1165 * @param default_value The default value.
1166 * @param multiline TRUE if the inputted text can span multiple lines.
1167 * @param masked TRUE if the inputted text should be masked in some way.
1168 * @param hint Optionally suggest how the input box should appear.
1169 * Use "html," for example, to allow the user to enter
1170 * HTML.
1171 * @param ok_text The text for the @c OK button.
1172 * @param ok_cb The callback for the @c OK button.
1173 * @param cancel_text The text for the @c Cancel button.
1174 * @param cancel_cb The callback for the @c Cancel button.
1175 * @param user_data The data to pass to the callback.
1176 *
1177 * @return A UI-specific handle.
1178 */
1179 void *gaim_request_input(void *handle, const char *title,
1180 const char *primary, const char *secondary,
1181 const char *default_value,
1182 gboolean multiline, gboolean masked, gchar *hint,
1183 const char *ok_text, GCallback ok_cb,
1184 const char *cancel_text, GCallback cancel_cb,
1185 void *user_data);
1186
1187 /**
1188 * Prompts the user for multiple-choice input.
1189 *
1190 * @param handle The plugin or connection handle. For some
1191 * things this is EXTREMELY important. See
1192 * the comments on gaim_request_input.
1193 * @param title The title of the message.
1194 * @param primary The main point of the message.
1195 * @param secondary The secondary information.
1196 * @param default_value The default value.
1197 * @param ok_text The text for the @c OK button.
1198 * @param ok_cb The callback for the @c OK button.
1199 * @param cancel_text The text for the @c Cancel button.
1200 * @param cancel_cb The callback for the @c Cancel button.
1201 * @param user_data The data to pass to the callback.
1202 * @param ... The choices. This argument list should be
1203 * terminated with a NULL parameter.
1204 *
1205 * @return A UI-specific handle.
1206 */
1207 void *gaim_request_choice(void *handle, const char *title,
1208 const char *primary, const char *secondary,
1209 unsigned int default_value,
1210 const char *ok_text, GCallback ok_cb,
1211 const char *cancel_text, GCallback cancel_cb,
1212 void *user_data, ...);
1213
1214 /**
1215 * Prompts the user for multiple-choice input.
1216 *
1217 * @param handle The plugin or connection handle. For some
1218 * things this is EXTREMELY important. See
1219 * the comments on gaim_request_input.
1220 * @param title The title of the message.
1221 * @param primary The main point of the message.
1222 * @param secondary The secondary information.
1223 * @param default_value The default value.
1224 * @param ok_text The text for the @c OK button.
1225 * @param ok_cb The callback for the @c OK button.
1226 * @param cancel_text The text for the @c Cancel button.
1227 * @param cancel_cb The callback for the @c Cancel button.
1228 * @param user_data The data to pass to the callback.
1229 * @param choices The choices. This argument list should be
1230 * terminated with a @c NULL parameter.
1231 *
1232 * @return A UI-specific handle.
1233 */
1234 void *gaim_request_choice_varg(void *handle, const char *title,
1235 const char *primary, const char *secondary,
1236 unsigned int default_value,
1237 const char *ok_text, GCallback ok_cb,
1238 const char *cancel_text, GCallback cancel_cb,
1239 void *user_data, va_list choices);
1240
1241 /**
1242 * Prompts the user for an action.
1243 *
1244 * This is often represented as a dialog with a button for each action.
1245 *
1246 * @param handle The plugin or connection handle. For some
1247 * things this is EXTREMELY important. See
1248 * the comments on gaim_request_input.
1249 * @param title The title of the message.
1250 * @param primary The main point of the message.
1251 * @param secondary The secondary information.
1252 * @param default_action The default value.
1253 * @param user_data The data to pass to the callback.
1254 * @param action_count The number of actions.
1255 * @param ... A list of actions.
1256 *
1257 * @return A UI-specific handle.
1258 */
1259 void *gaim_request_action(void *handle, const char *title,
1260 const char *primary, const char *secondary,
1261 unsigned int default_action,
1262 void *user_data, size_t action_count, ...);
1263
1264 /**
1265 * Prompts the user for an action.
1266 *
1267 * This is often represented as a dialog with a button for each action.
1268 *
1269 * @param handle The plugin or connection handle. For some
1270 * things this is EXTREMELY important. See
1271 * the comments on gaim_request_input.
1272 * @param title The title of the message.
1273 * @param primary The main point of the message.
1274 * @param secondary The secondary information.
1275 * @param default_action The default value.
1276 * @param user_data The data to pass to the callback.
1277 * @param action_count The number of actions.
1278 * @param actions A list of actions and callbacks.
1279 *
1280 * @return A UI-specific handle.
1281 */
1282 void *gaim_request_action_varg(void *handle, const char *title,
1283 const char *primary, const char *secondary,
1284 unsigned int default_action,
1285 void *user_data, size_t action_count,
1286 va_list actions);
1287
1288 /**
1289 * Displays groups of fields for the user to fill in.
1290 *
1291 * @param handle The plugin or connection handle. For some
1292 * things this is EXTREMELY important. See
1293 * the comments on gaim_request_input.
1294 * @param title The title of the message.
1295 * @param primary The main point of the message.
1296 * @param secondary The secondary information.
1297 * @param fields The list of fields.
1298 * @param ok_text The text for the @c OK button.
1299 * @param ok_cb The callback for the @c OK button.
1300 * @param cancel_text The text for the @c Cancel button.
1301 * @param cancel_cb The callback for the @c Cancel button.
1302 * @param user_data The data to pass to the callback.
1303 *
1304 * @return A UI-specific handle.
1305 */
1306 void *gaim_request_fields(void *handle, const char *title,
1307 const char *primary, const char *secondary,
1308 GaimRequestFields *fields,
1309 const char *ok_text, GCallback ok_cb,
1310 const char *cancel_text, GCallback cancel_cb,
1311 void *user_data);
1312
1313 /**
1314 * Closes a request.
1315 *
1316 * @param type The request type.
1317 * @param uihandle The request UI handle.
1318 */
1319 void gaim_request_close(GaimRequestType type, void *uihandle);
1320
1321 /**
1322 * Closes all requests registered with the specified handle.
1323 *
1324 * @param handle The handle.
1325 */
1326 void gaim_request_close_with_handle(void *handle);
1327
1328 /**
1329 * A wrapper for gaim_request_action() that uses @c Yes and @c No buttons.
1330 */
1331 #define gaim_request_yes_no(handle, title, primary, secondary, \
1332 default_action, user_data, yes_cb, no_cb) \
1333 gaim_request_action((handle), (title), (primary), (secondary), \
1334 (default_action), (user_data), 2, \
1335 _("Yes"), (yes_cb), _("No"), (no_cb))
1336
1337 /**
1338 * A wrapper for gaim_request_action() that uses @c OK and @c Cancel buttons.
1339 */
1340 #define gaim_request_ok_cancel(handle, title, primary, secondary, \
1341 default_action, user_data, ok_cb, cancel_cb) \
1342 gaim_request_action((handle), (title), (primary), (secondary), \
1343 (default_action), (user_data), 2, \
1344 _("OK"), (ok_cb), _("Cancel"), (cancel_cb))
1345
1346 /**
1347 * A wrapper for gaim_request_action() that uses Accept and Cancel buttons.
1348 */
1349 #define gaim_request_accept_cancel(handle, title, primary, secondary, \
1350 default_action, user_data, accept_cb, \
1351 cancel_cb) \
1352 gaim_request_action((handle), (title), (primary), (secondary), \
1353 (default_action), (user_data), 2, \
1354 _("_Accept"), (accept_cb), _("Cancel"), (cancel_cb))
1355
1356 /**
1357 * Displays a file selector request dialog. Returns the selected filename to
1358 * the callback. Can be used for either opening a file or saving a file.
1359 *
1360 * @param handle The plugin or connection handle. For some
1361 * things this is EXTREMELY important. See
1362 * the comments on gaim_request_input.
1363 * @param title The title for the dialog (may be @c NULL)
1364 * @param filename The default filename (may be @c NULL)
1365 * @param savedialog True if this dialog is being used to save a file.
1366 * False if it is being used to open a file.
1367 * @param ok_cb The callback for the @c OK button.
1368 * @param cancel_cb The callback for the @c Cancel button.
1369 * @param user_data The data to pass to the callback.
1370 *
1371 * @return A UI-specific handle.
1372 */
1373 void *gaim_request_file(void *handle, const char *title, const char *filename,
1374 gboolean savedialog,
1375 GCallback ok_cb, GCallback cancel_cb,
1376 void *user_data);
1377
1378 /**
1379 * Displays a folder select dialog. Returns the selected filename to
1380 * the callback.
1381 *
1382 * @param handle The plugin or connection handle. For some
1383 * things this is EXTREMELY important. See
1384 * the comments on gaim_request_input.
1385 * @param title The title for the dialog (may be @c NULL)
1386 * @param dirname The default directory name (may be @c NULL)
1387 * @param ok_cb The callback for the @c OK button.
1388 * @param cancel_cb The callback for the @c Cancel button.
1389 * @param user_data The data to pass to the callback.
1390 *
1391 * @return A UI-specific handle.
1392 */
1393 void *gaim_request_folder(void *handle, const char *title, const char *dirname,
1394 GCallback ok_cb, GCallback cancel_cb,
1395 void *user_data);
1396
1397 /*@}*/
1398
1399 /**************************************************************************/
1400 /** @name UI Registration Functions */
1401 /**************************************************************************/
1402 /*@{*/
1403
1404 /**
1405 * Sets the UI operations structure to be used when displaying a
1406 * request.
1407 *
1408 * @param ops The UI operations structure.
1409 */
1410 void gaim_request_set_ui_ops(GaimRequestUiOps *ops);
1411
1412 /**
1413 * Returns the UI operations structure to be used when displaying a
1414 * request.
1415 *
1416 * @return The UI operations structure.
1417 */
1418 GaimRequestUiOps *gaim_request_get_ui_ops(void);
1419
1420 /*@}*/
1421
1422 #ifdef __cplusplus
1423 }
1424 #endif
1425
1426 #endif /* _GAIM_REQUEST_H_ */

Mercurial Repository: pidgin3

mercurial