request.h

Go to the documentation of this file.
00001 
00006 /* purple
00007  *
00008  * Purple is the legal property of its developers, whose names are too numerous
00009  * to list here.  Please refer to the COPYRIGHT file distributed with this
00010  * source distribution.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
00025  */
00026 #ifndef _PURPLE_REQUEST_H_
00027 #define _PURPLE_REQUEST_H_
00028 
00029 #include <stdlib.h>
00030 #include <glib-object.h>
00031 #include <glib.h>
00032 
00034 typedef struct _PurpleRequestField PurpleRequestField;
00035 
00036 #include "account.h"
00037 
00038 #define PURPLE_DEFAULT_ACTION_NONE  -1
00039 
00043 typedef enum
00044 {
00045     PURPLE_REQUEST_INPUT = 0,  
00046     PURPLE_REQUEST_CHOICE,     
00047     PURPLE_REQUEST_ACTION,     
00048     PURPLE_REQUEST_FIELDS,     
00049     PURPLE_REQUEST_FILE,       
00050     PURPLE_REQUEST_FOLDER      
00052 } PurpleRequestType;
00053 
00057 typedef enum
00058 {
00059     PURPLE_REQUEST_FIELD_NONE,
00060     PURPLE_REQUEST_FIELD_STRING,
00061     PURPLE_REQUEST_FIELD_INTEGER,
00062     PURPLE_REQUEST_FIELD_BOOLEAN,
00063     PURPLE_REQUEST_FIELD_CHOICE,
00064     PURPLE_REQUEST_FIELD_LIST,
00065     PURPLE_REQUEST_FIELD_LABEL,
00066     PURPLE_REQUEST_FIELD_IMAGE,
00067     PURPLE_REQUEST_FIELD_ACCOUNT
00068 
00069 } PurpleRequestFieldType;
00070 
00074 typedef struct
00075 {
00076     GList *groups;
00077 
00078     GHashTable *fields;
00079 
00080     GList *required_fields;
00081 
00082     void *ui_data;
00083 
00084 } PurpleRequestFields;
00085 
00089 typedef struct
00090 {
00091     PurpleRequestFields *fields_list;
00092 
00093     char *title;
00094 
00095     GList *fields;
00096 
00097 } PurpleRequestFieldGroup;
00098 
00099 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_REQUEST_C_)
00100 
00103 struct _PurpleRequestField
00104 {
00105     PurpleRequestFieldType type;
00106     PurpleRequestFieldGroup *group;
00107 
00108     char *id;
00109     char *label;
00110     char *type_hint;
00111 
00112     gboolean visible;
00113     gboolean required;
00114 
00115     union
00116     {
00117         struct
00118         {
00119             gboolean multiline;
00120             gboolean masked;
00121             gboolean editable;
00122             char *default_value;
00123             char *value;
00124 
00125         } string;
00126 
00127         struct
00128         {
00129             int default_value;
00130             int value;
00131 
00132         } integer;
00133 
00134         struct
00135         {
00136             gboolean default_value;
00137             gboolean value;
00138 
00139         } boolean;
00140 
00141         struct
00142         {
00143             int default_value;
00144             int value;
00145 
00146             GList *labels;
00147 
00148         } choice;
00149 
00150         struct
00151         {
00152             GList *items;
00153             GList *icons;
00154             GHashTable *item_data;
00155             GList *selected;
00156             GHashTable *selected_table;
00157 
00158             gboolean multiple_selection;
00159 
00160         } list;
00161 
00162         struct
00163         {
00164             PurpleAccount *default_account;
00165             PurpleAccount *account;
00166             gboolean show_all;
00167 
00168             PurpleFilterAccountFunc filter_func;
00169 
00170         } account;
00171 
00172         struct
00173         {
00174             unsigned int scale_x;
00175             unsigned int scale_y;
00176             const char *buffer;
00177             gsize size;
00178         } image;
00179 
00180     } u;
00181 
00182     void *ui_data;
00183 
00184 };
00185 #endif
00186 
00190 typedef struct
00191 {
00193     void *(*request_input)(const char *title, const char *primary,
00194                            const char *secondary, const char *default_value,
00195                            gboolean multiline, gboolean masked, gchar *hint,
00196                            const char *ok_text, GCallback ok_cb,
00197                            const char *cancel_text, GCallback cancel_cb,
00198                            PurpleAccount *account, const char *who,
00199                            PurpleConversation *conv, void *user_data);
00200 
00202     void *(*request_choice)(const char *title, const char *primary,
00203                             const char *secondary, int default_value,
00204                             const char *ok_text, GCallback ok_cb,
00205                             const char *cancel_text, GCallback cancel_cb,
00206                             PurpleAccount *account, const char *who,
00207                             PurpleConversation *conv, void *user_data,
00208                             va_list choices);
00209 
00211     void *(*request_action)(const char *title, const char *primary,
00212                             const char *secondary, int default_action,
00213                             PurpleAccount *account, const char *who,
00214                             PurpleConversation *conv, void *user_data,
00215                             size_t action_count, va_list actions);
00216 
00218     void *(*request_fields)(const char *title, const char *primary,
00219                             const char *secondary, PurpleRequestFields *fields,
00220                             const char *ok_text, GCallback ok_cb,
00221                             const char *cancel_text, GCallback cancel_cb,
00222                             PurpleAccount *account, const char *who,
00223                             PurpleConversation *conv, void *user_data);
00224 
00226     void *(*request_file)(const char *title, const char *filename,
00227                           gboolean savedialog, GCallback ok_cb,
00228                           GCallback cancel_cb, PurpleAccount *account,
00229                           const char *who, PurpleConversation *conv,
00230                           void *user_data);
00231 
00232     void (*close_request)(PurpleRequestType type, void *ui_handle);
00233 
00235     void *(*request_folder)(const char *title, const char *dirname,
00236                             GCallback ok_cb, GCallback cancel_cb,
00237                             PurpleAccount *account, const char *who,
00238                             PurpleConversation *conv, void *user_data);
00239 
00241     void *(*request_action_with_icon)(const char *title, const char *primary,
00242                             const char *secondary, int default_action,
00243                             PurpleAccount *account, const char *who,
00244                             PurpleConversation *conv, 
00245                             gconstpointer icon_data, gsize icon_size,
00246                             void *user_data,
00247                             size_t action_count, va_list actions);
00248 
00249     void (*_purple_reserved1)(void);
00250     void (*_purple_reserved2)(void);
00251     void (*_purple_reserved3)(void);
00252 } PurpleRequestUiOps;
00253 
00254 typedef void (*PurpleRequestInputCb)(void *, const char *);
00255 
00260 typedef void (*PurpleRequestActionCb)(void *, int);
00261 typedef void (*PurpleRequestChoiceCb)(void *, int);
00262 typedef void (*PurpleRequestFieldsCb)(void *, PurpleRequestFields *fields);
00263 typedef void (*PurpleRequestFileCb)(void *, const char *filename);
00264 
00265 #ifdef __cplusplus
00266 extern "C" {
00267 #endif
00268 
00269 /**************************************************************************/
00271 /**************************************************************************/
00279 PurpleRequestFields *purple_request_fields_new(void);
00280 
00286 void purple_request_fields_destroy(PurpleRequestFields *fields);
00287 
00294 void purple_request_fields_add_group(PurpleRequestFields *fields,
00295                                    PurpleRequestFieldGroup *group);
00296 
00304 GList *purple_request_fields_get_groups(const PurpleRequestFields *fields);
00305 
00314 gboolean purple_request_fields_exists(const PurpleRequestFields *fields,
00315                                     const char *id);
00316 
00324 GList *purple_request_fields_get_required(const PurpleRequestFields *fields);
00325 
00334 gboolean purple_request_fields_is_field_required(const PurpleRequestFields *fields,
00335                                                const char *id);
00336 
00344 gboolean purple_request_fields_all_required_filled(
00345     const PurpleRequestFields *fields);
00346 
00355 PurpleRequestField *purple_request_fields_get_field(
00356         const PurpleRequestFields *fields, const char *id);
00357 
00366 const char *purple_request_fields_get_string(const PurpleRequestFields *fields,
00367                                            const char *id);
00368 
00377 int purple_request_fields_get_integer(const PurpleRequestFields *fields,
00378                                     const char *id);
00379 
00388 gboolean purple_request_fields_get_bool(const PurpleRequestFields *fields,
00389                                       const char *id);
00390 
00399 int purple_request_fields_get_choice(const PurpleRequestFields *fields,
00400                                    const char *id);
00401 
00410 PurpleAccount *purple_request_fields_get_account(const PurpleRequestFields *fields,
00411                                              const char *id);
00412 
00415 /**************************************************************************/
00417 /**************************************************************************/
00427 PurpleRequestFieldGroup *purple_request_field_group_new(const char *title);
00428 
00434 void purple_request_field_group_destroy(PurpleRequestFieldGroup *group);
00435 
00442 void purple_request_field_group_add_field(PurpleRequestFieldGroup *group,
00443                                         PurpleRequestField *field);
00444 
00452 const char *purple_request_field_group_get_title(
00453         const PurpleRequestFieldGroup *group);
00454 
00462 GList *purple_request_field_group_get_fields(
00463         const PurpleRequestFieldGroup *group);
00464 
00467 /**************************************************************************/
00469 /**************************************************************************/
00481 PurpleRequestField *purple_request_field_new(const char *id, const char *text,
00482                                          PurpleRequestFieldType type);
00483 
00489 void purple_request_field_destroy(PurpleRequestField *field);
00490 
00497 void purple_request_field_set_label(PurpleRequestField *field, const char *label);
00498 
00505 void purple_request_field_set_visible(PurpleRequestField *field, gboolean visible);
00506 
00516 void purple_request_field_set_type_hint(PurpleRequestField *field,
00517                                       const char *type_hint);
00518 
00525 void purple_request_field_set_required(PurpleRequestField *field,
00526                                      gboolean required);
00527 
00535 PurpleRequestFieldType purple_request_field_get_type(const PurpleRequestField *field);
00536 
00546 PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field);
00547 
00555 const char *purple_request_field_get_id(const PurpleRequestField *field);
00556 
00564 const char *purple_request_field_get_label(const PurpleRequestField *field);
00565 
00573 gboolean purple_request_field_is_visible(const PurpleRequestField *field);
00574 
00582 const char *purple_request_field_get_type_hint(const PurpleRequestField *field);
00583 
00591 gboolean purple_request_field_is_required(const PurpleRequestField *field);
00592 
00602 gpointer purple_request_field_get_ui_data(const PurpleRequestField *field);
00603 
00614 void purple_request_field_set_ui_data(PurpleRequestField *field,
00615                                       gpointer ui_data);
00616 
00619 /**************************************************************************/
00621 /**************************************************************************/
00634 PurpleRequestField *purple_request_field_string_new(const char *id,
00635                                                 const char *text,
00636                                                 const char *default_value,
00637                                                 gboolean multiline);
00638 
00645 void purple_request_field_string_set_default_value(PurpleRequestField *field,
00646                                                  const char *default_value);
00647 
00654 void purple_request_field_string_set_value(PurpleRequestField *field,
00655                                          const char *value);
00656 
00664 void purple_request_field_string_set_masked(PurpleRequestField *field,
00665                                           gboolean masked);
00666 
00673 void purple_request_field_string_set_editable(PurpleRequestField *field,
00674                                             gboolean editable);
00675 
00683 const char *purple_request_field_string_get_default_value(
00684         const PurpleRequestField *field);
00685 
00693 const char *purple_request_field_string_get_value(const PurpleRequestField *field);
00694 
00702 gboolean purple_request_field_string_is_multiline(const PurpleRequestField *field);
00703 
00711 gboolean purple_request_field_string_is_masked(const PurpleRequestField *field);
00712 
00720 gboolean purple_request_field_string_is_editable(const PurpleRequestField *field);
00721 
00724 /**************************************************************************/
00726 /**************************************************************************/
00738 PurpleRequestField *purple_request_field_int_new(const char *id,
00739                                              const char *text,
00740                                              int default_value);
00741 
00748 void purple_request_field_int_set_default_value(PurpleRequestField *field,
00749                                               int default_value);
00750 
00757 void purple_request_field_int_set_value(PurpleRequestField *field, int value);
00758 
00766 int purple_request_field_int_get_default_value(const PurpleRequestField *field);
00767 
00775 int purple_request_field_int_get_value(const PurpleRequestField *field);
00776 
00779 /**************************************************************************/
00781 /**************************************************************************/
00795 PurpleRequestField *purple_request_field_bool_new(const char *id,
00796                                               const char *text,
00797                                               gboolean default_value);
00798 
00805 void purple_request_field_bool_set_default_value(PurpleRequestField *field,
00806                                                gboolean default_value);
00807 
00814 void purple_request_field_bool_set_value(PurpleRequestField *field,
00815                                        gboolean value);
00816 
00824 gboolean purple_request_field_bool_get_default_value(
00825         const PurpleRequestField *field);
00826 
00834 gboolean purple_request_field_bool_get_value(const PurpleRequestField *field);
00835 
00838 /**************************************************************************/
00840 /**************************************************************************/
00854 PurpleRequestField *purple_request_field_choice_new(const char *id,
00855                                                 const char *text,
00856                                                 int default_value);
00857 
00864 void purple_request_field_choice_add(PurpleRequestField *field,
00865                                    const char *label);
00866 
00873 void purple_request_field_choice_set_default_value(PurpleRequestField *field,
00874                                                  int default_value);
00875 
00882 void purple_request_field_choice_set_value(PurpleRequestField *field, int value);
00883 
00891 int purple_request_field_choice_get_default_value(const PurpleRequestField *field);
00892 
00900 int purple_request_field_choice_get_value(const PurpleRequestField *field);
00901 
00909 GList *purple_request_field_choice_get_labels(const PurpleRequestField *field);
00910 
00913 /**************************************************************************/
00915 /**************************************************************************/
00926 PurpleRequestField *purple_request_field_list_new(const char *id, const char *text);
00927 
00935 void purple_request_field_list_set_multi_select(PurpleRequestField *field,
00936                                               gboolean multi_select);
00937 
00945 gboolean purple_request_field_list_get_multi_select(
00946     const PurpleRequestField *field);
00947 
00956 void *purple_request_field_list_get_data(const PurpleRequestField *field,
00957                                        const char *text);
00958 
00968 void purple_request_field_list_add(PurpleRequestField *field,
00969                                  const char *item, void *data);
00970 
00979 void purple_request_field_list_add_icon(PurpleRequestField *field,
00980                                  const char *item, const char* icon_path, void* data);
00981 
00988 void purple_request_field_list_add_selected(PurpleRequestField *field,
00989                                           const char *item);
00990 
00996 void purple_request_field_list_clear_selected(PurpleRequestField *field);
00997 
01004 void purple_request_field_list_set_selected(PurpleRequestField *field,
01005                                           GList *items);
01006 
01015 gboolean purple_request_field_list_is_selected(const PurpleRequestField *field,
01016                                              const char *item);
01017 
01028 GList *purple_request_field_list_get_selected(
01029     const PurpleRequestField *field);
01030 
01038 GList *purple_request_field_list_get_items(const PurpleRequestField *field);
01039 
01050 GList *purple_request_field_list_get_icons(const PurpleRequestField *field);
01051 
01054 /**************************************************************************/
01056 /**************************************************************************/
01067 PurpleRequestField *purple_request_field_label_new(const char *id,
01068                                                const char *text);
01069 
01072 /**************************************************************************/
01074 /**************************************************************************/
01087 PurpleRequestField *purple_request_field_image_new(const char *id, const char *text,
01088                                                const char *buf, gsize size);
01089 
01097 void purple_request_field_image_set_scale(PurpleRequestField *field, unsigned int x, unsigned int y);
01098 
01106 const char *purple_request_field_image_get_buffer(PurpleRequestField *field);
01107 
01115 gsize purple_request_field_image_get_size(PurpleRequestField *field);
01116 
01124 unsigned int purple_request_field_image_get_scale_x(PurpleRequestField *field);
01125 
01133 unsigned int purple_request_field_image_get_scale_y(PurpleRequestField *field);
01134 
01137 /**************************************************************************/
01139 /**************************************************************************/
01153 PurpleRequestField *purple_request_field_account_new(const char *id,
01154                                                  const char *text,
01155                                                  PurpleAccount *account);
01156 
01163 void purple_request_field_account_set_default_value(PurpleRequestField *field,
01164                                                   PurpleAccount *default_value);
01165 
01172 void purple_request_field_account_set_value(PurpleRequestField *field,
01173                                           PurpleAccount *value);
01174 
01184 void purple_request_field_account_set_show_all(PurpleRequestField *field,
01185                                              gboolean show_all);
01186 
01196 void purple_request_field_account_set_filter(PurpleRequestField *field,
01197                                            PurpleFilterAccountFunc filter_func);
01198 
01206 PurpleAccount *purple_request_field_account_get_default_value(
01207         const PurpleRequestField *field);
01208 
01216 PurpleAccount *purple_request_field_account_get_value(
01217         const PurpleRequestField *field);
01218 
01228 gboolean purple_request_field_account_get_show_all(
01229         const PurpleRequestField *field);
01230 
01241 PurpleFilterAccountFunc purple_request_field_account_get_filter(
01242         const PurpleRequestField *field);
01243 
01246 /**************************************************************************/
01248 /**************************************************************************/
01297 void *purple_request_input(void *handle, const char *title, const char *primary,
01298     const char *secondary, const char *default_value, gboolean multiline,
01299     gboolean masked, gchar *hint,
01300     const char *ok_text, GCallback ok_cb,
01301     const char *cancel_text, GCallback cancel_cb,
01302     PurpleAccount *account, const char *who, PurpleConversation *conv,
01303     void *user_data);
01304 
01338 void *purple_request_choice(void *handle, const char *title, const char *primary,
01339     const char *secondary, int default_value,
01340     const char *ok_text, GCallback ok_cb,
01341     const char *cancel_text, GCallback cancel_cb,
01342     PurpleAccount *account, const char *who, PurpleConversation *conv,
01343     void *user_data, ...) G_GNUC_NULL_TERMINATED;
01344 
01348 void *purple_request_choice_varg(void *handle, const char *title,
01349     const char *primary, const char *secondary, int default_value,
01350     const char *ok_text, GCallback ok_cb,
01351     const char *cancel_text, GCallback cancel_cb,
01352     PurpleAccount *account, const char *who, PurpleConversation *conv,
01353     void *user_data, va_list choices);
01354 
01390 void *purple_request_action(void *handle, const char *title, const char *primary,
01391     const char *secondary, int default_action, PurpleAccount *account,
01392     const char *who, PurpleConversation *conv, void *user_data,
01393     size_t action_count, ...);
01394 
01398 void *purple_request_action_varg(void *handle, const char *title,
01399     const char *primary, const char *secondary, int default_action,
01400     PurpleAccount *account, const char *who, PurpleConversation *conv,
01401     void *user_data, size_t action_count, va_list actions);
01402 
01408 void *purple_request_action_with_icon(void *handle, const char *title, 
01409     const char *primary, const char *secondary, int default_action, 
01410     PurpleAccount *account, const char *who, PurpleConversation *conv, 
01411     gconstpointer icon_data, gsize icon_size, void *user_data, 
01412     size_t action_count, ...);
01413 
01419 void *purple_request_action_with_icon_varg(void *handle, const char *title,
01420     const char *primary, const char *secondary, int default_action,
01421     PurpleAccount *account, const char *who, PurpleConversation *conv,
01422     gconstpointer icon_data, gsize icon_size,
01423     void *user_data, size_t action_count, va_list actions);
01424 
01425 
01455 void *purple_request_fields(void *handle, const char *title, const char *primary,
01456     const char *secondary, PurpleRequestFields *fields,
01457     const char *ok_text, GCallback ok_cb,
01458     const char *cancel_text, GCallback cancel_cb,
01459     PurpleAccount *account, const char *who, PurpleConversation *conv,
01460     void *user_data);
01461 
01468 void purple_request_close(PurpleRequestType type, void *uihandle);
01469 
01478 void purple_request_close_with_handle(void *handle);
01479 
01483 #define purple_request_yes_no(handle, title, primary, secondary, \
01484                             default_action, account, who, conv, \
01485                             user_data, yes_cb, no_cb) \
01486     purple_request_action((handle), (title), (primary), (secondary), \
01487                         (default_action), account, who, conv, (user_data), 2, \
01488                         _("_Yes"), (yes_cb), _("_No"), (no_cb))
01489 
01493 #define purple_request_ok_cancel(handle, title, primary, secondary, \
01494                             default_action, account, who, conv, \
01495                             user_data, ok_cb, cancel_cb) \
01496     purple_request_action((handle), (title), (primary), (secondary), \
01497                         (default_action), account, who, conv, (user_data), 2, \
01498                         _("_OK"), (ok_cb), _("_Cancel"), (cancel_cb))
01499 
01503 #define purple_request_accept_cancel(handle, title, primary, secondary, \
01504                                    default_action, account, who, conv, \
01505                                    user_data, accept_cb, cancel_cb) \
01506     purple_request_action((handle), (title), (primary), (secondary), \
01507                         (default_action), account, who, conv, (user_data), 2, \
01508                         _("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
01509 
01514 #define purple_request_accept_cancel_with_icon(handle, title, primary, secondary, \
01515                                    default_action, account, who, conv, \
01516                                    icon_data, icon_size, \
01517                                    user_data, accept_cb, cancel_cb) \
01518     purple_request_action_with_icon((handle), (title), (primary), (secondary), \
01519                         (default_action), account, who, conv, icon_data, icon_size, \
01520                         (user_data), 2, \
01521                         _("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
01522 
01547 void *purple_request_file(void *handle, const char *title, const char *filename,
01548     gboolean savedialog, GCallback ok_cb, GCallback cancel_cb,
01549     PurpleAccount *account, const char *who, PurpleConversation *conv,
01550     void *user_data);
01551 
01574 void *purple_request_folder(void *handle, const char *title, const char *dirname,
01575     GCallback ok_cb, GCallback cancel_cb,
01576     PurpleAccount *account, const char *who, PurpleConversation *conv,
01577     void *user_data);
01578 
01581 /**************************************************************************/
01583 /**************************************************************************/
01592 void purple_request_set_ui_ops(PurpleRequestUiOps *ops);
01593 
01600 PurpleRequestUiOps *purple_request_get_ui_ops(void);
01601 
01604 #ifdef __cplusplus
01605 }
01606 #endif
01607 
01608 #endif /* _PURPLE_REQUEST_H_ */