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