Pidgin

request.h File Reference

Request API. More...

#include <stdlib.h>
#include <glib-object.h>
#include <glib.h>
#include "account.h"

Include dependency graph for request.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


Data Structures

struct  PurpleRequestFields
 Multiple fields request data. More...
struct  PurpleRequestFieldGroup
 A group of fields with a title. More...
struct  _PurpleRequestField
 A request field. More...
struct  PurpleRequestUiOps
 Request UI operations. More...

Request API

#define purple_request_yes_no(handle, title, primary, secondary, default_action, account, who, conv, user_data, yes_cb, no_cb)
 A wrapper for purple_request_action() that uses Yes and No buttons.
#define purple_request_ok_cancel(handle, title, primary, secondary, default_action, account, who, conv, user_data, ok_cb, cancel_cb)
 A wrapper for purple_request_action() that uses OK and Cancel buttons.
#define purple_request_accept_cancel(handle, title, primary, secondary, default_action, account, who, conv, user_data, accept_cb, cancel_cb)
 A wrapper for purple_request_action() that uses Accept and Cancel buttons.
void * purple_request_input (void *handle, const char *title, const char *primary, const char *secondary, const char *default_value, gboolean multiline, gboolean masked, gchar *hint, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Prompts the user for text input.
void * purple_request_choice (void *handle, const char *title, const char *primary, const char *secondary, int default_value, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data,...) G_GNUC_NULL_TERMINATED
 Prompts the user for multiple-choice input.
void * purple_request_choice_varg (void *handle, const char *title, const char *primary, const char *secondary, int default_value, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data, va_list choices)
 va_list version of purple_request_choice(); see its documentation.
void * purple_request_action (void *handle, const char *title, const char *primary, const char *secondary, int default_action, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data, size_t action_count,...)
 Prompts the user for an action.
void * purple_request_action_varg (void *handle, const char *title, const char *primary, const char *secondary, int default_action, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data, size_t action_count, va_list actions)
 va_list version of purple_request_action(); see its documentation.
void * purple_request_fields (void *handle, const char *title, const char *primary, const char *secondary, PurpleRequestFields *fields, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Displays groups of fields for the user to fill in.
void purple_request_close (PurpleRequestType type, void *uihandle)
 Closes a request.
void purple_request_close_with_handle (void *handle)
 Closes all requests registered with the specified handle.
void * purple_request_file (void *handle, const char *title, const char *filename, gboolean savedialog, GCallback ok_cb, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Displays a file selector request dialog.
void * purple_request_folder (void *handle, const char *title, const char *dirname, GCallback ok_cb, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Displays a folder select dialog.

Defines

#define PURPLE_DEFAULT_ACTION_NONE   -1

Typedefs

typedef struct _PurpleRequestField PurpleRequestField
typedef void(* PurpleRequestInputCb )(void *, const char *)
typedef void(* PurpleRequestActionCb )(void *, int)
 The type of callbacks passed to purple_request_action().
typedef void(* PurpleRequestChoiceCb )(void *, int)
typedef void(* PurpleRequestFieldsCb )(void *, PurpleRequestFields *fields)
typedef void(* PurpleRequestFileCb )(void *, const char *filename)

Enumerations

enum  PurpleRequestType {
  PURPLE_REQUEST_INPUT = 0, PURPLE_REQUEST_CHOICE, PURPLE_REQUEST_ACTION, PURPLE_REQUEST_FIELDS,
  PURPLE_REQUEST_FILE, PURPLE_REQUEST_FOLDER
}
 Request types. More...
enum  PurpleRequestFieldType {
  PURPLE_REQUEST_FIELD_NONE, PURPLE_REQUEST_FIELD_STRING, PURPLE_REQUEST_FIELD_INTEGER, PURPLE_REQUEST_FIELD_BOOLEAN,
  PURPLE_REQUEST_FIELD_CHOICE, PURPLE_REQUEST_FIELD_LIST, PURPLE_REQUEST_FIELD_LABEL, PURPLE_REQUEST_FIELD_IMAGE,
  PURPLE_REQUEST_FIELD_ACCOUNT
}
 A type of field.

Functions

Field List API
PurpleRequestFields * purple_request_fields_new (void)
 Creates a list of fields to pass to purple_request_fields().
void purple_request_fields_destroy (PurpleRequestFields *fields)
 Destroys a list of fields.
void purple_request_fields_add_group (PurpleRequestFields *fields, PurpleRequestFieldGroup *group)
 Adds a group of fields to the list.
GList * purple_request_fields_get_groups (const PurpleRequestFields *fields)
 Returns a list of all groups in a field list.
gboolean purple_request_fields_exists (const PurpleRequestFields *fields, const char *id)
 Returns whether or not the field with the specified ID exists.
GList * purple_request_fields_get_required (const PurpleRequestFields *fields)
 Returns a list of all required fields.
gboolean purple_request_fields_is_field_required (const PurpleRequestFields *fields, const char *id)
 Returns whether or not a field with the specified ID is required.
gboolean purple_request_fields_all_required_filled (const PurpleRequestFields *fields)
 Returns whether or not all required fields have values.
PurpleRequestField * purple_request_fields_get_field (const PurpleRequestFields *fields, const char *id)
 Return the field with the specified ID.
const char * purple_request_fields_get_string (const PurpleRequestFields *fields, const char *id)
 Returns the string value of a field with the specified ID.
int purple_request_fields_get_integer (const PurpleRequestFields *fields, const char *id)
 Returns the integer value of a field with the specified ID.
gboolean purple_request_fields_get_bool (const PurpleRequestFields *fields, const char *id)
 Returns the boolean value of a field with the specified ID.
int purple_request_fields_get_choice (const PurpleRequestFields *fields, const char *id)
 Returns the choice index of a field with the specified ID.
PurpleAccount * purple_request_fields_get_account (const PurpleRequestFields *fields, const char *id)
 Returns the account of a field with the specified ID.
Fields Group API
PurpleRequestFieldGroup * purple_request_field_group_new (const char *title)
 Creates a fields group with an optional title.
void purple_request_field_group_destroy (PurpleRequestFieldGroup *group)
 Destroys a fields group.
void purple_request_field_group_add_field (PurpleRequestFieldGroup *group, PurpleRequestField *field)
 Adds a field to the group.
const char * purple_request_field_group_get_title (const PurpleRequestFieldGroup *group)
 Returns the title of a fields group.
GList * purple_request_field_group_get_fields (const PurpleRequestFieldGroup *group)
 Returns a list of all fields in a group.
Field API
PurpleRequestField * purple_request_field_new (const char *id, const char *text, PurpleRequestFieldType type)
 Creates a field of the specified type.
void purple_request_field_destroy (PurpleRequestField *field)
 Destroys a field.
void purple_request_field_set_label (PurpleRequestField *field, const char *label)
 Sets the label text of a field.
void purple_request_field_set_visible (PurpleRequestField *field, gboolean visible)
 Sets whether or not a field is visible.
void purple_request_field_set_type_hint (PurpleRequestField *field, const char *type_hint)
 Sets the type hint for the field.
void purple_request_field_set_required (PurpleRequestField *field, gboolean required)
 Sets whether or not a field is required.
PurpleRequestFieldType purple_request_field_get_type (const PurpleRequestField *field)
 Returns the type of a field.
PurpleRequestFieldGroup * purple_request_field_get_group (const PurpleRequestField *field)
 Returns the group for the field.
const char * purple_request_field_get_id (const PurpleRequestField *field)
 Returns the ID of a field.
const char * purple_request_field_get_label (const PurpleRequestField *field)
 Returns the label text of a field.
gboolean purple_request_field_is_visible (const PurpleRequestField *field)
 Returns whether or not a field is visible.
const char * purple_request_field_get_type_hint (const PurpleRequestField *field)
 Returns the field's type hint.
gboolean purple_request_field_is_required (const PurpleRequestField *field)
 Returns whether or not a field is required.
gpointer purple_request_field_get_ui_data (const PurpleRequestField *field)
 Returns the ui_data for a field.
void purple_request_field_set_ui_data (PurpleRequestField *field, gpointer ui_data)
 Sets the ui_data for a field.
String Field API
PurpleRequestField * purple_request_field_string_new (const char *id, const char *text, const char *default_value, gboolean multiline)
 Creates a string request field.
void purple_request_field_string_set_default_value (PurpleRequestField *field, const char *default_value)
 Sets the default value in a string field.
void purple_request_field_string_set_value (PurpleRequestField *field, const char *value)
 Sets the value in a string field.
void purple_request_field_string_set_masked (PurpleRequestField *field, gboolean masked)
 Sets whether or not a string field is masked (commonly used for password fields).
void purple_request_field_string_set_editable (PurpleRequestField *field, gboolean editable)
 Sets whether or not a string field is editable.
const char * purple_request_field_string_get_default_value (const PurpleRequestField *field)
 Returns the default value in a string field.
const char * purple_request_field_string_get_value (const PurpleRequestField *field)
 Returns the user-entered value in a string field.
gboolean purple_request_field_string_is_multiline (const PurpleRequestField *field)
 Returns whether or not a string field is multi-line.
gboolean purple_request_field_string_is_masked (const PurpleRequestField *field)
 Returns whether or not a string field is masked.
gboolean purple_request_field_string_is_editable (const PurpleRequestField *field)
 Returns whether or not a string field is editable.
Integer Field API
PurpleRequestField * purple_request_field_int_new (const char *id, const char *text, int default_value)
 Creates an integer field.
void purple_request_field_int_set_default_value (PurpleRequestField *field, int default_value)
 Sets the default value in an integer field.
void purple_request_field_int_set_value (PurpleRequestField *field, int value)
 Sets the value in an integer field.
int purple_request_field_int_get_default_value (const PurpleRequestField *field)
 Returns the default value in an integer field.
int purple_request_field_int_get_value (const PurpleRequestField *field)
 Returns the user-entered value in an integer field.
Boolean Field API
PurpleRequestField * purple_request_field_bool_new (const char *id, const char *text, gboolean default_value)
 Creates a boolean field.
void purple_request_field_bool_set_default_value (PurpleRequestField *field, gboolean default_value)
 Sets the default value in an boolean field.
void purple_request_field_bool_set_value (PurpleRequestField *field, gboolean value)
 Sets the value in an boolean field.
gboolean purple_request_field_bool_get_default_value (const PurpleRequestField *field)
 Returns the default value in an boolean field.
gboolean purple_request_field_bool_get_value (const PurpleRequestField *field)
 Returns the user-entered value in an boolean field.
Choice Field API
PurpleRequestField * purple_request_field_choice_new (const char *id, const char *text, int default_value)
 Creates a multiple choice field.
void purple_request_field_choice_add (PurpleRequestField *field, const char *label)
 Adds a choice to a multiple choice field.
void purple_request_field_choice_set_default_value (PurpleRequestField *field, int default_value)
 Sets the default value in an choice field.
void purple_request_field_choice_set_value (PurpleRequestField *field, int value)
 Sets the value in an choice field.
int purple_request_field_choice_get_default_value (const PurpleRequestField *field)
 Returns the default value in an choice field.
int purple_request_field_choice_get_value (const PurpleRequestField *field)
 Returns the user-entered value in an choice field.
GList * purple_request_field_choice_get_labels (const PurpleRequestField *field)
 Returns a list of labels in a choice field.
List Field API
PurpleRequestField * purple_request_field_list_new (const char *id, const char *text)
 Creates a multiple list item field.
void purple_request_field_list_set_multi_select (PurpleRequestField *field, gboolean multi_select)
 Sets whether or not a list field allows multiple selection.
gboolean purple_request_field_list_get_multi_select (const PurpleRequestField *field)
 Returns whether or not a list field allows multiple selection.
void * purple_request_field_list_get_data (const PurpleRequestField *field, const char *text)
 Returns the data for a particular item.
void purple_request_field_list_add (PurpleRequestField *field, const char *item, void *data)
 Adds an item to a list field.
void purple_request_field_list_add_selected (PurpleRequestField *field, const char *item)
 Adds a selected item to the list field.
void purple_request_field_list_clear_selected (PurpleRequestField *field)
 Clears the list of selected items in a list field.
void purple_request_field_list_set_selected (PurpleRequestField *field, GList *items)
 Sets a list of selected items in a list field.
gboolean purple_request_field_list_is_selected (const PurpleRequestField *field, const char *item)
 Returns whether or not a particular item is selected in a list field.
GList * purple_request_field_list_get_selected (const PurpleRequestField *field)
 Returns a list of selected items in a list field.
GList * purple_request_field_list_get_items (const PurpleRequestField *field)
 Returns a list of items in a list field.
Label Field API
PurpleRequestField * purple_request_field_label_new (const char *id, const char *text)
 Creates a label field.
Image Field API
PurpleRequestField * purple_request_field_image_new (const char *id, const char *text, const char *buf, gsize size)
 Creates an image field.
void purple_request_field_image_set_scale (PurpleRequestField *field, unsigned int x, unsigned int y)
 Sets the scale factors of an image field.
const char * purple_request_field_image_get_buffer (PurpleRequestField *field)
 Returns pointer to the image.
gsize purple_request_field_image_get_size (PurpleRequestField *field)
 Returns size (in bytes) of the image.
unsigned int purple_request_field_image_get_scale_x (PurpleRequestField *field)
 Returns X scale coefficient of the image.
unsigned int purple_request_field_image_get_scale_y (PurpleRequestField *field)
 Returns Y scale coefficient of the image.
Account Field API
PurpleRequestField * purple_request_field_account_new (const char *id, const char *text, PurpleAccount *account)
 Creates an account field.
void purple_request_field_account_set_default_value (PurpleRequestField *field, PurpleAccount *default_value)
 Sets the default account on an account field.
void purple_request_field_account_set_value (PurpleRequestField *field, PurpleAccount *value)
 Sets the account in an account field.
void purple_request_field_account_set_show_all (PurpleRequestField *field, gboolean show_all)
 Sets whether or not to show all accounts in an account field.
void purple_request_field_account_set_filter (PurpleRequestField *field, PurpleFilterAccountFunc filter_func)
 Sets the account filter function in an account field.
PurpleAccount * purple_request_field_account_get_default_value (const PurpleRequestField *field)
 Returns the default account in an account field.
PurpleAccount * purple_request_field_account_get_value (const PurpleRequestField *field)
 Returns the user-entered account in an account field.
gboolean purple_request_field_account_get_show_all (const PurpleRequestField *field)
 Returns whether or not to show all accounts in an account field.
PurpleFilterAccountFunc purple_request_field_account_get_filter (const PurpleRequestField *field)
 Returns the account filter function in an account field.
UI Registration Functions
void purple_request_set_ui_ops (PurpleRequestUiOps *ops)
 Sets the UI operations structure to be used when displaying a request.
PurpleRequestUiOps * purple_request_get_ui_ops (void)
 Returns the UI operations structure to be used when displaying a request.

Detailed Description

Request API.

Definition in file request.h.

Define Documentation

#define purple_request_accept_cancel ( handle,
title,
primary,
secondary,
default_action,
account,
who,
conv,
user_data,
accept_cb,
cancel_cb   ) 

Value:

purple_request_action((handle), (title), (primary), (secondary), \
                        (default_action), account, who, conv, (user_data), 2, \
                        _("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
A wrapper for purple_request_action() that uses Accept and Cancel buttons.

Definition at line 1448 of file request.h.

#define purple_request_ok_cancel ( handle,
title,
primary,
secondary,
default_action,
account,
who,
conv,
user_data,
ok_cb,
cancel_cb   ) 

Value:

purple_request_action((handle), (title), (primary), (secondary), \
                        (default_action), account, who, conv, (user_data), 2, \
                        _("_OK"), (ok_cb), _("_Cancel"), (cancel_cb))
A wrapper for purple_request_action() that uses OK and Cancel buttons.

Definition at line 1438 of file request.h.

#define purple_request_yes_no ( handle,
title,
primary,
secondary,
default_action,
account,
who,
conv,
user_data,
yes_cb,
no_cb   ) 

Value:

purple_request_action((handle), (title), (primary), (secondary), \
                        (default_action), account, who, conv, (user_data), 2, \
                        _("_Yes"), (yes_cb), _("_No"), (no_cb))
A wrapper for purple_request_action() that uses Yes and No buttons.

Definition at line 1428 of file request.h.

Typedef Documentation

typedef void(* PurpleRequestActionCb)(void *, int)

The type of callbacks passed to purple_request_action().

The first argument is the user_data parameter; the second is the index in the list of actions of the one chosen.

Definition at line 251 of file request.h.

typedef struct _PurpleRequestField PurpleRequestField

A request field.

Definition at line 34 of file request.h.

Enumeration Type Documentation

enum PurpleRequestType

Request types.

Enumerator:
PURPLE_REQUEST_INPUT  Text input request.

PURPLE_REQUEST_CHOICE  Multiple-choice request.

PURPLE_REQUEST_ACTION  Action request.

PURPLE_REQUEST_FIELDS  Multiple fields request.

PURPLE_REQUEST_FILE  File open or save request.

PURPLE_REQUEST_FOLDER  Folder selection request.

Definition at line 43 of file request.h.

Function Documentation

void* purple_request_action ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
int  default_action,
PurpleAccount *  account,
const char *  who,
PurpleConversation *  conv,
void *  user_data,
size_t  action_count,
  ... 
)

Prompts the user for an action.

This is often represented as a dialog with a button for each action.

Parameters:
handle The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
title The title of the message, or NULL if it should have no title.
primary The main point of the message, or NULL if you're feeling enigmatic.
secondary Secondary information, or NULL if there is none.
default_action The default action, zero-indexed; if the third action supplied should be the default, supply 2. The should be the action that users are most likely to select.
account The PurpleAccount associated with this request, or NULL if none is.
who The username of the buddy associated with this request, or NULL if none is.
conv The PurpleConversation associated with this request, or NULL if none is.
user_data The data to pass to the callback.
action_count The number of actions.
... A list of actions. These are pairs of arguments. The first of each pair is the char * label that appears on the button. It should have an underscore before the letter you want to use as the accelerator key for the button. The second of each pair is the PurpleRequestActionCb function to use when the button is clicked.
Returns:
A UI-specific handle.

void* purple_request_choice ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
int  default_value,
const char *  ok_text,
GCallback  ok_cb,
const char *  cancel_text,
GCallback  cancel_cb,
PurpleAccount *  account,
const char *  who,
PurpleConversation *  conv,
void *  user_data,
  ... 
)

Prompts the user for multiple-choice input.

Parameters:
handle The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
title The title of the message, or NULL if it should have no title.
primary The main point of the message, or NULL if you're feeling enigmatic.
secondary Secondary information, or NULL if there is none.
default_value The default choice; this should be one of the values listed in the varargs.
ok_text The text for the OK button, which may not be NULL.
ok_cb The callback for the OK button, which may not be NULL.
cancel_text The text for the Cancel button, which may not be NULL.
cancel_cb The callback for the Cancel button, or NULL to do nothing.
account The PurpleAccount associated with this request, or NULL if none is.
who The username of the buddy associated with this request, or NULL if none is.
conv The PurpleConversation associated with this request, or NULL if none is.
user_data The data to pass to the callback.
... The choices, which should be pairs of char * descriptions and int values, terminated with a NULL parameter.
Returns:
A UI-specific handle.

void purple_request_close ( PurpleRequestType  type,
void *  uihandle 
)

Closes a request.

Parameters:
type The request type.
uihandle The request UI handle.

void purple_request_close_with_handle ( void *  handle  ) 

Closes all requests registered with the specified handle.

Parameters:
handle The handle, as supplied as the handle parameter to one of the purple_request_* functions.
See also:
purple_request_input().

PurpleAccount* purple_request_field_account_get_default_value ( const PurpleRequestField *  field  ) 

Returns the default account in an account field.

Parameters:
field The field.
Returns:
The default account.

PurpleFilterAccountFunc purple_request_field_account_get_filter ( const PurpleRequestField *  field  ) 

Returns the account filter function in an account field.

This function will determine which accounts get displayed and which don't.

Parameters:
field The account field.
Returns:
The account filter function.

gboolean purple_request_field_account_get_show_all ( const PurpleRequestField *  field  ) 

Returns whether or not to show all accounts in an account field.

If TRUE, all accounts, online or offline, will be shown. If FALSE, only online accounts will be shown.

Parameters:
field The account field.
Returns:
Whether or not to show all accounts.

PurpleAccount* purple_request_field_account_get_value ( const PurpleRequestField *  field  ) 

Returns the user-entered account in an account field.

Parameters:
field The field.
Returns:
The user-entered account.

PurpleRequestField* purple_request_field_account_new ( const char *  id,
const char *  text,
PurpleAccount *  account 
)

Creates an account field.

By default, this field will not show offline accounts.

Parameters:
id The field ID.
text The text label of the field.
account The optional default account.
Returns:
The new field.

void purple_request_field_account_set_default_value ( PurpleRequestField *  field,
PurpleAccount *  default_value 
)

Sets the default account on an account field.

Parameters:
field The account field.
default_value The default account.

void purple_request_field_account_set_filter ( PurpleRequestField *  field,
PurpleFilterAccountFunc  filter_func 
)

Sets the account filter function in an account field.

This function will determine which accounts get displayed and which don't.

Parameters:
field The account field.
filter_func The account filter function.

void purple_request_field_account_set_show_all ( PurpleRequestField *  field,
gboolean  show_all 
)

Sets whether or not to show all accounts in an account field.

If TRUE, all accounts, online or offline, will be shown. If FALSE, only online accounts will be shown.

Parameters:
field The account field.
show_all Whether or not to show all accounts.

void purple_request_field_account_set_value ( PurpleRequestField *  field,
PurpleAccount *  value 
)

Sets the account in an account field.

Parameters:
field The account field.
value The account.

gboolean purple_request_field_bool_get_default_value ( const PurpleRequestField *  field  ) 

Returns the default value in an boolean field.

Parameters:
field The field.
Returns:
The default value.

gboolean purple_request_field_bool_get_value ( const PurpleRequestField *  field  ) 

Returns the user-entered value in an boolean field.

Parameters:
field The field.
Returns:
The value.

PurpleRequestField* purple_request_field_bool_new ( const char *  id,
const char *  text,
gboolean  default_value 
)

Creates a boolean field.

This is often represented as a checkbox.

Parameters:
id The field ID.
text The text label of the field.
default_value The default value.
Returns:
The new field.

void purple_request_field_bool_set_default_value ( PurpleRequestField *  field,
gboolean  default_value 
)

Sets the default value in an boolean field.

Parameters:
field The field.
default_value The default value.

void purple_request_field_bool_set_value ( PurpleRequestField *  field,
gboolean  value 
)

Sets the value in an boolean field.

Parameters:
field The field.
value The value.

void purple_request_field_choice_add ( PurpleRequestField *  field,
const char *  label 
)

Adds a choice to a multiple choice field.

Parameters:
field The choice field.
label The choice label.

int purple_request_field_choice_get_default_value ( const PurpleRequestField *  field  ) 

Returns the default value in an choice field.

Parameters:
field The field.
Returns:
The default value.

GList* purple_request_field_choice_get_labels ( const PurpleRequestField *  field  ) 

Returns a list of labels in a choice field.

Parameters:
field The field.
Note:
The return value of this function must not be modified or freed.
Returns:
The list of labels.

int purple_request_field_choice_get_value ( const PurpleRequestField *  field  ) 

Returns the user-entered value in an choice field.

Parameters:
field The field.
Returns:
The value.

PurpleRequestField* purple_request_field_choice_new ( const char *  id,
const char *  text,
int  default_value 
)

Creates a multiple choice field.

This is often represented as a group of radio buttons.

Parameters:
id The field ID.
text The optional label of the field.
default_value The default choice.
Returns:
The new field.

void purple_request_field_choice_set_default_value ( PurpleRequestField *  field,
int  default_value 
)

Sets the default value in an choice field.

Parameters:
field The field.
default_value The default value.

void purple_request_field_choice_set_value ( PurpleRequestField *  field,
int  value 
)

Sets the value in an choice field.

Parameters:
field The field.
value The value.

void purple_request_field_destroy ( PurpleRequestField *  field  ) 

Destroys a field.

Parameters:
field The field to destroy.

PurpleRequestFieldGroup* purple_request_field_get_group ( const PurpleRequestField *  field  ) 

Returns the group for the field.

Parameters:
field The field.
Returns:
The UI data.
Since:
2.6.0

const char* purple_request_field_get_id ( const PurpleRequestField *  field  ) 

Returns the ID of a field.

Parameters:
field The field.
Returns:
The ID

const char* purple_request_field_get_label ( const PurpleRequestField *  field  ) 

Returns the label text of a field.

Parameters:
field The field.
Returns:
The label text.

PurpleRequestFieldType purple_request_field_get_type ( const PurpleRequestField *  field  ) 

Returns the type of a field.

Parameters:
field The field.
Returns:
The field's type.

const char* purple_request_field_get_type_hint ( const PurpleRequestField *  field  ) 

Returns the field's type hint.

Parameters:
field The field.
Returns:
The field's type hint.

gpointer purple_request_field_get_ui_data ( const PurpleRequestField *  field  ) 

Returns the ui_data for a field.

Parameters:
field The field.
Returns:
The UI data.
Since:
2.6.0

void purple_request_field_group_add_field ( PurpleRequestFieldGroup *  group,
PurpleRequestField *  field 
)

Adds a field to the group.

Parameters:
group The group to add the field to.
field The field to add to the group.

void purple_request_field_group_destroy ( PurpleRequestFieldGroup *  group  ) 

Destroys a fields group.

Parameters:
group The group to destroy.

GList* purple_request_field_group_get_fields ( const PurpleRequestFieldGroup *  group  ) 

Returns a list of all fields in a group.

Parameters:
group The group.
Note:
The return value of this function must not be modified or freed.
Returns:
The list of fields in the group.

const char* purple_request_field_group_get_title ( const PurpleRequestFieldGroup *  group  ) 

Returns the title of a fields group.

Parameters:
group The group.
Returns:
The title, if set.

PurpleRequestFieldGroup* purple_request_field_group_new ( const char *  title  ) 

Creates a fields group with an optional title.

Parameters:
title The optional title to give the group.
Returns:
A new fields group

const char* purple_request_field_image_get_buffer ( PurpleRequestField *  field  ) 

Returns pointer to the image.

Parameters:
field The image field.
Returns:
Pointer to the image.

unsigned int purple_request_field_image_get_scale_x ( PurpleRequestField *  field  ) 

Returns X scale coefficient of the image.

Parameters:
field The image field.
Returns:
X scale coefficient of the image.

unsigned int purple_request_field_image_get_scale_y ( PurpleRequestField *  field  ) 

Returns Y scale coefficient of the image.

Parameters:
field The image field.
Returns:
Y scale coefficient of the image.

gsize purple_request_field_image_get_size ( PurpleRequestField *  field  ) 

Returns size (in bytes) of the image.

Parameters:
field The image field.
Returns:
Size of the image.

PurpleRequestField* purple_request_field_image_new ( const char *  id,
const char *  text,
const char *  buf,
gsize  size 
)

Creates an image field.

Parameters:
id The field ID.
text The label of the field.
buf The image data.
size The size of the data in buffer.
Returns:
The new field.

void purple_request_field_image_set_scale ( PurpleRequestField *  field,
unsigned int  x,
unsigned int  y 
)

Sets the scale factors of an image field.

Parameters:
field The image field.
x The x scale factor.
y The y scale factor.

int purple_request_field_int_get_default_value ( const PurpleRequestField *  field  ) 

Returns the default value in an integer field.

Parameters:
field The field.
Returns:
The default value.

int purple_request_field_int_get_value ( const PurpleRequestField *  field  ) 

Returns the user-entered value in an integer field.

Parameters:
field The field.
Returns:
The value.

PurpleRequestField* purple_request_field_int_new ( const char *  id,
const char *  text,
int  default_value 
)

Creates an integer field.

Parameters:
id The field ID.
text The text label of the field.
default_value The default value.
Returns:
The new field.

void purple_request_field_int_set_default_value ( PurpleRequestField *  field,
int  default_value 
)

Sets the default value in an integer field.

Parameters:
field The field.
default_value The default value.

void purple_request_field_int_set_value ( PurpleRequestField *  field,
int  value 
)

Sets the value in an integer field.

Parameters:
field The field.
value The value.

gboolean purple_request_field_is_required ( const PurpleRequestField *  field  ) 

Returns whether or not a field is required.

Parameters:
field The field.
Returns:
TRUE if the field is required, or FALSE.

gboolean purple_request_field_is_visible ( const PurpleRequestField *  field  ) 

Returns whether or not a field is visible.

Parameters:
field The field.
Returns:
TRUE if the field is visible. FALSE otherwise.

PurpleRequestField* purple_request_field_label_new ( const char *  id,
const char *  text 
)

Creates a label field.

Parameters:
id The field ID.
text The label of the field.
Returns:
The new field.

void purple_request_field_list_add ( PurpleRequestField *  field,
const char *  item,
void *  data 
)

Adds an item to a list field.

Parameters:
field The list field.
item The list item.
data The associated data.

void purple_request_field_list_add_selected ( PurpleRequestField *  field,
const char *  item 
)

Adds a selected item to the list field.

Parameters:
field The field.
item The item to add.

void purple_request_field_list_clear_selected ( PurpleRequestField *  field  ) 

Clears the list of selected items in a list field.

Parameters:
field The field.

void* purple_request_field_list_get_data ( const PurpleRequestField *  field,
const char *  text 
)

Returns the data for a particular item.

Parameters:
field The list field.
text The item text.
Returns:
The data associated with the item.

GList* purple_request_field_list_get_items ( const PurpleRequestField *  field  ) 

Returns a list of items in a list field.

Parameters:
field The field.
Note:
The return value of this function must not be modified or freed.
Returns:
The list of items.

gboolean purple_request_field_list_get_multi_select ( const PurpleRequestField *  field  ) 

Returns whether or not a list field allows multiple selection.

Parameters:
field The list field.
Returns:
TRUE if multiple selection is enabled, or FALSE otherwise.

GList* purple_request_field_list_get_selected ( const PurpleRequestField *  field  ) 

Returns a list of selected items in a list field.

To retrieve the data for each item, use purple_request_field_list_get_data().

Parameters:
field The field.
Note:
The return value of this function must not be modified or freed.
Returns:
The list of selected items.

gboolean purple_request_field_list_is_selected ( const PurpleRequestField *  field,
const char *  item 
)

Returns whether or not a particular item is selected in a list field.

Parameters:
field The field.
item The item.
Returns:
TRUE if the item is selected. FALSE otherwise.

PurpleRequestField* purple_request_field_list_new ( const char *  id,
const char *  text 
)

Creates a multiple list item field.

Parameters:
id The field ID.
text The optional label of the field.
Returns:
The new field.

void purple_request_field_list_set_multi_select ( PurpleRequestField *  field,
gboolean  multi_select 
)

Sets whether or not a list field allows multiple selection.

Parameters:
field The list field.
multi_select TRUE if multiple selection is enabled, or FALSE otherwise.

void purple_request_field_list_set_selected ( PurpleRequestField *  field,
GList *  items 
)

Sets a list of selected items in a list field.

Parameters:
field The field.
items The list of selected items, which is not modified or freed.

PurpleRequestField* purple_request_field_new ( const char *  id,
const char *  text,
PurpleRequestFieldType  type 
)

Creates a field of the specified type.

Parameters:
id The field ID.
text The text label of the field.
type The type of field.
Returns:
The new field.

void purple_request_field_set_label ( PurpleRequestField *  field,
const char *  label 
)

Sets the label text of a field.

Parameters:
field The field.
label The text label.

void purple_request_field_set_required ( PurpleRequestField *  field,
gboolean  required 
)

Sets whether or not a field is required.

Parameters:
field The field.
required TRUE if required, or FALSE.

void purple_request_field_set_type_hint ( PurpleRequestField *  field,
const char *  type_hint 
)

Sets the type hint for the field.

This is optionally used by the UIs to provide such features as auto-completion for type hints like "account" and "screenname".

Parameters:
field The field.
type_hint The type hint.

void purple_request_field_set_ui_data ( PurpleRequestField *  field,
gpointer  ui_data 
)

Sets the ui_data for a field.

Parameters:
field The field.
ui_data The UI data.
Returns:
The UI data.
Since:
2.6.0

void purple_request_field_set_visible ( PurpleRequestField *  field,
gboolean  visible 
)

Sets whether or not a field is visible.

Parameters:
field The field.
visible TRUE if visible, or FALSE if not.

const char* purple_request_field_string_get_default_value ( const PurpleRequestField *  field  ) 

Returns the default value in a string field.

Parameters:
field The field.
Returns:
The default value.

const char* purple_request_field_string_get_value ( const PurpleRequestField *  field  ) 

Returns the user-entered value in a string field.

Parameters:
field The field.
Returns:
The value.

gboolean purple_request_field_string_is_editable ( const PurpleRequestField *  field  ) 

Returns whether or not a string field is editable.

Parameters:
field The field.
Returns:
TRUE if the field is editable, or FALSE otherwise.

gboolean purple_request_field_string_is_masked ( const PurpleRequestField *  field  ) 

Returns whether or not a string field is masked.

Parameters:
field The field.
Returns:
TRUE if the field is masked, or FALSE otherwise.

gboolean purple_request_field_string_is_multiline ( const PurpleRequestField *  field  ) 

Returns whether or not a string field is multi-line.

Parameters:
field The field.
Returns:
TRUE if the field is mulit-line, or FALSE otherwise.

PurpleRequestField* purple_request_field_string_new ( const char *  id,
const char *  text,
const char *  default_value,
gboolean  multiline 
)

Creates a string request field.

Parameters:
id The field ID.
text The text label of the field.
default_value The optional default value.
multiline Whether or not this should be a multiline string.
Returns:
The new field.

void purple_request_field_string_set_default_value ( PurpleRequestField *  field,
const char *  default_value 
)

Sets the default value in a string field.

Parameters:
field The field.
default_value The default value.

void purple_request_field_string_set_editable ( PurpleRequestField *  field,
gboolean  editable 
)

Sets whether or not a string field is editable.

Parameters:
field The field.
editable The editable value.

void purple_request_field_string_set_masked ( PurpleRequestField *  field,
gboolean  masked 
)

Sets whether or not a string field is masked (commonly used for password fields).

Parameters:
field The field.
masked The masked value.

void purple_request_field_string_set_value ( PurpleRequestField *  field,
const char *  value 
)

Sets the value in a string field.

Parameters:
field The field.
value The value.

void* purple_request_fields ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
PurpleRequestFields *  fields,
const char *  ok_text,
GCallback  ok_cb,
const char *  cancel_text,
GCallback  cancel_cb,
PurpleAccount *  account,
const char *  who,
PurpleConversation *  conv,
void *  user_data 
)

Displays groups of fields for the user to fill in.

Parameters:
handle The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
title The title of the message, or NULL if it should have no title.
primary The main point of the message, or NULL if you're feeling enigmatic.
secondary Secondary information, or NULL if there is none.
fields The list of fields.
ok_text The text for the OK button, which may not be NULL.
ok_cb The callback for the OK button, which may not be NULL.
cancel_text The text for the Cancel button, which may not be NULL.
cancel_cb The callback for the Cancel button, which may be NULL.
account The PurpleAccount associated with this request, or NULL if none is
who The username of the buddy associated with this request, or NULL if none is
conv The PurpleConversation associated with this request, or NULL if none is
user_data The data to pass to the callback.
Returns:
A UI-specific handle.

void purple_request_fields_add_group ( PurpleRequestFields *  fields,
PurpleRequestFieldGroup *  group 
)

Adds a group of fields to the list.

Parameters:
fields The fields list.
group The group to add.

gboolean purple_request_fields_all_required_filled ( const PurpleRequestFields *  fields  ) 

Returns whether or not all required fields have values.

Parameters:
fields The fields list.
Returns:
TRUE if all required fields have values, or FALSE.

void purple_request_fields_destroy ( PurpleRequestFields *  fields  ) 

Destroys a list of fields.

Parameters:
fields The list of fields to destroy.

gboolean purple_request_fields_exists ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns whether or not the field with the specified ID exists.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
TRUE if the field exists, or FALSE.

PurpleAccount* purple_request_fields_get_account ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns the account of a field with the specified ID.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
The account value, if found, or NULL otherwise.

gboolean purple_request_fields_get_bool ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns the boolean value of a field with the specified ID.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
The boolean value, if found, or FALSE otherwise.

int purple_request_fields_get_choice ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns the choice index of a field with the specified ID.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
The choice index, if found, or -1 otherwise.

PurpleRequestField* purple_request_fields_get_field ( const PurpleRequestFields *  fields,
const char *  id 
)

Return the field with the specified ID.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
The field, if found.

GList* purple_request_fields_get_groups ( const PurpleRequestFields *  fields  ) 

Returns a list of all groups in a field list.

Parameters:
fields The fields list.
Note:
The return value of this function must not be modified or freed.
Returns:
A list of groups.

int purple_request_fields_get_integer ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns the integer value of a field with the specified ID.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
The integer value, if found, or 0 otherwise.

GList* purple_request_fields_get_required ( const PurpleRequestFields *  fields  ) 

Returns a list of all required fields.

Parameters:
fields The fields list.
Note:
The return value of this function must not be modified or freed.
Returns:
The list of required fields.

const char* purple_request_fields_get_string ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns the string value of a field with the specified ID.

Parameters:
fields The fields list.
id The ID of the field.
Returns:
The string value, if found, or NULL otherwise.

gboolean purple_request_fields_is_field_required ( const PurpleRequestFields *  fields,
const char *  id 
)

Returns whether or not a field with the specified ID is required.

Parameters:
fields The fields list.
id The field ID.
Returns:
TRUE if the specified field is required, or FALSE.

PurpleRequestFields* purple_request_fields_new ( void   ) 

Creates a list of fields to pass to purple_request_fields().

Returns:
A PurpleRequestFields structure.

void* purple_request_file ( void *  handle,
const char *  title,
const char *  filename,
gboolean  savedialog,
GCallback  ok_cb,
GCallback  cancel_cb,
PurpleAccount *  account,
const char *  who,
PurpleConversation *  conv,
void *  user_data 
)

Displays a file selector request dialog.

Returns the selected filename to the callback. Can be used for either opening a file or saving a file.

Parameters:
handle The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
title The title of the message, or NULL if it should have no title.
filename The default filename (may be NULL)
savedialog True if this dialog is being used to save a file. False if it is being used to open a file.
ok_cb The callback for the OK button.
cancel_cb The callback for the Cancel button, which may be NULL.
account The PurpleAccount associated with this request, or NULL if none is
who The username of the buddy associated with this request, or NULL if none is
conv The PurpleConversation associated with this request, or NULL if none is
user_data The data to pass to the callback.
Returns:
A UI-specific handle.

void* purple_request_folder ( void *  handle,
const char *  title,
const char *  dirname,
GCallback  ok_cb,
GCallback  cancel_cb,
PurpleAccount *  account,
const char *  who,
PurpleConversation *  conv,
void *  user_data 
)

Displays a folder select dialog.

Returns the selected filename to the callback.

Parameters:
handle The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
title The title of the message, or NULL if it should have no title.
dirname The default directory name (may be NULL)
ok_cb The callback for the OK button.
cancel_cb The callback for the Cancel button, which may be NULL.
account The PurpleAccount associated with this request, or NULL if none is
who The username of the buddy associated with this request, or NULL if none is
conv The PurpleConversation associated with this request, or NULL if none is
user_data The data to pass to the callback.
Returns:
A UI-specific handle.

PurpleRequestUiOps* purple_request_get_ui_ops ( void   ) 

Returns the UI operations structure to be used when displaying a request.

Returns:
The UI operations structure.

void* purple_request_input ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
const char *  default_value,
gboolean  multiline,
gboolean  masked,
gchar *  hint,
const char *  ok_text,
GCallback  ok_cb,
const char *  cancel_text,
GCallback  cancel_cb,
PurpleAccount *  account,
const char *  who,
PurpleConversation *  conv,
void *  user_data 
)

Prompts the user for text input.

Parameters:
handle The plugin or connection handle. For some things this is extremely important. The handle is used to programmatically close the request dialog when it is no longer needed. For PRPLs this is often a pointer to the PurpleConnection instance. For plugins this should be a similar, unique memory location. This value is important because it allows a request to be closed with purple_request_close_with_handle() when, for example, you sign offline. If the request is not closed it is very likely to cause a crash whenever the callback handler functions are triggered.
title The title of the message, or NULL if it should have no title.
primary The main point of the message, or NULL if you're feeling enigmatic.
secondary Secondary information, or NULL if there is none.
default_value The default value.
multiline TRUE if the inputted text can span multiple lines.
masked TRUE if the inputted text should be masked in some way (such as by displaying characters as stars). This might be because the input is some kind of password.
hint Optionally suggest how the input box should appear. Use "html", for example, to allow the user to enter HTML.
ok_text The text for the OK button, which may not be NULL.
ok_cb The callback for the OK button, which may not be NULL.
cancel_text The text for the Cancel button, which may not be NULL.
cancel_cb The callback for the Cancel button, which may be NULL.
account The PurpleAccount associated with this request, or NULL if none is.
who The username of the buddy associated with this request, or NULL if none is.
conv The PurpleConversation associated with this request, or NULL if none is.
user_data The data to pass to the callback.
Returns:
A UI-specific handle.

void purple_request_set_ui_ops ( PurpleRequestUiOps *  ops  ) 

Sets the UI operations structure to be used when displaying a request.

Parameters:
ops The UI operations structure.