1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/request.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,1538 @@
1.4 +/**
1.5 + * @file request.h Request API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +#ifndef _PURPLE_REQUEST_H_
1.30 +#define _PURPLE_REQUEST_H_
1.31 +
1.32 +#include <stdlib.h>
1.33 +#include <glib-object.h>
1.34 +#include <glib.h>
1.35 +
1.36 +/** @copydoc _PurpleRequestField */
1.37 +typedef struct _PurpleRequestField PurpleRequestField;
1.38 +
1.39 +#include "account.h"
1.40 +
1.41 +#define PURPLE_DEFAULT_ACTION_NONE -1
1.42 +
1.43 +/**
1.44 + * Request types.
1.45 + */
1.46 +typedef enum
1.47 +{
1.48 + PURPLE_REQUEST_INPUT = 0, /**< Text input request. */
1.49 + PURPLE_REQUEST_CHOICE, /**< Multiple-choice request. */
1.50 + PURPLE_REQUEST_ACTION, /**< Action request. */
1.51 + PURPLE_REQUEST_FIELDS, /**< Multiple fields request. */
1.52 + PURPLE_REQUEST_FILE, /**< File open or save request. */
1.53 + PURPLE_REQUEST_FOLDER /**< Folder selection request. */
1.54 +
1.55 +} PurpleRequestType;
1.56 +
1.57 +/**
1.58 + * A type of field.
1.59 + */
1.60 +typedef enum
1.61 +{
1.62 + PURPLE_REQUEST_FIELD_NONE,
1.63 + PURPLE_REQUEST_FIELD_STRING,
1.64 + PURPLE_REQUEST_FIELD_INTEGER,
1.65 + PURPLE_REQUEST_FIELD_BOOLEAN,
1.66 + PURPLE_REQUEST_FIELD_CHOICE,
1.67 + PURPLE_REQUEST_FIELD_LIST,
1.68 + PURPLE_REQUEST_FIELD_LABEL,
1.69 + PURPLE_REQUEST_FIELD_IMAGE,
1.70 + PURPLE_REQUEST_FIELD_ACCOUNT
1.71 +
1.72 +} PurpleRequestFieldType;
1.73 +
1.74 +/**
1.75 + * Multiple fields request data.
1.76 + */
1.77 +typedef struct
1.78 +{
1.79 + GList *groups;
1.80 +
1.81 + GHashTable *fields;
1.82 +
1.83 + GList *required_fields;
1.84 +
1.85 + void *ui_data;
1.86 +
1.87 +} PurpleRequestFields;
1.88 +
1.89 +/**
1.90 + * A group of fields with a title.
1.91 + */
1.92 +typedef struct
1.93 +{
1.94 + PurpleRequestFields *fields_list;
1.95 +
1.96 + char *title;
1.97 +
1.98 + GList *fields;
1.99 +
1.100 +} PurpleRequestFieldGroup;
1.101 +
1.102 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_REQUEST_C_)
1.103 +/**
1.104 + * A request field.
1.105 + */
1.106 +struct _PurpleRequestField
1.107 +{
1.108 + PurpleRequestFieldType type;
1.109 + PurpleRequestFieldGroup *group;
1.110 +
1.111 + char *id;
1.112 + char *label;
1.113 + char *type_hint;
1.114 +
1.115 + gboolean visible;
1.116 + gboolean required;
1.117 +
1.118 + union
1.119 + {
1.120 + struct
1.121 + {
1.122 + gboolean multiline;
1.123 + gboolean masked;
1.124 + gboolean editable;
1.125 + char *default_value;
1.126 + char *value;
1.127 +
1.128 + } string;
1.129 +
1.130 + struct
1.131 + {
1.132 + int default_value;
1.133 + int value;
1.134 +
1.135 + } integer;
1.136 +
1.137 + struct
1.138 + {
1.139 + gboolean default_value;
1.140 + gboolean value;
1.141 +
1.142 + } boolean;
1.143 +
1.144 + struct
1.145 + {
1.146 + int default_value;
1.147 + int value;
1.148 +
1.149 + GList *labels;
1.150 +
1.151 + } choice;
1.152 +
1.153 + struct
1.154 + {
1.155 + GList *items;
1.156 + GHashTable *item_data;
1.157 + GList *selected;
1.158 + GHashTable *selected_table;
1.159 +
1.160 + gboolean multiple_selection;
1.161 +
1.162 + } list;
1.163 +
1.164 + struct
1.165 + {
1.166 + PurpleAccount *default_account;
1.167 + PurpleAccount *account;
1.168 + gboolean show_all;
1.169 +
1.170 + PurpleFilterAccountFunc filter_func;
1.171 +
1.172 + } account;
1.173 +
1.174 + struct
1.175 + {
1.176 + unsigned int scale_x;
1.177 + unsigned int scale_y;
1.178 + const char *buffer;
1.179 + gsize size;
1.180 + } image;
1.181 +
1.182 + } u;
1.183 +
1.184 + void *ui_data;
1.185 +
1.186 +};
1.187 +#endif
1.188 +
1.189 +/**
1.190 + * Request UI operations.
1.191 + */
1.192 +typedef struct
1.193 +{
1.194 + /** @see purple_request_input(). */
1.195 + void *(*request_input)(const char *title, const char *primary,
1.196 + const char *secondary, const char *default_value,
1.197 + gboolean multiline, gboolean masked, gchar *hint,
1.198 + const char *ok_text, GCallback ok_cb,
1.199 + const char *cancel_text, GCallback cancel_cb,
1.200 + PurpleAccount *account, const char *who,
1.201 + PurpleConversation *conv, void *user_data);
1.202 +
1.203 + /** @see purple_request_choice_varg(). */
1.204 + void *(*request_choice)(const char *title, const char *primary,
1.205 + const char *secondary, int default_value,
1.206 + const char *ok_text, GCallback ok_cb,
1.207 + const char *cancel_text, GCallback cancel_cb,
1.208 + PurpleAccount *account, const char *who,
1.209 + PurpleConversation *conv, void *user_data,
1.210 + va_list choices);
1.211 +
1.212 + /** @see purple_request_action_varg(). */
1.213 + void *(*request_action)(const char *title, const char *primary,
1.214 + const char *secondary, int default_action,
1.215 + PurpleAccount *account, const char *who,
1.216 + PurpleConversation *conv, void *user_data,
1.217 + size_t action_count, va_list actions);
1.218 +
1.219 + /** @see purple_request_fields(). */
1.220 + void *(*request_fields)(const char *title, const char *primary,
1.221 + const char *secondary, PurpleRequestFields *fields,
1.222 + const char *ok_text, GCallback ok_cb,
1.223 + const char *cancel_text, GCallback cancel_cb,
1.224 + PurpleAccount *account, const char *who,
1.225 + PurpleConversation *conv, void *user_data);
1.226 +
1.227 + /** @see purple_request_file(). */
1.228 + void *(*request_file)(const char *title, const char *filename,
1.229 + gboolean savedialog, GCallback ok_cb,
1.230 + GCallback cancel_cb, PurpleAccount *account,
1.231 + const char *who, PurpleConversation *conv,
1.232 + void *user_data);
1.233 +
1.234 + void (*close_request)(PurpleRequestType type, void *ui_handle);
1.235 +
1.236 + /** @see purple_request_folder(). */
1.237 + void *(*request_folder)(const char *title, const char *dirname,
1.238 + GCallback ok_cb, GCallback cancel_cb,
1.239 + PurpleAccount *account, const char *who,
1.240 + PurpleConversation *conv, void *user_data);
1.241 +
1.242 + void (*_purple_reserved1)(void);
1.243 + void (*_purple_reserved2)(void);
1.244 + void (*_purple_reserved3)(void);
1.245 + void (*_purple_reserved4)(void);
1.246 +} PurpleRequestUiOps;
1.247 +
1.248 +typedef void (*PurpleRequestInputCb)(void *, const char *);
1.249 +
1.250 +/** The type of callbacks passed to purple_request_action(). The first
1.251 + * argument is the @a user_data parameter; the second is the index in the list
1.252 + * of actions of the one chosen.
1.253 + */
1.254 +typedef void (*PurpleRequestActionCb)(void *, int);
1.255 +typedef void (*PurpleRequestChoiceCb)(void *, int);
1.256 +typedef void (*PurpleRequestFieldsCb)(void *, PurpleRequestFields *fields);
1.257 +typedef void (*PurpleRequestFileCb)(void *, const char *filename);
1.258 +
1.259 +#ifdef __cplusplus
1.260 +extern "C" {
1.261 +#endif
1.262 +
1.263 +/**************************************************************************/
1.264 +/** @name Field List API */
1.265 +/**************************************************************************/
1.266 +/*@{*/
1.267 +
1.268 +/**
1.269 + * Creates a list of fields to pass to purple_request_fields().
1.270 + *
1.271 + * @return A PurpleRequestFields structure.
1.272 + */
1.273 +PurpleRequestFields *purple_request_fields_new(void);
1.274 +
1.275 +/**
1.276 + * Destroys a list of fields.
1.277 + *
1.278 + * @param fields The list of fields to destroy.
1.279 + */
1.280 +void purple_request_fields_destroy(PurpleRequestFields *fields);
1.281 +
1.282 +/**
1.283 + * Adds a group of fields to the list.
1.284 + *
1.285 + * @param fields The fields list.
1.286 + * @param group The group to add.
1.287 + */
1.288 +void purple_request_fields_add_group(PurpleRequestFields *fields,
1.289 + PurpleRequestFieldGroup *group);
1.290 +
1.291 +/**
1.292 + * Returns a list of all groups in a field list.
1.293 + *
1.294 + * @param fields The fields list.
1.295 + *
1.296 + * @constreturn A list of groups.
1.297 + */
1.298 +GList *purple_request_fields_get_groups(const PurpleRequestFields *fields);
1.299 +
1.300 +/**
1.301 + * Returns whether or not the field with the specified ID exists.
1.302 + *
1.303 + * @param fields The fields list.
1.304 + * @param id The ID of the field.
1.305 + *
1.306 + * @return TRUE if the field exists, or FALSE.
1.307 + */
1.308 +gboolean purple_request_fields_exists(const PurpleRequestFields *fields,
1.309 + const char *id);
1.310 +
1.311 +/**
1.312 + * Returns a list of all required fields.
1.313 + *
1.314 + * @param fields The fields list.
1.315 + *
1.316 + * @constreturn The list of required fields.
1.317 + */
1.318 +GList *purple_request_fields_get_required(const PurpleRequestFields *fields);
1.319 +
1.320 +/**
1.321 + * Returns whether or not a field with the specified ID is required.
1.322 + *
1.323 + * @param fields The fields list.
1.324 + * @param id The field ID.
1.325 + *
1.326 + * @return TRUE if the specified field is required, or FALSE.
1.327 + */
1.328 +gboolean purple_request_fields_is_field_required(const PurpleRequestFields *fields,
1.329 + const char *id);
1.330 +
1.331 +/**
1.332 + * Returns whether or not all required fields have values.
1.333 + *
1.334 + * @param fields The fields list.
1.335 + *
1.336 + * @return TRUE if all required fields have values, or FALSE.
1.337 + */
1.338 +gboolean purple_request_fields_all_required_filled(
1.339 + const PurpleRequestFields *fields);
1.340 +
1.341 +/**
1.342 + * Return the field with the specified ID.
1.343 + *
1.344 + * @param fields The fields list.
1.345 + * @param id The ID of the field.
1.346 + *
1.347 + * @return The field, if found.
1.348 + */
1.349 +PurpleRequestField *purple_request_fields_get_field(
1.350 + const PurpleRequestFields *fields, const char *id);
1.351 +
1.352 +/**
1.353 + * Returns the string value of a field with the specified ID.
1.354 + *
1.355 + * @param fields The fields list.
1.356 + * @param id The ID of the field.
1.357 + *
1.358 + * @return The string value, if found, or @c NULL otherwise.
1.359 + */
1.360 +const char *purple_request_fields_get_string(const PurpleRequestFields *fields,
1.361 + const char *id);
1.362 +
1.363 +/**
1.364 + * Returns the integer value of a field with the specified ID.
1.365 + *
1.366 + * @param fields The fields list.
1.367 + * @param id The ID of the field.
1.368 + *
1.369 + * @return The integer value, if found, or 0 otherwise.
1.370 + */
1.371 +int purple_request_fields_get_integer(const PurpleRequestFields *fields,
1.372 + const char *id);
1.373 +
1.374 +/**
1.375 + * Returns the boolean value of a field with the specified ID.
1.376 + *
1.377 + * @param fields The fields list.
1.378 + * @param id The ID of the field.
1.379 + *
1.380 + * @return The boolean value, if found, or @c FALSE otherwise.
1.381 + */
1.382 +gboolean purple_request_fields_get_bool(const PurpleRequestFields *fields,
1.383 + const char *id);
1.384 +
1.385 +/**
1.386 + * Returns the choice index of a field with the specified ID.
1.387 + *
1.388 + * @param fields The fields list.
1.389 + * @param id The ID of the field.
1.390 + *
1.391 + * @return The choice index, if found, or -1 otherwise.
1.392 + */
1.393 +int purple_request_fields_get_choice(const PurpleRequestFields *fields,
1.394 + const char *id);
1.395 +
1.396 +/**
1.397 + * Returns the account of a field with the specified ID.
1.398 + *
1.399 + * @param fields The fields list.
1.400 + * @param id The ID of the field.
1.401 + *
1.402 + * @return The account value, if found, or NULL otherwise.
1.403 + */
1.404 +PurpleAccount *purple_request_fields_get_account(const PurpleRequestFields *fields,
1.405 + const char *id);
1.406 +
1.407 +/*@}*/
1.408 +
1.409 +/**************************************************************************/
1.410 +/** @name Fields Group API */
1.411 +/**************************************************************************/
1.412 +/*@{*/
1.413 +
1.414 +/**
1.415 + * Creates a fields group with an optional title.
1.416 + *
1.417 + * @param title The optional title to give the group.
1.418 + *
1.419 + * @return A new fields group
1.420 + */
1.421 +PurpleRequestFieldGroup *purple_request_field_group_new(const char *title);
1.422 +
1.423 +/**
1.424 + * Destroys a fields group.
1.425 + *
1.426 + * @param group The group to destroy.
1.427 + */
1.428 +void purple_request_field_group_destroy(PurpleRequestFieldGroup *group);
1.429 +
1.430 +/**
1.431 + * Adds a field to the group.
1.432 + *
1.433 + * @param group The group to add the field to.
1.434 + * @param field The field to add to the group.
1.435 + */
1.436 +void purple_request_field_group_add_field(PurpleRequestFieldGroup *group,
1.437 + PurpleRequestField *field);
1.438 +
1.439 +/**
1.440 + * Returns the title of a fields group.
1.441 + *
1.442 + * @param group The group.
1.443 + *
1.444 + * @return The title, if set.
1.445 + */
1.446 +const char *purple_request_field_group_get_title(
1.447 + const PurpleRequestFieldGroup *group);
1.448 +
1.449 +/**
1.450 + * Returns a list of all fields in a group.
1.451 + *
1.452 + * @param group The group.
1.453 + *
1.454 + * @constreturn The list of fields in the group.
1.455 + */
1.456 +GList *purple_request_field_group_get_fields(
1.457 + const PurpleRequestFieldGroup *group);
1.458 +
1.459 +/*@}*/
1.460 +
1.461 +/**************************************************************************/
1.462 +/** @name Field API */
1.463 +/**************************************************************************/
1.464 +/*@{*/
1.465 +
1.466 +/**
1.467 + * Creates a field of the specified type.
1.468 + *
1.469 + * @param id The field ID.
1.470 + * @param text The text label of the field.
1.471 + * @param type The type of field.
1.472 + *
1.473 + * @return The new field.
1.474 + */
1.475 +PurpleRequestField *purple_request_field_new(const char *id, const char *text,
1.476 + PurpleRequestFieldType type);
1.477 +
1.478 +/**
1.479 + * Destroys a field.
1.480 + *
1.481 + * @param field The field to destroy.
1.482 + */
1.483 +void purple_request_field_destroy(PurpleRequestField *field);
1.484 +
1.485 +/**
1.486 + * Sets the label text of a field.
1.487 + *
1.488 + * @param field The field.
1.489 + * @param label The text label.
1.490 + */
1.491 +void purple_request_field_set_label(PurpleRequestField *field, const char *label);
1.492 +
1.493 +/**
1.494 + * Sets whether or not a field is visible.
1.495 + *
1.496 + * @param field The field.
1.497 + * @param visible TRUE if visible, or FALSE if not.
1.498 + */
1.499 +void purple_request_field_set_visible(PurpleRequestField *field, gboolean visible);
1.500 +
1.501 +/**
1.502 + * Sets the type hint for the field.
1.503 + *
1.504 + * This is optionally used by the UIs to provide such features as
1.505 + * auto-completion for type hints like "account" and "screenname".
1.506 + *
1.507 + * @param field The field.
1.508 + * @param type_hint The type hint.
1.509 + */
1.510 +void purple_request_field_set_type_hint(PurpleRequestField *field,
1.511 + const char *type_hint);
1.512 +
1.513 +/**
1.514 + * Sets whether or not a field is required.
1.515 + *
1.516 + * @param field The field.
1.517 + * @param required TRUE if required, or FALSE.
1.518 + */
1.519 +void purple_request_field_set_required(PurpleRequestField *field,
1.520 + gboolean required);
1.521 +
1.522 +/**
1.523 + * Returns the type of a field.
1.524 + *
1.525 + * @param field The field.
1.526 + *
1.527 + * @return The field's type.
1.528 + */
1.529 +PurpleRequestFieldType purple_request_field_get_type(const PurpleRequestField *field);
1.530 +
1.531 +/**
1.532 + * Returns the group for the field.
1.533 + *
1.534 + * @param field The field.
1.535 + *
1.536 + * @return The UI data.
1.537 + *
1.538 + * @since 2.6.0
1.539 + */
1.540 +PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field);
1.541 +
1.542 +/**
1.543 + * Returns the ID of a field.
1.544 + *
1.545 + * @param field The field.
1.546 + *
1.547 + * @return The ID
1.548 + */
1.549 +const char *purple_request_field_get_id(const PurpleRequestField *field);
1.550 +
1.551 +/**
1.552 + * Returns the label text of a field.
1.553 + *
1.554 + * @param field The field.
1.555 + *
1.556 + * @return The label text.
1.557 + */
1.558 +const char *purple_request_field_get_label(const PurpleRequestField *field);
1.559 +
1.560 +/**
1.561 + * Returns whether or not a field is visible.
1.562 + *
1.563 + * @param field The field.
1.564 + *
1.565 + * @return TRUE if the field is visible. FALSE otherwise.
1.566 + */
1.567 +gboolean purple_request_field_is_visible(const PurpleRequestField *field);
1.568 +
1.569 +/**
1.570 + * Returns the field's type hint.
1.571 + *
1.572 + * @param field The field.
1.573 + *
1.574 + * @return The field's type hint.
1.575 + */
1.576 +const char *purple_request_field_get_type_hint(const PurpleRequestField *field);
1.577 +
1.578 +/**
1.579 + * Returns whether or not a field is required.
1.580 + *
1.581 + * @param field The field.
1.582 + *
1.583 + * @return TRUE if the field is required, or FALSE.
1.584 + */
1.585 +gboolean purple_request_field_is_required(const PurpleRequestField *field);
1.586 +
1.587 +/**
1.588 + * Returns the ui_data for a field.
1.589 + *
1.590 + * @param field The field.
1.591 + *
1.592 + * @return The UI data.
1.593 + *
1.594 + * @since 2.6.0
1.595 + */
1.596 +gpointer purple_request_field_get_ui_data(const PurpleRequestField *field);
1.597 +
1.598 +/**
1.599 + * Sets the ui_data for a field.
1.600 + *
1.601 + * @param field The field.
1.602 + * @param ui_data The UI data.
1.603 + *
1.604 + * @return The UI data.
1.605 + *
1.606 + * @since 2.6.0
1.607 + */
1.608 +void purple_request_field_set_ui_data(PurpleRequestField *field,
1.609 + gpointer ui_data);
1.610 +
1.611 +/*@}*/
1.612 +
1.613 +/**************************************************************************/
1.614 +/** @name String Field API */
1.615 +/**************************************************************************/
1.616 +/*@{*/
1.617 +
1.618 +/**
1.619 + * Creates a string request field.
1.620 + *
1.621 + * @param id The field ID.
1.622 + * @param text The text label of the field.
1.623 + * @param default_value The optional default value.
1.624 + * @param multiline Whether or not this should be a multiline string.
1.625 + *
1.626 + * @return The new field.
1.627 + */
1.628 +PurpleRequestField *purple_request_field_string_new(const char *id,
1.629 + const char *text,
1.630 + const char *default_value,
1.631 + gboolean multiline);
1.632 +
1.633 +/**
1.634 + * Sets the default value in a string field.
1.635 + *
1.636 + * @param field The field.
1.637 + * @param default_value The default value.
1.638 + */
1.639 +void purple_request_field_string_set_default_value(PurpleRequestField *field,
1.640 + const char *default_value);
1.641 +
1.642 +/**
1.643 + * Sets the value in a string field.
1.644 + *
1.645 + * @param field The field.
1.646 + * @param value The value.
1.647 + */
1.648 +void purple_request_field_string_set_value(PurpleRequestField *field,
1.649 + const char *value);
1.650 +
1.651 +/**
1.652 + * Sets whether or not a string field is masked
1.653 + * (commonly used for password fields).
1.654 + *
1.655 + * @param field The field.
1.656 + * @param masked The masked value.
1.657 + */
1.658 +void purple_request_field_string_set_masked(PurpleRequestField *field,
1.659 + gboolean masked);
1.660 +
1.661 +/**
1.662 + * Sets whether or not a string field is editable.
1.663 + *
1.664 + * @param field The field.
1.665 + * @param editable The editable value.
1.666 + */
1.667 +void purple_request_field_string_set_editable(PurpleRequestField *field,
1.668 + gboolean editable);
1.669 +
1.670 +/**
1.671 + * Returns the default value in a string field.
1.672 + *
1.673 + * @param field The field.
1.674 + *
1.675 + * @return The default value.
1.676 + */
1.677 +const char *purple_request_field_string_get_default_value(
1.678 + const PurpleRequestField *field);
1.679 +
1.680 +/**
1.681 + * Returns the user-entered value in a string field.
1.682 + *
1.683 + * @param field The field.
1.684 + *
1.685 + * @return The value.
1.686 + */
1.687 +const char *purple_request_field_string_get_value(const PurpleRequestField *field);
1.688 +
1.689 +/**
1.690 + * Returns whether or not a string field is multi-line.
1.691 + *
1.692 + * @param field The field.
1.693 + *
1.694 + * @return @c TRUE if the field is mulit-line, or @c FALSE otherwise.
1.695 + */
1.696 +gboolean purple_request_field_string_is_multiline(const PurpleRequestField *field);
1.697 +
1.698 +/**
1.699 + * Returns whether or not a string field is masked.
1.700 + *
1.701 + * @param field The field.
1.702 + *
1.703 + * @return @c TRUE if the field is masked, or @c FALSE otherwise.
1.704 + */
1.705 +gboolean purple_request_field_string_is_masked(const PurpleRequestField *field);
1.706 +
1.707 +/**
1.708 + * Returns whether or not a string field is editable.
1.709 + *
1.710 + * @param field The field.
1.711 + *
1.712 + * @return @c TRUE if the field is editable, or @c FALSE otherwise.
1.713 + */
1.714 +gboolean purple_request_field_string_is_editable(const PurpleRequestField *field);
1.715 +
1.716 +/*@}*/
1.717 +
1.718 +/**************************************************************************/
1.719 +/** @name Integer Field API */
1.720 +/**************************************************************************/
1.721 +/*@{*/
1.722 +
1.723 +/**
1.724 + * Creates an integer field.
1.725 + *
1.726 + * @param id The field ID.
1.727 + * @param text The text label of the field.
1.728 + * @param default_value The default value.
1.729 + *
1.730 + * @return The new field.
1.731 + */
1.732 +PurpleRequestField *purple_request_field_int_new(const char *id,
1.733 + const char *text,
1.734 + int default_value);
1.735 +
1.736 +/**
1.737 + * Sets the default value in an integer field.
1.738 + *
1.739 + * @param field The field.
1.740 + * @param default_value The default value.
1.741 + */
1.742 +void purple_request_field_int_set_default_value(PurpleRequestField *field,
1.743 + int default_value);
1.744 +
1.745 +/**
1.746 + * Sets the value in an integer field.
1.747 + *
1.748 + * @param field The field.
1.749 + * @param value The value.
1.750 + */
1.751 +void purple_request_field_int_set_value(PurpleRequestField *field, int value);
1.752 +
1.753 +/**
1.754 + * Returns the default value in an integer field.
1.755 + *
1.756 + * @param field The field.
1.757 + *
1.758 + * @return The default value.
1.759 + */
1.760 +int purple_request_field_int_get_default_value(const PurpleRequestField *field);
1.761 +
1.762 +/**
1.763 + * Returns the user-entered value in an integer field.
1.764 + *
1.765 + * @param field The field.
1.766 + *
1.767 + * @return The value.
1.768 + */
1.769 +int purple_request_field_int_get_value(const PurpleRequestField *field);
1.770 +
1.771 +/*@}*/
1.772 +
1.773 +/**************************************************************************/
1.774 +/** @name Boolean Field API */
1.775 +/**************************************************************************/
1.776 +/*@{*/
1.777 +
1.778 +/**
1.779 + * Creates a boolean field.
1.780 + *
1.781 + * This is often represented as a checkbox.
1.782 + *
1.783 + * @param id The field ID.
1.784 + * @param text The text label of the field.
1.785 + * @param default_value The default value.
1.786 + *
1.787 + * @return The new field.
1.788 + */
1.789 +PurpleRequestField *purple_request_field_bool_new(const char *id,
1.790 + const char *text,
1.791 + gboolean default_value);
1.792 +
1.793 +/**
1.794 + * Sets the default value in an boolean field.
1.795 + *
1.796 + * @param field The field.
1.797 + * @param default_value The default value.
1.798 + */
1.799 +void purple_request_field_bool_set_default_value(PurpleRequestField *field,
1.800 + gboolean default_value);
1.801 +
1.802 +/**
1.803 + * Sets the value in an boolean field.
1.804 + *
1.805 + * @param field The field.
1.806 + * @param value The value.
1.807 + */
1.808 +void purple_request_field_bool_set_value(PurpleRequestField *field,
1.809 + gboolean value);
1.810 +
1.811 +/**
1.812 + * Returns the default value in an boolean field.
1.813 + *
1.814 + * @param field The field.
1.815 + *
1.816 + * @return The default value.
1.817 + */
1.818 +gboolean purple_request_field_bool_get_default_value(
1.819 + const PurpleRequestField *field);
1.820 +
1.821 +/**
1.822 + * Returns the user-entered value in an boolean field.
1.823 + *
1.824 + * @param field The field.
1.825 + *
1.826 + * @return The value.
1.827 + */
1.828 +gboolean purple_request_field_bool_get_value(const PurpleRequestField *field);
1.829 +
1.830 +/*@}*/
1.831 +
1.832 +/**************************************************************************/
1.833 +/** @name Choice Field API */
1.834 +/**************************************************************************/
1.835 +/*@{*/
1.836 +
1.837 +/**
1.838 + * Creates a multiple choice field.
1.839 + *
1.840 + * This is often represented as a group of radio buttons.
1.841 + *
1.842 + * @param id The field ID.
1.843 + * @param text The optional label of the field.
1.844 + * @param default_value The default choice.
1.845 + *
1.846 + * @return The new field.
1.847 + */
1.848 +PurpleRequestField *purple_request_field_choice_new(const char *id,
1.849 + const char *text,
1.850 + int default_value);
1.851 +
1.852 +/**
1.853 + * Adds a choice to a multiple choice field.
1.854 + *
1.855 + * @param field The choice field.
1.856 + * @param label The choice label.
1.857 + */
1.858 +void purple_request_field_choice_add(PurpleRequestField *field,
1.859 + const char *label);
1.860 +
1.861 +/**
1.862 + * Sets the default value in an choice field.
1.863 + *
1.864 + * @param field The field.
1.865 + * @param default_value The default value.
1.866 + */
1.867 +void purple_request_field_choice_set_default_value(PurpleRequestField *field,
1.868 + int default_value);
1.869 +
1.870 +/**
1.871 + * Sets the value in an choice field.
1.872 + *
1.873 + * @param field The field.
1.874 + * @param value The value.
1.875 + */
1.876 +void purple_request_field_choice_set_value(PurpleRequestField *field, int value);
1.877 +
1.878 +/**
1.879 + * Returns the default value in an choice field.
1.880 + *
1.881 + * @param field The field.
1.882 + *
1.883 + * @return The default value.
1.884 + */
1.885 +int purple_request_field_choice_get_default_value(const PurpleRequestField *field);
1.886 +
1.887 +/**
1.888 + * Returns the user-entered value in an choice field.
1.889 + *
1.890 + * @param field The field.
1.891 + *
1.892 + * @return The value.
1.893 + */
1.894 +int purple_request_field_choice_get_value(const PurpleRequestField *field);
1.895 +
1.896 +/**
1.897 + * Returns a list of labels in a choice field.
1.898 + *
1.899 + * @param field The field.
1.900 + *
1.901 + * @constreturn The list of labels.
1.902 + */
1.903 +GList *purple_request_field_choice_get_labels(const PurpleRequestField *field);
1.904 +
1.905 +/*@}*/
1.906 +
1.907 +/**************************************************************************/
1.908 +/** @name List Field API */
1.909 +/**************************************************************************/
1.910 +/*@{*/
1.911 +
1.912 +/**
1.913 + * Creates a multiple list item field.
1.914 + *
1.915 + * @param id The field ID.
1.916 + * @param text The optional label of the field.
1.917 + *
1.918 + * @return The new field.
1.919 + */
1.920 +PurpleRequestField *purple_request_field_list_new(const char *id, const char *text);
1.921 +
1.922 +/**
1.923 + * Sets whether or not a list field allows multiple selection.
1.924 + *
1.925 + * @param field The list field.
1.926 + * @param multi_select TRUE if multiple selection is enabled,
1.927 + * or FALSE otherwise.
1.928 + */
1.929 +void purple_request_field_list_set_multi_select(PurpleRequestField *field,
1.930 + gboolean multi_select);
1.931 +
1.932 +/**
1.933 + * Returns whether or not a list field allows multiple selection.
1.934 + *
1.935 + * @param field The list field.
1.936 + *
1.937 + * @return TRUE if multiple selection is enabled, or FALSE otherwise.
1.938 + */
1.939 +gboolean purple_request_field_list_get_multi_select(
1.940 + const PurpleRequestField *field);
1.941 +
1.942 +/**
1.943 + * Returns the data for a particular item.
1.944 + *
1.945 + * @param field The list field.
1.946 + * @param text The item text.
1.947 + *
1.948 + * @return The data associated with the item.
1.949 + */
1.950 +void *purple_request_field_list_get_data(const PurpleRequestField *field,
1.951 + const char *text);
1.952 +
1.953 +/**
1.954 + * Adds an item to a list field.
1.955 + *
1.956 + * @param field The list field.
1.957 + * @param item The list item.
1.958 + * @param data The associated data.
1.959 + */
1.960 +void purple_request_field_list_add(PurpleRequestField *field,
1.961 + const char *item, void *data);
1.962 +
1.963 +/**
1.964 + * Adds a selected item to the list field.
1.965 + *
1.966 + * @param field The field.
1.967 + * @param item The item to add.
1.968 + */
1.969 +void purple_request_field_list_add_selected(PurpleRequestField *field,
1.970 + const char *item);
1.971 +
1.972 +/**
1.973 + * Clears the list of selected items in a list field.
1.974 + *
1.975 + * @param field The field.
1.976 + */
1.977 +void purple_request_field_list_clear_selected(PurpleRequestField *field);
1.978 +
1.979 +/**
1.980 + * Sets a list of selected items in a list field.
1.981 + *
1.982 + * @param field The field.
1.983 + * @param items The list of selected items, which is not modified or freed.
1.984 + */
1.985 +void purple_request_field_list_set_selected(PurpleRequestField *field,
1.986 + GList *items);
1.987 +
1.988 +/**
1.989 + * Returns whether or not a particular item is selected in a list field.
1.990 + *
1.991 + * @param field The field.
1.992 + * @param item The item.
1.993 + *
1.994 + * @return TRUE if the item is selected. FALSE otherwise.
1.995 + */
1.996 +gboolean purple_request_field_list_is_selected(const PurpleRequestField *field,
1.997 + const char *item);
1.998 +
1.999 +/**
1.1000 + * Returns a list of selected items in a list field.
1.1001 + *
1.1002 + * To retrieve the data for each item, use
1.1003 + * purple_request_field_list_get_data().
1.1004 + *
1.1005 + * @param field The field.
1.1006 + *
1.1007 + * @constreturn The list of selected items.
1.1008 + */
1.1009 +GList *purple_request_field_list_get_selected(
1.1010 + const PurpleRequestField *field);
1.1011 +
1.1012 +/**
1.1013 + * Returns a list of items in a list field.
1.1014 + *
1.1015 + * @param field The field.
1.1016 + *
1.1017 + * @constreturn The list of items.
1.1018 + */
1.1019 +GList *purple_request_field_list_get_items(const PurpleRequestField *field);
1.1020 +
1.1021 +/*@}*/
1.1022 +
1.1023 +/**************************************************************************/
1.1024 +/** @name Label Field API */
1.1025 +/**************************************************************************/
1.1026 +/*@{*/
1.1027 +
1.1028 +/**
1.1029 + * Creates a label field.
1.1030 + *
1.1031 + * @param id The field ID.
1.1032 + * @param text The label of the field.
1.1033 + *
1.1034 + * @return The new field.
1.1035 + */
1.1036 +PurpleRequestField *purple_request_field_label_new(const char *id,
1.1037 + const char *text);
1.1038 +
1.1039 +/*@}*/
1.1040 +
1.1041 +/**************************************************************************/
1.1042 +/** @name Image Field API */
1.1043 +/**************************************************************************/
1.1044 +/*@{*/
1.1045 +
1.1046 +/**
1.1047 + * Creates an image field.
1.1048 + *
1.1049 + * @param id The field ID.
1.1050 + * @param text The label of the field.
1.1051 + * @param buf The image data.
1.1052 + * @param size The size of the data in @a buffer.
1.1053 + *
1.1054 + * @return The new field.
1.1055 + */
1.1056 +PurpleRequestField *purple_request_field_image_new(const char *id, const char *text,
1.1057 + const char *buf, gsize size);
1.1058 +
1.1059 +/**
1.1060 + * Sets the scale factors of an image field.
1.1061 + *
1.1062 + * @param field The image field.
1.1063 + * @param x The x scale factor.
1.1064 + * @param y The y scale factor.
1.1065 + */
1.1066 +void purple_request_field_image_set_scale(PurpleRequestField *field, unsigned int x, unsigned int y);
1.1067 +
1.1068 +/**
1.1069 + * Returns pointer to the image.
1.1070 + *
1.1071 + * @param field The image field.
1.1072 + *
1.1073 + * @return Pointer to the image.
1.1074 + */
1.1075 +const char *purple_request_field_image_get_buffer(PurpleRequestField *field);
1.1076 +
1.1077 +/**
1.1078 + * Returns size (in bytes) of the image.
1.1079 + *
1.1080 + * @param field The image field.
1.1081 + *
1.1082 + * @return Size of the image.
1.1083 + */
1.1084 +gsize purple_request_field_image_get_size(PurpleRequestField *field);
1.1085 +
1.1086 +/**
1.1087 + * Returns X scale coefficient of the image.
1.1088 + *
1.1089 + * @param field The image field.
1.1090 + *
1.1091 + * @return X scale coefficient of the image.
1.1092 + */
1.1093 +unsigned int purple_request_field_image_get_scale_x(PurpleRequestField *field);
1.1094 +
1.1095 +/**
1.1096 + * Returns Y scale coefficient of the image.
1.1097 + *
1.1098 + * @param field The image field.
1.1099 + *
1.1100 + * @return Y scale coefficient of the image.
1.1101 + */
1.1102 +unsigned int purple_request_field_image_get_scale_y(PurpleRequestField *field);
1.1103 +
1.1104 +/*@}*/
1.1105 +
1.1106 +/**************************************************************************/
1.1107 +/** @name Account Field API */
1.1108 +/**************************************************************************/
1.1109 +/*@{*/
1.1110 +
1.1111 +/**
1.1112 + * Creates an account field.
1.1113 + *
1.1114 + * By default, this field will not show offline accounts.
1.1115 + *
1.1116 + * @param id The field ID.
1.1117 + * @param text The text label of the field.
1.1118 + * @param account The optional default account.
1.1119 + *
1.1120 + * @return The new field.
1.1121 + */
1.1122 +PurpleRequestField *purple_request_field_account_new(const char *id,
1.1123 + const char *text,
1.1124 + PurpleAccount *account);
1.1125 +
1.1126 +/**
1.1127 + * Sets the default account on an account field.
1.1128 + *
1.1129 + * @param field The account field.
1.1130 + * @param default_value The default account.
1.1131 + */
1.1132 +void purple_request_field_account_set_default_value(PurpleRequestField *field,
1.1133 + PurpleAccount *default_value);
1.1134 +
1.1135 +/**
1.1136 + * Sets the account in an account field.
1.1137 + *
1.1138 + * @param field The account field.
1.1139 + * @param value The account.
1.1140 + */
1.1141 +void purple_request_field_account_set_value(PurpleRequestField *field,
1.1142 + PurpleAccount *value);
1.1143 +
1.1144 +/**
1.1145 + * Sets whether or not to show all accounts in an account field.
1.1146 + *
1.1147 + * If TRUE, all accounts, online or offline, will be shown. If FALSE,
1.1148 + * only online accounts will be shown.
1.1149 + *
1.1150 + * @param field The account field.
1.1151 + * @param show_all Whether or not to show all accounts.
1.1152 + */
1.1153 +void purple_request_field_account_set_show_all(PurpleRequestField *field,
1.1154 + gboolean show_all);
1.1155 +
1.1156 +/**
1.1157 + * Sets the account filter function in an account field.
1.1158 + *
1.1159 + * This function will determine which accounts get displayed and which
1.1160 + * don't.
1.1161 + *
1.1162 + * @param field The account field.
1.1163 + * @param filter_func The account filter function.
1.1164 + */
1.1165 +void purple_request_field_account_set_filter(PurpleRequestField *field,
1.1166 + PurpleFilterAccountFunc filter_func);
1.1167 +
1.1168 +/**
1.1169 + * Returns the default account in an account field.
1.1170 + *
1.1171 + * @param field The field.
1.1172 + *
1.1173 + * @return The default account.
1.1174 + */
1.1175 +PurpleAccount *purple_request_field_account_get_default_value(
1.1176 + const PurpleRequestField *field);
1.1177 +
1.1178 +/**
1.1179 + * Returns the user-entered account in an account field.
1.1180 + *
1.1181 + * @param field The field.
1.1182 + *
1.1183 + * @return The user-entered account.
1.1184 + */
1.1185 +PurpleAccount *purple_request_field_account_get_value(
1.1186 + const PurpleRequestField *field);
1.1187 +
1.1188 +/**
1.1189 + * Returns whether or not to show all accounts in an account field.
1.1190 + *
1.1191 + * If TRUE, all accounts, online or offline, will be shown. If FALSE,
1.1192 + * only online accounts will be shown.
1.1193 + *
1.1194 + * @param field The account field.
1.1195 + * @return Whether or not to show all accounts.
1.1196 + */
1.1197 +gboolean purple_request_field_account_get_show_all(
1.1198 + const PurpleRequestField *field);
1.1199 +
1.1200 +/**
1.1201 + * Returns the account filter function in an account field.
1.1202 + *
1.1203 + * This function will determine which accounts get displayed and which
1.1204 + * don't.
1.1205 + *
1.1206 + * @param field The account field.
1.1207 + *
1.1208 + * @return The account filter function.
1.1209 + */
1.1210 +PurpleFilterAccountFunc purple_request_field_account_get_filter(
1.1211 + const PurpleRequestField *field);
1.1212 +
1.1213 +/*@}*/
1.1214 +
1.1215 +/**************************************************************************/
1.1216 +/** @name Request API */
1.1217 +/**************************************************************************/
1.1218 +/*@{*/
1.1219 +
1.1220 +/**
1.1221 + * Prompts the user for text input.
1.1222 + *
1.1223 + * @param handle The plugin or connection handle. For some
1.1224 + * things this is <em>extremely</em> important. The
1.1225 + * handle is used to programmatically close the request
1.1226 + * dialog when it is no longer needed. For PRPLs this
1.1227 + * is often a pointer to the #PurpleConnection
1.1228 + * instance. For plugins this should be a similar,
1.1229 + * unique memory location. This value is important
1.1230 + * because it allows a request to be closed with
1.1231 + * purple_request_close_with_handle() when, for
1.1232 + * example, you sign offline. If the request is
1.1233 + * <em>not</em> closed it is <strong>very</strong>
1.1234 + * likely to cause a crash whenever the callback
1.1235 + * handler functions are triggered.
1.1236 + * @param title The title of the message, or @c NULL if it should have
1.1237 + * no title.
1.1238 + * @param primary The main point of the message, or @c NULL if you're
1.1239 + * feeling enigmatic.
1.1240 + * @param secondary Secondary information, or @c NULL if there is none.
1.1241 + * @param default_value The default value.
1.1242 + * @param multiline @c TRUE if the inputted text can span multiple lines.
1.1243 + * @param masked @c TRUE if the inputted text should be masked in some
1.1244 + * way (such as by displaying characters as stars). This
1.1245 + * might be because the input is some kind of password.
1.1246 + * @param hint Optionally suggest how the input box should appear.
1.1247 + * Use "html", for example, to allow the user to enter
1.1248 + * HTML.
1.1249 + * @param ok_text The text for the @c OK button, which may not be @c NULL.
1.1250 + * @param ok_cb The callback for the @c OK button, which may not be @c
1.1251 + * NULL.
1.1252 + * @param cancel_text The text for the @c Cancel button, which may not be @c
1.1253 + * NULL.
1.1254 + * @param cancel_cb The callback for the @c Cancel button, which may be
1.1255 + * @c NULL.
1.1256 + * @param account The #PurpleAccount associated with this request, or @c
1.1257 + * NULL if none is.
1.1258 + * @param who The username of the buddy associated with this request,
1.1259 + * or @c NULL if none is.
1.1260 + * @param conv The #PurpleConversation associated with this request, or
1.1261 + * @c NULL if none is.
1.1262 + * @param user_data The data to pass to the callback.
1.1263 + *
1.1264 + * @return A UI-specific handle.
1.1265 + */
1.1266 +void *purple_request_input(void *handle, const char *title, const char *primary,
1.1267 + const char *secondary, const char *default_value, gboolean multiline,
1.1268 + gboolean masked, gchar *hint,
1.1269 + const char *ok_text, GCallback ok_cb,
1.1270 + const char *cancel_text, GCallback cancel_cb,
1.1271 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1272 + void *user_data);
1.1273 +
1.1274 +/**
1.1275 + * Prompts the user for multiple-choice input.
1.1276 + *
1.1277 + * @param handle The plugin or connection handle. For some things this
1.1278 + * is <em>extremely</em> important. See the comments on
1.1279 + * purple_request_input().
1.1280 + * @param title The title of the message, or @c NULL if it should have
1.1281 + * no title.
1.1282 + * @param primary The main point of the message, or @c NULL if you're
1.1283 + * feeling enigmatic.
1.1284 + * @param secondary Secondary information, or @c NULL if there is none.
1.1285 + * @param default_value The default choice; this should be one of the values
1.1286 + * listed in the varargs.
1.1287 + * @param ok_text The text for the @c OK button, which may not be @c NULL.
1.1288 + * @param ok_cb The callback for the @c OK button, which may not be @c
1.1289 + * NULL.
1.1290 + * @param cancel_text The text for the @c Cancel button, which may not be @c
1.1291 + * NULL.
1.1292 + * @param cancel_cb The callback for the @c Cancel button, or @c NULL to
1.1293 + * do nothing.
1.1294 + * @param account The #PurpleAccount associated with this request, or @c
1.1295 + * NULL if none is.
1.1296 + * @param who The username of the buddy associated with this request,
1.1297 + * or @c NULL if none is.
1.1298 + * @param conv The #PurpleConversation associated with this request, or
1.1299 + * @c NULL if none is.
1.1300 + * @param user_data The data to pass to the callback.
1.1301 + * @param ... The choices, which should be pairs of <tt>char *</tt>
1.1302 + * descriptions and <tt>int</tt> values, terminated with a
1.1303 + * @c NULL parameter.
1.1304 + *
1.1305 + * @return A UI-specific handle.
1.1306 + */
1.1307 +void *purple_request_choice(void *handle, const char *title, const char *primary,
1.1308 + const char *secondary, int default_value,
1.1309 + const char *ok_text, GCallback ok_cb,
1.1310 + const char *cancel_text, GCallback cancel_cb,
1.1311 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1312 + void *user_data, ...) G_GNUC_NULL_TERMINATED;
1.1313 +
1.1314 +/**
1.1315 + * <tt>va_list</tt> version of purple_request_choice(); see its documentation.
1.1316 + */
1.1317 +void *purple_request_choice_varg(void *handle, const char *title,
1.1318 + const char *primary, const char *secondary, int default_value,
1.1319 + const char *ok_text, GCallback ok_cb,
1.1320 + const char *cancel_text, GCallback cancel_cb,
1.1321 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1322 + void *user_data, va_list choices);
1.1323 +
1.1324 +/**
1.1325 + * Prompts the user for an action.
1.1326 + *
1.1327 + * This is often represented as a dialog with a button for each action.
1.1328 + *
1.1329 + * @param handle The plugin or connection handle. For some things this
1.1330 + * is <em>extremely</em> important. See the comments on
1.1331 + * purple_request_input().
1.1332 + * @param title The title of the message, or @c NULL if it should have
1.1333 + * no title.
1.1334 + * @param primary The main point of the message, or @c NULL if you're
1.1335 + * feeling enigmatic.
1.1336 + * @param secondary Secondary information, or @c NULL if there is none.
1.1337 + * @param default_action The default action, zero-indexed; if the third action
1.1338 + * supplied should be the default, supply <tt>2</tt>.
1.1339 + * The should be the action that users are most likely
1.1340 + * to select.
1.1341 + * @param account The #PurpleAccount associated with this request, or @c
1.1342 + * NULL if none is.
1.1343 + * @param who The username of the buddy associated with this request,
1.1344 + * or @c NULL if none is.
1.1345 + * @param conv The #PurpleConversation associated with this request, or
1.1346 + * @c NULL if none is.
1.1347 + * @param user_data The data to pass to the callback.
1.1348 + * @param action_count The number of actions.
1.1349 + * @param ... A list of actions. These are pairs of
1.1350 + * arguments. The first of each pair is the
1.1351 + * <tt>char *</tt> label that appears on the button. It
1.1352 + * should have an underscore before the letter you want
1.1353 + * to use as the accelerator key for the button. The
1.1354 + * second of each pair is the #PurpleRequestActionCb
1.1355 + * function to use when the button is clicked.
1.1356 + *
1.1357 + * @return A UI-specific handle.
1.1358 + */
1.1359 +void *purple_request_action(void *handle, const char *title, const char *primary,
1.1360 + const char *secondary, int default_action, PurpleAccount *account,
1.1361 + const char *who, PurpleConversation *conv, void *user_data,
1.1362 + size_t action_count, ...);
1.1363 +
1.1364 +/**
1.1365 + * <tt>va_list</tt> version of purple_request_action(); see its documentation.
1.1366 + */
1.1367 +void *purple_request_action_varg(void *handle, const char *title,
1.1368 + const char *primary, const char *secondary, int default_action,
1.1369 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1370 + void *user_data, size_t action_count, va_list actions);
1.1371 +
1.1372 +/**
1.1373 + * Displays groups of fields for the user to fill in.
1.1374 + *
1.1375 + * @param handle The plugin or connection handle. For some things this
1.1376 + * is <em>extremely</em> important. See the comments on
1.1377 + * purple_request_input().
1.1378 + * @param title The title of the message, or @c NULL if it should have
1.1379 + * no title.
1.1380 + * @param primary The main point of the message, or @c NULL if you're
1.1381 + * feeling enigmatic.
1.1382 + * @param secondary Secondary information, or @c NULL if there is none.
1.1383 + * @param fields The list of fields.
1.1384 + * @param ok_text The text for the @c OK button, which may not be @c NULL.
1.1385 + * @param ok_cb The callback for the @c OK button, which may not be @c
1.1386 + * NULL.
1.1387 + * @param cancel_text The text for the @c Cancel button, which may not be @c
1.1388 + * NULL.
1.1389 + * @param cancel_cb The callback for the @c Cancel button, which may be
1.1390 + * @c NULL.
1.1391 + * @param account The #PurpleAccount associated with this request, or @c
1.1392 + * NULL if none is
1.1393 + * @param who The username of the buddy associated with this request,
1.1394 + * or @c NULL if none is
1.1395 + * @param conv The #PurpleConversation associated with this request, or
1.1396 + * @c NULL if none is
1.1397 + * @param user_data The data to pass to the callback.
1.1398 + *
1.1399 + * @return A UI-specific handle.
1.1400 + */
1.1401 +void *purple_request_fields(void *handle, const char *title, const char *primary,
1.1402 + const char *secondary, PurpleRequestFields *fields,
1.1403 + const char *ok_text, GCallback ok_cb,
1.1404 + const char *cancel_text, GCallback cancel_cb,
1.1405 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1406 + void *user_data);
1.1407 +
1.1408 +/**
1.1409 + * Closes a request.
1.1410 + *
1.1411 + * @param type The request type.
1.1412 + * @param uihandle The request UI handle.
1.1413 + */
1.1414 +void purple_request_close(PurpleRequestType type, void *uihandle);
1.1415 +
1.1416 +/**
1.1417 + * Closes all requests registered with the specified handle.
1.1418 + *
1.1419 + * @param handle The handle, as supplied as the @a handle parameter to one of the
1.1420 + * <tt>purple_request_*</tt> functions.
1.1421 + *
1.1422 + * @see purple_request_input().
1.1423 + */
1.1424 +void purple_request_close_with_handle(void *handle);
1.1425 +
1.1426 +/**
1.1427 + * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.
1.1428 + */
1.1429 +#define purple_request_yes_no(handle, title, primary, secondary, \
1.1430 + default_action, account, who, conv, \
1.1431 + user_data, yes_cb, no_cb) \
1.1432 + purple_request_action((handle), (title), (primary), (secondary), \
1.1433 + (default_action), account, who, conv, (user_data), 2, \
1.1434 + _("_Yes"), (yes_cb), _("_No"), (no_cb))
1.1435 +
1.1436 +/**
1.1437 + * A wrapper for purple_request_action() that uses @c OK and @c Cancel buttons.
1.1438 + */
1.1439 +#define purple_request_ok_cancel(handle, title, primary, secondary, \
1.1440 + default_action, account, who, conv, \
1.1441 + user_data, ok_cb, cancel_cb) \
1.1442 + purple_request_action((handle), (title), (primary), (secondary), \
1.1443 + (default_action), account, who, conv, (user_data), 2, \
1.1444 + _("_OK"), (ok_cb), _("_Cancel"), (cancel_cb))
1.1445 +
1.1446 +/**
1.1447 + * A wrapper for purple_request_action() that uses Accept and Cancel buttons.
1.1448 + */
1.1449 +#define purple_request_accept_cancel(handle, title, primary, secondary, \
1.1450 + default_action, account, who, conv, \
1.1451 + user_data, accept_cb, cancel_cb) \
1.1452 + purple_request_action((handle), (title), (primary), (secondary), \
1.1453 + (default_action), account, who, conv, (user_data), 2, \
1.1454 + _("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
1.1455 +
1.1456 +/**
1.1457 + * Displays a file selector request dialog. Returns the selected filename to
1.1458 + * the callback. Can be used for either opening a file or saving a file.
1.1459 + *
1.1460 + * @param handle The plugin or connection handle. For some things this
1.1461 + * is <em>extremely</em> important. See the comments on
1.1462 + * purple_request_input().
1.1463 + * @param title The title of the message, or @c NULL if it should have
1.1464 + * no title.
1.1465 + * @param filename The default filename (may be @c NULL)
1.1466 + * @param savedialog True if this dialog is being used to save a file.
1.1467 + * False if it is being used to open a file.
1.1468 + * @param ok_cb The callback for the @c OK button.
1.1469 + * @param cancel_cb The callback for the @c Cancel button, which may be @c NULL.
1.1470 + * @param account The #PurpleAccount associated with this request, or @c
1.1471 + * NULL if none is
1.1472 + * @param who The username of the buddy associated with this request,
1.1473 + * or @c NULL if none is
1.1474 + * @param conv The #PurpleConversation associated with this request, or
1.1475 + * @c NULL if none is
1.1476 + * @param user_data The data to pass to the callback.
1.1477 + *
1.1478 + * @return A UI-specific handle.
1.1479 + */
1.1480 +void *purple_request_file(void *handle, const char *title, const char *filename,
1.1481 + gboolean savedialog, GCallback ok_cb, GCallback cancel_cb,
1.1482 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1483 + void *user_data);
1.1484 +
1.1485 +/**
1.1486 + * Displays a folder select dialog. Returns the selected filename to
1.1487 + * the callback.
1.1488 + *
1.1489 + * @param handle The plugin or connection handle. For some things this
1.1490 + * is <em>extremely</em> important. See the comments on
1.1491 + * purple_request_input().
1.1492 + * @param title The title of the message, or @c NULL if it should have
1.1493 + * no title.
1.1494 + * @param dirname The default directory name (may be @c NULL)
1.1495 + * @param ok_cb The callback for the @c OK button.
1.1496 + * @param cancel_cb The callback for the @c Cancel button, which may be @c NULL.
1.1497 + * @param account The #PurpleAccount associated with this request, or @c
1.1498 + * NULL if none is
1.1499 + * @param who The username of the buddy associated with this request,
1.1500 + * or @c NULL if none is
1.1501 + * @param conv The #PurpleConversation associated with this request, or
1.1502 + * @c NULL if none is
1.1503 + * @param user_data The data to pass to the callback.
1.1504 + *
1.1505 + * @return A UI-specific handle.
1.1506 + */
1.1507 +void *purple_request_folder(void *handle, const char *title, const char *dirname,
1.1508 + GCallback ok_cb, GCallback cancel_cb,
1.1509 + PurpleAccount *account, const char *who, PurpleConversation *conv,
1.1510 + void *user_data);
1.1511 +
1.1512 +/*@}*/
1.1513 +
1.1514 +/**************************************************************************/
1.1515 +/** @name UI Registration Functions */
1.1516 +/**************************************************************************/
1.1517 +/*@{*/
1.1518 +
1.1519 +/**
1.1520 + * Sets the UI operations structure to be used when displaying a
1.1521 + * request.
1.1522 + *
1.1523 + * @param ops The UI operations structure.
1.1524 + */
1.1525 +void purple_request_set_ui_ops(PurpleRequestUiOps *ops);
1.1526 +
1.1527 +/**
1.1528 + * Returns the UI operations structure to be used when displaying a
1.1529 + * request.
1.1530 + *
1.1531 + * @return The UI operations structure.
1.1532 + */
1.1533 +PurpleRequestUiOps *purple_request_get_ui_ops(void);
1.1534 +
1.1535 +/*@}*/
1.1536 +
1.1537 +#ifdef __cplusplus
1.1538 +}
1.1539 +#endif
1.1540 +
1.1541 +#endif /* _PURPLE_REQUEST_H_ */