--- a/libpurple/request.h Fri Jan 31 20:57:38 2014 +0530
+++ b/libpurple/request.h Sat Feb 01 00:58:34 2014 +0530
@@ -35,21 +35,29 @@
#include "request-datasheet.h"
/**
+ * PurpleRequestField:
+ *
* A request field.
*/
typedef struct _PurpleRequestField PurpleRequestField;
/**
+ * PurpleRequestFields:
+ *
* Multiple fields request data.
*/
typedef struct _PurpleRequestFields PurpleRequestFields;
/**
+ * PurpleRequestFieldGroup:
+ *
* A group of fields with a title.
*/
typedef struct _PurpleRequestFieldGroup PurpleRequestFieldGroup;
/**
+ * PurpleRequestCommonParameters:
+ *
* Common parameters for UI operations.
*/
typedef struct _PurpleRequestCommonParameters PurpleRequestCommonParameters;
@@ -59,21 +67,32 @@
#define PURPLE_DEFAULT_ACTION_NONE -1
/**
+ * PurpleRequestType:
+ * @PURPLE_REQUEST_INPUT: Text input request.
+ * @PURPLE_REQUEST_CHOICE: Multiple-choice request.
+ * @PURPLE_REQUEST_ACTION: Action request.
+ * @PURPLE_REQUEST_WAIT: Please wait dialog.
+ * @PURPLE_REQUEST_FIELDS: Multiple fields request.
+ * @PURPLE_REQUEST_FILE: File open or save request.
+ * @PURPLE_REQUEST_FOLDER: Folder selection request.
+ *
* Request types.
*/
typedef enum
{
- PURPLE_REQUEST_INPUT = 0, /**< Text input request. */
- PURPLE_REQUEST_CHOICE, /**< Multiple-choice request. */
- PURPLE_REQUEST_ACTION, /**< Action request. */
- PURPLE_REQUEST_WAIT, /**< Please wait dialog. */
- PURPLE_REQUEST_FIELDS, /**< Multiple fields request. */
- PURPLE_REQUEST_FILE, /**< File open or save request. */
- PURPLE_REQUEST_FOLDER /**< Folder selection request. */
+ PURPLE_REQUEST_INPUT = 0,
+ PURPLE_REQUEST_CHOICE,
+ PURPLE_REQUEST_ACTION,
+ PURPLE_REQUEST_WAIT,
+ PURPLE_REQUEST_FIELDS,
+ PURPLE_REQUEST_FILE,
+ PURPLE_REQUEST_FOLDER
} PurpleRequestType;
/**
+ * PurpleRequestFieldType:
+ *
* A type of field.
*/
typedef enum
@@ -111,6 +130,8 @@
typedef void (*PurpleRequestCancelCb)(gpointer);
/**
+ * PurpleRequestUiOps:
+ *
* Request UI operations.
*/
typedef struct
@@ -184,11 +205,15 @@
typedef gboolean (*PurpleRequestFieldSensitivityCb)(PurpleRequestField *field);
-/** The type of callbacks passed to purple_request_action(). The first
- * argument is the @a user_data parameter; the second is the index in the list
- * of actions of the one chosen.
+/**
+ * PurpleRequestActionCb:
+ *
+ * The type of callbacks passed to purple_request_action(). The first
+ * argument is the <tt>user_data</tt> parameter; the second is the index in the
+ * list of actions of the one chosen.
*/
typedef void (*PurpleRequestActionCb)(void *, int);
+
typedef void (*PurpleRequestChoiceCb)(void *, gpointer);
typedef void (*PurpleRequestFieldsCb)(void *, PurpleRequestFields *fields);
typedef void (*PurpleRequestFileCb)(void *, const char *filename);
@@ -202,6 +227,8 @@
/*@{*/
/**
+ * purple_request_cpar_new:
+ *
* Creates new parameters set for the request, which may or may not be used by
* the UI to display the request.
*
@@ -211,6 +238,8 @@
purple_request_cpar_new(void);
/**
+ * purple_request_cpar_from_connection:
+ *
* Creates new parameters set initially bound with the #PurpleConnection.
*
* Returns: The new parameters set.
@@ -219,6 +248,8 @@
purple_request_cpar_from_connection(PurpleConnection *gc);
/**
+ * purple_request_cpar_from_account:
+ *
* Creates new parameters set initially bound with the #PurpleAccount.
*
* Returns: The new parameters set.
@@ -227,6 +258,8 @@
purple_request_cpar_from_account(PurpleAccount *account);
/**
+ * purple_request_cpar_from_conversation:
+ *
* Creates new parameters set initially bound with the #PurpleConversation.
*
* Returns: The new parameters set.
@@ -234,40 +267,44 @@
PurpleRequestCommonParameters *
purple_request_cpar_from_conversation(PurpleConversation *conv);
-/*
+/**
+ * purple_request_cpar_ref:
+ * @cpar: The object to ref.
+ *
* Increases the reference count on the parameters set.
- *
- * @cpar: The object to ref.
*/
void
purple_request_cpar_ref(PurpleRequestCommonParameters *cpar);
/**
+ * purple_request_cpar_unref:
+ * @cpar: The parameters set object to unref and possibly destroy.
+ *
* Decreases the reference count on the parameters set.
*
* The object will be destroyed when this reaches 0.
*
- * @cpar: The parameters set object to unref and possibly destroy.
- *
* Returns: The NULL, if object was destroyed, cpar otherwise.
*/
PurpleRequestCommonParameters *
purple_request_cpar_unref(PurpleRequestCommonParameters *cpar);
/**
- * Sets the #PurpleAccount associated with the request, or %NULL, if none is.
- *
+ * purple_request_cpar_set_account:
* @cpar: The parameters set.
* @account: The #PurpleAccount to associate.
+ *
+ * Sets the #PurpleAccount associated with the request, or %NULL, if none is.
*/
void
purple_request_cpar_set_account(PurpleRequestCommonParameters *cpar,
PurpleAccount *account);
/**
- * Gets the #PurpleAccount associated with the request.
+ * purple_request_cpar_get_account:
+ * @cpar: The parameters set (may be %NULL).
*
- * @cpar: The parameters set (may be %NULL).
+ * Gets the #PurpleAccount associated with the request.
*
* Returns: The associated #PurpleAccount, or NULL if none is.
*/
@@ -275,20 +312,22 @@
purple_request_cpar_get_account(PurpleRequestCommonParameters *cpar);
/**
+ * purple_request_cpar_set_conversation:
+ * @cpar: The parameters set.
+ * @conv: The #PurpleConversation to associate.
+ *
* Sets the #PurpleConversation associated with the request, or %NULL, if
* none is.
- *
- * @cpar: The parameters set.
- * @conv: The #PurpleConversation to associate.
*/
void
purple_request_cpar_set_conversation(PurpleRequestCommonParameters *cpar,
PurpleConversation *conv);
/**
- * Gets the #PurpleConversation associated with the request.
+ * purple_request_cpar_get_conversation:
+ * @cpar: The parameters set (may be %NULL).
*
- * @cpar: The parameters set (may be %NULL).
+ * Gets the #PurpleConversation associated with the request.
*
* Returns: The associated #PurpleConversation, or NULL if none is.
*/
@@ -296,19 +335,21 @@
purple_request_cpar_get_conversation(PurpleRequestCommonParameters *cpar);
/**
- * Sets the icon associated with the request.
- *
+ * purple_request_cpar_set_icon:
* @cpar: The parameters set.
* @icon_type: The icon type.
+ *
+ * Sets the icon associated with the request.
*/
void
purple_request_cpar_set_icon(PurpleRequestCommonParameters *cpar,
PurpleRequestIconType icon_type);
/**
- * Gets the icon associated with the request.
+ * purple_request_cpar_get_icon:
+ * @cpar: The parameters set.
*
- * @cpar: The parameters set.
+ * Gets the icon associated with the request.
*
* Returns: icon_type The icon type.
*/
@@ -316,23 +357,25 @@
purple_request_cpar_get_icon(PurpleRequestCommonParameters *cpar);
/**
- * Sets the custom icon associated with the request.
- *
+ * purple_request_cpar_set_custom_icon:
* @cpar: The parameters set.
* @icon_data: The icon image contents (%NULL to reset).
* @icon_size: The icon image size.
+ *
+ * Sets the custom icon associated with the request.
*/
void
purple_request_cpar_set_custom_icon(PurpleRequestCommonParameters *cpar,
gconstpointer icon_data, gsize icon_size);
/**
- * Gets the custom icon associated with the request.
- *
+ * purple_request_cpar_get_custom_icon:
* @cpar: The parameters set (may be %NULL).
* @icon_size: The pointer to variable, where icon size should be stored
* (may be %NULL).
*
+ * Gets the custom icon associated with the request.
+ *
* Returns: The icon image contents.
*/
gconstpointer
@@ -340,21 +383,23 @@
gsize *icon_size);
/**
- * Switches the request text to be HTML or not.
- *
+ * purple_request_cpar_set_html:
* @cpar: The parameters set.
* @enabled: 1, if the text passed with the request contains HTML,
* 0 otherwise. Don't use any other values, as they may be
* redefined in the future.
+ *
+ * Switches the request text to be HTML or not.
*/
void
purple_request_cpar_set_html(PurpleRequestCommonParameters *cpar,
gboolean enabled);
/**
- * Checks, if the text passed to the request is HTML.
+ * purple_request_cpar_is_html:
+ * @cpar: The parameters set (may be %NULL).
*
- * @cpar: The parameters set (may be %NULL).
+ * Checks, if the text passed to the request is HTML.
*
* Returns: %TRUE, if the text is HTML, %FALSE otherwise.
*/
@@ -362,19 +407,21 @@
purple_request_cpar_is_html(PurpleRequestCommonParameters *cpar);
/**
- * Sets dialog display mode to compact or default.
- *
+ * purple_request_cpar_set_compact:
* @cpar: The parameters set.
* @compact: TRUE for compact, FALSE otherwise.
+ *
+ * Sets dialog display mode to compact or default.
*/
void
purple_request_cpar_set_compact(PurpleRequestCommonParameters *cpar,
gboolean compact);
/**
- * Gets dialog display mode.
+ * purple_request_cpar_is_compact:
+ * @cpar: The parameters set (may be %NULL).
*
- * @cpar: The parameters set (may be %NULL).
+ * Gets dialog display mode.
*
* Returns: TRUE for compact, FALSE for default.
*/
@@ -382,23 +429,25 @@
purple_request_cpar_is_compact(PurpleRequestCommonParameters *cpar);
/**
- * Sets the callback for the Help button.
- *
+ * purple_request_cpar_set_help_cb:
* @cpar: The parameters set.
* @cb: The callback.
* @user_data: The data to be passed to the callback.
+ *
+ * Sets the callback for the Help button.
*/
void
purple_request_cpar_set_help_cb(PurpleRequestCommonParameters *cpar,
PurpleRequestHelpCb cb, gpointer user_data);
/**
- * Gets the callback for the Help button.
- *
+ * purple_request_cpar_get_help_cb:
* @cpar: The parameters set (may be %NULL).
* @user_data: The pointer to the variable, where user data (to be passed
* to callback function) should be stored.
*
+ * Gets the callback for the Help button.
+ *
* Returns: The callback.
*/
PurpleRequestHelpCb
@@ -406,8 +455,7 @@
gpointer *user_data);
/**
- * Sets extra actions for the PurpleRequestFields dialog.
- *
+ * purple_request_cpar_set_extra_actions:
* @cpar: The parameters set.
* @...: A list of actions. These are pairs of arguments. The first of
* each pair is the <tt>char *</tt> label that appears on the
@@ -415,14 +463,17 @@
* to use as the accelerator key for the button. The second of each
* pair is the #PurpleRequestFieldsCb function to use when the
* button is clicked. Should be terminated with the NULL label.
+ *
+ * Sets extra actions for the PurpleRequestFields dialog.
*/
void
purple_request_cpar_set_extra_actions(PurpleRequestCommonParameters *cpar, ...);
/**
- * Gets extra actions for the PurpleRequestFields dialog.
+ * purple_request_cpar_get_extra_actions:
+ * @cpar: The parameters set (may be %NULL).
*
- * @cpar: The parameters set (may be %NULL).
+ * Gets extra actions for the PurpleRequestFields dialog.
*
* Returns: A list of actions (pairs of arguments, as in setter).
*/
@@ -430,20 +481,22 @@
purple_request_cpar_get_extra_actions(PurpleRequestCommonParameters *cpar);
/**
+ * purple_request_cpar_set_parent_from:
+ * @cpar: The parameters set.
+ * @ui_handle: The UI handle.
+ *
* Sets the same parent window for this dialog, as the parent of specified
* Notify API or Request API dialog UI handle.
- *
- * @cpar: The parameters set.
- * @ui_handle: The UI handle.
*/
void
purple_request_cpar_set_parent_from(PurpleRequestCommonParameters *cpar,
gpointer ui_handle);
/**
- * Gets the parent "donor" for this dialog.
+ * purple_request_cpar_get_parent_from:
+ * @cpar: The parameters set (may be %NULL).
*
- * @cpar: The parameters set (may be %NULL).
+ * Gets the parent "donor" for this dialog.
*
* Returns: The donors UI handle.
*/
@@ -458,6 +511,8 @@
/*@{*/
/**
+ * purple_request_fields_new:
+ *
* Creates a list of fields to pass to purple_request_fields().
*
* Returns: A PurpleRequestFields structure.
@@ -465,44 +520,49 @@
PurpleRequestFields *purple_request_fields_new(void);
/**
- * Destroys a list of fields.
+ * purple_request_fields_destroy:
+ * @fields: The list of fields to destroy.
*
- * @fields: The list of fields to destroy.
+ * Destroys a list of fields.
*/
void purple_request_fields_destroy(PurpleRequestFields *fields);
/**
- * Adds a group of fields to the list.
- *
+ * purple_request_fields_add_group:
* @fields: The fields list.
* @group: The group to add.
+ *
+ * Adds a group of fields to the list.
*/
void purple_request_fields_add_group(PurpleRequestFields *fields,
PurpleRequestFieldGroup *group);
/**
- * Returns a list of all groups in a field list.
+ * purple_request_fields_get_groups:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns a list of all groups in a field list.
*
* Returns: (transfer none): A list of groups.
*/
GList *purple_request_fields_get_groups(const PurpleRequestFields *fields);
/**
- * Set tab names for a field list.
- *
+ * purple_request_fields_set_tab_names:
* @fields: The fields list.
* @tab_names: NULL-terminated array of localized tab labels,
* may be %NULL.
+ *
+ * Set tab names for a field list.
*/
void purple_request_fields_set_tab_names(PurpleRequestFields *fields,
const gchar **tab_names);
/**
- * Returns tab names of a field list.
+ * purple_request_fields_get_tab_names:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns tab names of a field list.
*
* Returns: NULL-terminated array of localized tab labels, or NULL if tabs
* are disabled.
@@ -511,20 +571,22 @@
purple_request_fields_get_tab_names(const PurpleRequestFields *fields);
/**
- * Returns whether or not the field with the specified ID exists.
- *
+ * purple_request_fields_exists:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Returns whether or not the field with the specified ID exists.
+ *
* Returns: TRUE if the field exists, or FALSE.
*/
gboolean purple_request_fields_exists(const PurpleRequestFields *fields,
const char *id);
/**
- * Returns a list of all required fields.
+ * purple_request_fields_get_required:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns a list of all required fields.
*
* Returns: (transfer none): The list of required fields.
*/
@@ -532,9 +594,10 @@
const PurpleRequestFields *fields);
/**
- * Returns a list of all validated fields.
+ * purple_request_fields_get_validatable:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns a list of all validated fields.
*
* Returns: (transfer none): The list of validated fields.
*/
@@ -542,9 +605,10 @@
const PurpleRequestFields *fields);
/**
- * Returns a list of all fields with sensitivity callback added.
+ * purple_request_fields_get_autosensitive:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns a list of all fields with sensitivity callback added.
*
* Returns: (transfer none): The list of fields with automatic sensitivity callback.
*/
@@ -552,20 +616,22 @@
purple_request_fields_get_autosensitive(const PurpleRequestFields *fields);
/**
- * Returns whether or not a field with the specified ID is required.
- *
+ * purple_request_fields_is_field_required:
* @fields: The fields list.
* @id: The field ID.
*
+ * Returns whether or not a field with the specified ID is required.
+ *
* Returns: TRUE if the specified field is required, or FALSE.
*/
gboolean purple_request_fields_is_field_required(const PurpleRequestFields *fields,
const char *id);
/**
- * Returns whether or not all required fields have values.
+ * purple_request_fields_all_required_filled:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns whether or not all required fields have values.
*
* Returns: TRUE if all required fields have values, or FALSE.
*/
@@ -573,64 +639,70 @@
const PurpleRequestFields *fields);
/**
- * Returns whether or not all fields are valid.
+ * purple_request_fields_all_valid:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns whether or not all fields are valid.
*
* Returns: TRUE if all fields are valid, or FALSE.
*/
gboolean purple_request_fields_all_valid(const PurpleRequestFields *fields);
/**
- * Return the field with the specified ID.
- *
+ * purple_request_fields_get_field:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Return the field with the specified ID.
+ *
* Returns: The field, if found.
*/
PurpleRequestField *purple_request_fields_get_field(
const PurpleRequestFields *fields, const char *id);
/**
- * Returns the string value of a field with the specified ID.
- *
+ * purple_request_fields_get_string:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Returns the string value of a field with the specified ID.
+ *
* Returns: The string value, if found, or %NULL otherwise.
*/
const char *purple_request_fields_get_string(const PurpleRequestFields *fields,
const char *id);
/**
- * Returns the integer value of a field with the specified ID.
- *
+ * purple_request_fields_get_integer:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Returns the integer value of a field with the specified ID.
+ *
* Returns: The integer value, if found, or 0 otherwise.
*/
int purple_request_fields_get_integer(const PurpleRequestFields *fields,
const char *id);
/**
- * Returns the boolean value of a field with the specified ID.
- *
+ * purple_request_fields_get_bool:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Returns the boolean value of a field with the specified ID.
+ *
* Returns: The boolean value, if found, or %FALSE otherwise.
*/
gboolean purple_request_fields_get_bool(const PurpleRequestFields *fields,
const char *id);
/**
- * Returns the choice index of a field with the specified ID.
- *
+ * purple_request_fields_get_choice:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Returns the choice index of a field with the specified ID.
+ *
* Returns: The choice value, if found, or NULL otherwise.
*/
gpointer
@@ -638,20 +710,22 @@
const char *id);
/**
- * Returns the account of a field with the specified ID.
- *
+ * purple_request_fields_get_account:
* @fields: The fields list.
* @id: The ID of the field.
*
+ * Returns the account of a field with the specified ID.
+ *
* Returns: The account value, if found, or NULL otherwise.
*/
PurpleAccount *purple_request_fields_get_account(const PurpleRequestFields *fields,
const char *id);
/**
- * Returns the UI data associated with this object.
+ * purple_request_fields_get_ui_data:
+ * @fields: The fields list.
*
- * @fields: The fields list.
+ * Returns the UI data associated with this object.
*
* Returns: The UI data associated with this object. This is a
* convenience field provided to the UIs--it is not
@@ -660,10 +734,11 @@
gpointer purple_request_fields_get_ui_data(const PurpleRequestFields *fields);
/**
- * Set the UI data associated with this object.
- *
+ * purple_request_fields_set_ui_data:
* @fields: The fields list.
* @ui_data: A pointer to associate with this object.
+ *
+ * Set the UI data associated with this object.
*/
void purple_request_fields_set_ui_data(PurpleRequestFields *fields, gpointer ui_data);
@@ -675,29 +750,32 @@
/*@{*/
/**
- * Creates a fields group with an optional title.
+ * purple_request_field_group_new:
+ * @title: The optional title to give the group.
*
- * @title: The optional title to give the group.
+ * Creates a fields group with an optional title.
*
* Returns: A new fields group
*/
PurpleRequestFieldGroup *purple_request_field_group_new(const char *title);
/**
- * Sets tab number for a group.
- *
+ * purple_request_field_group_set_tab:
* @group: The group.
* @tab_no: The tab number.
*
+ * Sets tab number for a group.
+ *
* @see purple_request_fields_set_tab_names
*/
void purple_request_field_group_set_tab(PurpleRequestFieldGroup *group,
guint tab_no);
/**
- * Returns tab number of a group.
+ * purple_request_field_group_get_tab:
+ * @group: The group.
*
- * @group: The group.
+ * Returns tab number of a group.
*
* Returns: Tab number.
*
@@ -706,25 +784,28 @@
guint purple_request_field_group_get_tab(const PurpleRequestFieldGroup *group);
/**
- * Destroys a fields group.
+ * purple_request_field_group_destroy:
+ * @group: The group to destroy.
*
- * @group: The group to destroy.
+ * Destroys a fields group.
*/
void purple_request_field_group_destroy(PurpleRequestFieldGroup *group);
/**
- * Adds a field to the group.
- *
+ * purple_request_field_group_add_field:
* @group: The group to add the field to.
* @field: The field to add to the group.
+ *
+ * Adds a field to the group.
*/
void purple_request_field_group_add_field(PurpleRequestFieldGroup *group,
PurpleRequestField *field);
/**
- * Returns the title of a fields group.
+ * purple_request_field_group_get_title:
+ * @group: The group.
*
- * @group: The group.
+ * Returns the title of a fields group.
*
* Returns: The title, if set.
*/
@@ -732,9 +813,10 @@
const PurpleRequestFieldGroup *group);
/**
- * Returns a list of all fields in a group.
+ * purple_request_field_group_get_fields:
+ * @group: The group.
*
- * @group: The group.
+ * Returns a list of all fields in a group.
*
* Returns: (transfer none): The list of fields in the group.
*/
@@ -742,9 +824,10 @@
const PurpleRequestFieldGroup *group);
/**
- * Returns a list of all fields in a group.
+ * purple_request_field_group_get_fields_list:
+ * @group: The group.
*
- * @group: The group.
+ * Returns a list of all fields in a group.
*
* Returns: (transfer none): The list of fields in the group.
*/
@@ -759,174 +842,197 @@
/*@{*/
/**
- * Creates a field of the specified type.
- *
+ * purple_request_field_new:
* @id: The field ID.
* @text: The text label of the field.
* @type: The type of field.
*
+ * Creates a field of the specified type.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_new(const char *id, const char *text,
PurpleRequestFieldType type);
/**
- * Destroys a field.
+ * purple_request_field_destroy:
+ * @field: The field to destroy.
*
- * @field: The field to destroy.
+ * Destroys a field.
*/
void purple_request_field_destroy(PurpleRequestField *field);
/**
- * Sets the label text of a field.
- *
+ * purple_request_field_set_label:
* @field: The field.
* @label: The text label.
+ *
+ * Sets the label text of a field.
*/
void purple_request_field_set_label(PurpleRequestField *field, const char *label);
/**
- * Sets whether or not a field is visible.
- *
+ * purple_request_field_set_visible:
* @field: The field.
* @visible: TRUE if visible, or FALSE if not.
+ *
+ * Sets whether or not a field is visible.
*/
void purple_request_field_set_visible(PurpleRequestField *field, gboolean visible);
/**
+ * purple_request_field_set_type_hint:
+ * @field: The field.
+ * @type_hint: The 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".
- *
- * @field: The field.
- * @type_hint: The type hint.
*/
void purple_request_field_set_type_hint(PurpleRequestField *field,
const char *type_hint);
/**
+ * purple_request_field_set_tooltip:
+ * @field: The field.
+ * @tooltip: The tooltip text.
+ *
* Sets the tooltip for the field.
*
* This is optionally used by the UIs to provide a tooltip for
* the field.
- *
- * @field: The field.
- * @tooltip: The tooltip text.
*/
void purple_request_field_set_tooltip(PurpleRequestField *field,
const char *tooltip);
/**
- * Sets whether or not a field is required.
- *
+ * purple_request_field_set_required:
* @field: The field.
* @required: TRUE if required, or FALSE.
+ *
+ * Sets whether or not a field is required.
*/
void purple_request_field_set_required(PurpleRequestField *field,
gboolean required);
/**
- * Returns the type of a field.
+ * purple_request_field_get_type:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the type of a field.
*
* Returns: The field's type.
*/
PurpleRequestFieldType purple_request_field_get_type(const PurpleRequestField *field);
/**
- * Returns the group for the field.
+ * purple_request_field_get_group:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the group for the field.
*
* Returns: The UI data.
*/
PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field);
/**
- * Returns the ID of a field.
+ * purple_request_field_get_id:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the ID of a field.
*
* Returns: The ID
*/
const char *purple_request_field_get_id(const PurpleRequestField *field);
/**
- * Returns the label text of a field.
+ * purple_request_field_get_label:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the label text of a field.
*
* Returns: The label text.
*/
const char *purple_request_field_get_label(const PurpleRequestField *field);
/**
- * Returns whether or not a field is visible.
+ * purple_request_field_is_visible:
+ * @field: The field.
*
- * @field: The field.
+ * Returns whether or not a field is visible.
*
* Returns: TRUE if the field is visible. FALSE otherwise.
*/
gboolean purple_request_field_is_visible(const PurpleRequestField *field);
/**
- * Returns the field's type hint.
+ * purple_request_field_get_type_hint:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the field's type hint.
*
* Returns: The field's type hint.
*/
const char *purple_request_field_get_type_hint(const PurpleRequestField *field);
/**
- * Returns the field's tooltip.
+ * purple_request_field_get_tooltip:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the field's tooltip.
*
* Returns: The field's tooltip.
*/
const char *purple_request_field_get_tooltip(const PurpleRequestField *field);
/**
- * Returns whether or not a field is required.
+ * purple_request_field_is_required:
+ * @field: The field.
*
- * @field: The field.
+ * Returns whether or not a field is required.
*
* Returns: TRUE if the field is required, or FALSE.
*/
gboolean purple_request_field_is_required(const PurpleRequestField *field);
/**
- * Checks, if specified field has value.
+ * purple_request_field_is_filled:
+ * @field: The field.
*
- * @field: The field.
+ * Checks, if specified field has value.
*
* Returns: TRUE if the field has value, or FALSE.
*/
gboolean purple_request_field_is_filled(const PurpleRequestField *field);
/**
- * Sets validator for a single field.
- *
+ * purple_request_field_set_validator:
* @field: The field.
* @validator: The validator callback, NULL to disable validation.
* @user_data: The data to pass to the callback.
+ *
+ * Sets validator for a single field.
*/
void purple_request_field_set_validator(PurpleRequestField *field,
PurpleRequestFieldValidator validator, void *user_data);
/**
- * Returns whether or not field has validator set.
+ * purple_request_field_is_validatable:
+ * @field: The field.
*
- * @field: The field.
+ * Returns whether or not field has validator set.
*
* Returns: TRUE if the field has validator, or FALSE.
*/
gboolean purple_request_field_is_validatable(PurpleRequestField *field);
/**
+ * purple_request_field_is_valid:
+ * @field: The field.
+ * @errmsg: If non-NULL, the memory area, where the pointer to validation
+ * failure message will be set.
+ *
* Checks, if specified field is valid.
*
* If detailed message about failure reason is needed, there is an option to
@@ -935,56 +1041,57 @@
*
* Note: empty, not required fields are valid.
*
- * @field: The field.
- * @errmsg: If non-NULL, the memory area, where the pointer to validation
- * failure message will be set.
- *
* Returns: TRUE, if the field is valid, FALSE otherwise.
*/
gboolean purple_request_field_is_valid(PurpleRequestField *field, gchar **errmsg);
/**
- * Sets field editable.
- *
+ * purple_request_field_set_sensitive:
* @field: The field.
* @sensitive: TRUE if the field should be sensitive for user input.
+ *
+ * Sets field editable.
*/
void purple_request_field_set_sensitive(PurpleRequestField *field,
gboolean sensitive);
/**
- * Checks, if field is editable.
+ * purple_request_field_is_sensitive:
+ * @field: The field.
*
- * @field: The field.
+ * Checks, if field is editable.
*
* Returns: TRUE, if the field is sensitive for user input.
*/
gboolean purple_request_field_is_sensitive(PurpleRequestField *field);
/**
- * Sets the callback, used to determine if the field should be editable.
- *
+ * purple_request_field_set_sensitivity_cb:
* @field: The field.
* @cb: The callback.
+ *
+ * Sets the callback, used to determine if the field should be editable.
*/
void purple_request_field_set_sensitivity_cb(PurpleRequestField *field,
PurpleRequestFieldSensitivityCb cb);
/**
- * Returns the ui_data for a field.
+ * purple_request_field_get_ui_data:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the ui_data for a field.
*
* Returns: The UI data.
*/
gpointer purple_request_field_get_ui_data(const PurpleRequestField *field);
/**
- * Sets the ui_data for a field.
- *
+ * purple_request_field_set_ui_data:
* @field: The field.
* @ui_data: The UI data.
*
+ * Sets the ui_data for a field.
+ *
* Returns: The UI data.
*/
void purple_request_field_set_ui_data(PurpleRequestField *field,
@@ -998,13 +1105,14 @@
/*@{*/
/**
- * Creates a string request field.
- *
+ * purple_request_field_string_new:
* @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.
*
+ * Creates a string request field.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_string_new(const char *id,
@@ -1013,37 +1121,41 @@
gboolean multiline);
/**
- * Sets the default value in a string field.
- *
+ * purple_request_field_string_set_default_value:
* @field: The field.
* @default_value: The default value.
+ *
+ * Sets the default value in a string field.
*/
void purple_request_field_string_set_default_value(PurpleRequestField *field,
const char *default_value);
/**
- * Sets the value in a string field.
- *
+ * purple_request_field_string_set_value:
* @field: The field.
* @value: The value.
+ *
+ * Sets the value in a string field.
*/
void purple_request_field_string_set_value(PurpleRequestField *field,
const char *value);
/**
+ * purple_request_field_string_set_masked:
+ * @field: The field.
+ * @masked: The masked value.
+ *
* Sets whether or not a string field is masked
* (commonly used for password fields).
- *
- * @field: The field.
- * @masked: The masked value.
*/
void purple_request_field_string_set_masked(PurpleRequestField *field,
gboolean masked);
/**
- * Returns the default value in a string field.
+ * purple_request_field_string_get_default_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the default value in a string field.
*
* Returns: The default value.
*/
@@ -1051,27 +1163,30 @@
const PurpleRequestField *field);
/**
- * Returns the user-entered value in a string field.
+ * purple_request_field_string_get_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the user-entered value in a string field.
*
* Returns: The value.
*/
const char *purple_request_field_string_get_value(const PurpleRequestField *field);
/**
- * Returns whether or not a string field is multi-line.
+ * purple_request_field_string_is_multiline:
+ * @field: The field.
*
- * @field: The field.
+ * Returns whether or not a string field is multi-line.
*
* Returns: %TRUE if the field is mulit-line, or %FALSE otherwise.
*/
gboolean purple_request_field_string_is_multiline(const PurpleRequestField *field);
/**
- * Returns whether or not a string field is masked.
+ * purple_request_field_string_is_masked:
+ * @field: The field.
*
- * @field: The field.
+ * Returns whether or not a string field is masked.
*
* Returns: %TRUE if the field is masked, or %FALSE otherwise.
*/
@@ -1085,83 +1200,92 @@
/*@{*/
/**
- * Creates an integer field.
- *
+ * purple_request_field_int_new:
* @id: The field ID.
* @text: The text label of the field.
* @default_value: The default value.
* @lower_bound: The lower bound.
* @upper_bound: The upper bound.
*
+ * Creates an integer field.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_int_new(const char *id,
const char *text, int default_value, int lower_bound, int upper_bound);
/**
- * Sets the default value in an integer field.
- *
+ * purple_request_field_int_set_default_value:
* @field: The field.
* @default_value: The default value.
+ *
+ * Sets the default value in an integer field.
*/
void purple_request_field_int_set_default_value(PurpleRequestField *field,
int default_value);
/**
- * Sets the lower bound in an integer field.
- *
+ * purple_request_field_int_set_lower_bound:
* @field: The field.
* @lower_bound: The lower bound.
+ *
+ * Sets the lower bound in an integer field.
*/
void purple_request_field_int_set_lower_bound(PurpleRequestField *field, int lower_bound);
/**
- * Sets the upper bound in an integer field.
- *
+ * purple_request_field_int_set_upper_bound:
* @field: The field.
* @upper_bound: The upper bound.
+ *
+ * Sets the upper bound in an integer field.
*/
void purple_request_field_int_set_upper_bound(PurpleRequestField *field, int lower_bound);
/**
- * Sets the value in an integer field.
- *
+ * purple_request_field_int_set_value:
* @field: The field.
* @value: The value.
+ *
+ * Sets the value in an integer field.
*/
void purple_request_field_int_set_value(PurpleRequestField *field, int value);
/**
- * Returns the default value in an integer field.
+ * purple_request_field_int_get_default_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the default value in an integer field.
*
* Returns: The default value.
*/
int purple_request_field_int_get_default_value(const PurpleRequestField *field);
/**
- * Returns the lower bound in an integer field.
+ * purple_request_field_int_get_lower_bound:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the lower bound in an integer field.
*
* Returns: The lower bound.
*/
int purple_request_field_int_get_lower_bound(const PurpleRequestField *field);
/**
- * Returns the upper bound in an integer field.
+ * purple_request_field_int_get_upper_bound:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the upper bound in an integer field.
*
* Returns: The upper bound.
*/
int purple_request_field_int_get_upper_bound(const PurpleRequestField *field);
/**
- * Returns the user-entered value in an integer field.
+ * purple_request_field_int_get_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the user-entered value in an integer field.
*
* Returns: The value.
*/
@@ -1175,14 +1299,15 @@
/*@{*/
/**
+ * purple_request_field_bool_new:
+ * @id: The field ID.
+ * @text: The text label of the field.
+ * @default_value: The default value.
+ *
* Creates a boolean field.
*
* This is often represented as a checkbox.
*
- * @id: The field ID.
- * @text: The text label of the field.
- * @default_value: The default value.
- *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_bool_new(const char *id,
@@ -1190,27 +1315,30 @@
gboolean default_value);
/**
- * Sets the default value in an boolean field.
- *
+ * purple_request_field_bool_set_default_value:
* @field: The field.
* @default_value: The default value.
+ *
+ * Sets the default value in an boolean field.
*/
void purple_request_field_bool_set_default_value(PurpleRequestField *field,
gboolean default_value);
/**
- * Sets the value in an boolean field.
- *
+ * purple_request_field_bool_set_value:
* @field: The field.
* @value: The value.
+ *
+ * Sets the value in an boolean field.
*/
void purple_request_field_bool_set_value(PurpleRequestField *field,
gboolean value);
/**
- * Returns the default value in an boolean field.
+ * purple_request_field_bool_get_default_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the default value in an boolean field.
*
* Returns: The default value.
*/
@@ -1218,9 +1346,10 @@
const PurpleRequestField *field);
/**
- * Returns the user-entered value in an boolean field.
+ * purple_request_field_bool_get_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the user-entered value in an boolean field.
*
* Returns: The value.
*/
@@ -1234,14 +1363,15 @@
/*@{*/
/**
+ * purple_request_field_choice_new:
+ * @id: The field ID.
+ * @text: The optional label of the field.
+ * @default_value: The default choice.
+ *
* Creates a multiple choice field.
*
* This is often represented as a group of radio buttons.
*
- * @id: The field ID.
- * @text: The optional label of the field.
- * @default_value: The default choice.
- *
* Returns: The new field.
*/
PurpleRequestField *
@@ -1249,40 +1379,44 @@
gpointer default_value);
/**
- * Adds a choice to a multiple choice field.
- *
+ * purple_request_field_choice_add:
* @field: The choice field.
* @label: The choice label.
* @data: The choice value.
+ *
+ * Adds a choice to a multiple choice field.
*/
void
purple_request_field_choice_add(PurpleRequestField *field, const char *label,
gpointer data);
/**
- * Sets the default value in an choice field.
- *
+ * purple_request_field_choice_set_default_value:
* @field: The field.
* @default_value: The default value.
+ *
+ * Sets the default value in an choice field.
*/
void
purple_request_field_choice_set_default_value(PurpleRequestField *field,
gpointer default_value);
/**
- * Sets the value in an choice field.
- *
+ * purple_request_field_choice_set_value:
* @field: The field.
* @value: The value.
+ *
+ * Sets the value in an choice field.
*/
void
purple_request_field_choice_set_value(PurpleRequestField *field,
gpointer value);
/**
- * Returns the default value in an choice field.
+ * purple_request_field_choice_get_default_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the default value in an choice field.
*
* Returns: The default value.
*/
@@ -1290,9 +1424,10 @@
purple_request_field_choice_get_default_value(const PurpleRequestField *field);
/**
- * Returns the user-entered value in an choice field.
+ * purple_request_field_choice_get_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the user-entered value in an choice field.
*
* Returns: The value.
*/
@@ -1300,9 +1435,10 @@
purple_request_field_choice_get_value(const PurpleRequestField *field);
/**
- * Returns a list of elements in a choice field.
+ * purple_request_field_choice_get_elements:
+ * @field: The field.
*
- * @field: The field.
+ * Returns a list of elements in a choice field.
*
* Returns: (transfer none): The list of pairs <label, value>.
*/
@@ -1310,10 +1446,11 @@
purple_request_field_choice_get_elements(const PurpleRequestField *field);
/**
- * Sets the destructor for field values.
- *
+ * purple_request_field_choice_set_data_destructor:
* @field: The field.
* @destroy: The destroy function.
+ *
+ * Sets the destructor for field values.
*/
void
purple_request_field_choice_set_data_destructor(PurpleRequestField *field,
@@ -1327,29 +1464,32 @@
/*@{*/
/**
- * Creates a multiple list item field.
- *
+ * purple_request_field_list_new:
* @id: The field ID.
* @text: The optional label of the field.
*
+ * Creates a multiple list item field.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_list_new(const char *id, const char *text);
/**
- * Sets whether or not a list field allows multiple selection.
- *
+ * purple_request_field_list_set_multi_select:
* @field: The list field.
* @multi_select: TRUE if multiple selection is enabled,
* or FALSE otherwise.
+ *
+ * Sets whether or not a list field allows multiple selection.
*/
void purple_request_field_list_set_multi_select(PurpleRequestField *field,
gboolean multi_select);
/**
- * Returns whether or not a list field allows multiple selection.
+ * purple_request_field_list_get_multi_select:
+ * @field: The list field.
*
- * @field: The list field.
+ * Returns whether or not a list field allows multiple selection.
*
* Returns: TRUE if multiple selection is enabled, or FALSE otherwise.
*/
@@ -1357,92 +1497,101 @@
const PurpleRequestField *field);
/**
- * Returns the data for a particular item.
- *
+ * purple_request_field_list_get_data:
* @field: The list field.
* @text: The item text.
*
+ * Returns the data for a particular item.
+ *
* Returns: The data associated with the item.
*/
void *purple_request_field_list_get_data(const PurpleRequestField *field,
const char *text);
/**
- * Adds an item to a list field.
- *
+ * purple_request_field_list_add_icon:
* @field: The list field.
* @item: The list item.
* @icon_path: The path to icon file, or %NULL for no icon.
* @data: The associated data.
+ *
+ * Adds an item to a list field.
*/
void purple_request_field_list_add_icon(PurpleRequestField *field,
const char *item, const char* icon_path, void* data);
/**
- * Adds a selected item to the list field.
- *
+ * purple_request_field_list_add_selected:
* @field: The field.
* @item: The item to add.
+ *
+ * Adds a selected item to the list field.
*/
void purple_request_field_list_add_selected(PurpleRequestField *field,
const char *item);
/**
- * Clears the list of selected items in a list field.
+ * purple_request_field_list_clear_selected:
+ * @field: The field.
*
- * @field: The field.
+ * Clears the list of selected items in a list field.
*/
void purple_request_field_list_clear_selected(PurpleRequestField *field);
/**
- * Sets a list of selected items in a list field.
- *
+ * purple_request_field_list_set_selected:
* @field: The field.
* @items: The list of selected items, which is not modified or freed.
+ *
+ * Sets a list of selected items in a list field.
*/
void purple_request_field_list_set_selected(PurpleRequestField *field,
GList *items);
/**
- * Returns whether or not a particular item is selected in a list field.
- *
+ * purple_request_field_list_is_selected:
* @field: The field.
* @item: The item.
*
+ * Returns whether or not a particular item is selected in a list field.
+ *
* Returns: TRUE if the item is selected. FALSE otherwise.
*/
gboolean purple_request_field_list_is_selected(const PurpleRequestField *field,
const char *item);
/**
+ * purple_request_field_list_get_selected:
+ * @field: The 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().
*
- * @field: The field.
- *
* Returns: (transfer none): The list of selected items.
*/
GList *purple_request_field_list_get_selected(
const PurpleRequestField *field);
/**
- * Returns a list of items in a list field.
+ * purple_request_field_list_get_items:
+ * @field: The field.
*
- * @field: The field.
+ * Returns a list of items in a list field.
*
* Returns: (transfer none): The list of items.
*/
GList *purple_request_field_list_get_items(const PurpleRequestField *field);
/**
+ * purple_request_field_list_get_icons:
+ * @field: The field.
+ *
* Returns a list of icons in a list field.
*
* The icons will correspond with the items, in order.
*
- * @field: The field.
- *
* Returns: (transfer none): The list of icons or %NULL (i.e. the empty GList) if no
* items have icons.
*/
@@ -1456,11 +1605,12 @@
/*@{*/
/**
- * Creates a label field.
- *
+ * purple_request_field_label_new:
* @id: The field ID.
* @text: The label of the field.
*
+ * Creates a label field.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_label_new(const char *id,
@@ -1474,12 +1624,13 @@
/*@{*/
/**
- * Creates an image field.
- *
+ * purple_request_field_image_new:
* @id: The field ID.
* @text: The label of the field.
* @buf: The image data.
- * @size: The size of the data in @a buffer.
+ * @size: The size of the data in @buf.
+ *
+ * Creates an image field.
*
* Returns: The new field.
*/
@@ -1487,45 +1638,50 @@
const char *buf, gsize size);
/**
- * Sets the scale factors of an image field.
- *
+ * purple_request_field_image_set_scale:
* @field: The image field.
* @x: The x scale factor.
* @y: The y scale factor.
+ *
+ * Sets the scale factors of an image field.
*/
void purple_request_field_image_set_scale(PurpleRequestField *field, unsigned int x, unsigned int y);
/**
- * Returns pointer to the image.
+ * purple_request_field_image_get_buffer:
+ * @field: The image field.
*
- * @field: The image field.
+ * Returns pointer to the image.
*
* Returns: Pointer to the image.
*/
const char *purple_request_field_image_get_buffer(PurpleRequestField *field);
/**
- * Returns size (in bytes) of the image.
+ * purple_request_field_image_get_size:
+ * @field: The image field.
*
- * @field: The image field.
+ * Returns size (in bytes) of the image.
*
* Returns: Size of the image.
*/
gsize purple_request_field_image_get_size(PurpleRequestField *field);
/**
- * Returns X scale coefficient of the image.
+ * purple_request_field_image_get_scale_x:
+ * @field: The image field.
*
- * @field: The image field.
+ * Returns X scale coefficient of the image.
*
* Returns: X scale coefficient of the image.
*/
unsigned int purple_request_field_image_get_scale_x(PurpleRequestField *field);
/**
- * Returns Y scale coefficient of the image.
+ * purple_request_field_image_get_scale_y:
+ * @field: The image field.
*
- * @field: The image field.
+ * Returns Y scale coefficient of the image.
*
* Returns: Y scale coefficient of the image.
*/
@@ -1539,14 +1695,15 @@
/*@{*/
/**
+ * purple_request_field_account_new:
+ * @id: The field ID.
+ * @text: The text label of the field.
+ * @account: The optional default account.
+ *
* Creates an account field.
*
* By default, this field will not show offline accounts.
*
- * @id: The field ID.
- * @text: The text label of the field.
- * @account: The optional default account.
- *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_account_new(const char *id,
@@ -1554,51 +1711,56 @@
PurpleAccount *account);
/**
- * Sets the default account on an account field.
- *
+ * purple_request_field_account_set_default_value:
* @field: The account field.
* @default_value: The default account.
+ *
+ * Sets the default account on an account field.
*/
void purple_request_field_account_set_default_value(PurpleRequestField *field,
PurpleAccount *default_value);
/**
- * Sets the account in an account field.
- *
+ * purple_request_field_account_set_value:
* @field: The account field.
* @value: The account.
+ *
+ * Sets the account in an account field.
*/
void purple_request_field_account_set_value(PurpleRequestField *field,
PurpleAccount *value);
/**
+ * purple_request_field_account_set_show_all:
+ * @field: The account field.
+ * @show_all: Whether or not to show all accounts.
+ *
* 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.
- *
- * @field: The account field.
- * @show_all: Whether or not to show all accounts.
*/
void purple_request_field_account_set_show_all(PurpleRequestField *field,
gboolean show_all);
/**
+ * purple_request_field_account_set_filter:
+ * @field: The account field.
+ * @filter_func: The account filter function.
+ *
* Sets the account filter function in an account field.
*
* This function will determine which accounts get displayed and which
* don't.
- *
- * @field: The account field.
- * @filter_func: The account filter function.
*/
void purple_request_field_account_set_filter(PurpleRequestField *field,
PurpleFilterAccountFunc filter_func);
/**
- * Returns the default account in an account field.
+ * purple_request_field_account_get_default_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the default account in an account field.
*
* Returns: The default account.
*/
@@ -1606,9 +1768,10 @@
const PurpleRequestField *field);
/**
- * Returns the user-entered account in an account field.
+ * purple_request_field_account_get_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the user-entered account in an account field.
*
* Returns: The user-entered account.
*/
@@ -1616,25 +1779,28 @@
const PurpleRequestField *field);
/**
+ * purple_request_field_account_get_show_all:
+ * @field: The account 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.
*
- * @field: The account field.
* Returns: Whether or not to show all accounts.
*/
gboolean purple_request_field_account_get_show_all(
const PurpleRequestField *field);
/**
+ * purple_request_field_account_get_filter:
+ * @field: The account field.
+ *
* Returns the account filter function in an account field.
*
* This function will determine which accounts get displayed and which
* don't.
*
- * @field: The account field.
- *
* Returns: The account filter function.
*/
PurpleFilterAccountFunc purple_request_field_account_get_filter(
@@ -1648,12 +1814,13 @@
/*@{*/
/**
- * Creates a certificate field.
- *
+ * purple_request_field_certificate_new:
* @id: The field ID.
* @text: The label of the field.
* @cert: The certificate of the field.
*
+ * Creates a certificate field.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_certificate_new(const char *id,
@@ -1661,9 +1828,10 @@
PurpleCertificate *cert);
/**
- * Returns the certificate in a certificate field.
+ * purple_request_field_certificate_get_value:
+ * @field: The field.
*
- * @field: The field.
+ * Returns the certificate in a certificate field.
*
* Returns: The certificate.
*/
@@ -1678,21 +1846,23 @@
/*@{*/
/**
- * Creates a datasheet item field.
- *
+ * purple_request_field_datasheet_new:
* @id: The field ID.
* @text: The label of the field, may be %NULL.
* @sheet: The datasheet.
*
+ * Creates a datasheet item field.
+ *
* Returns: The new field.
*/
PurpleRequestField *purple_request_field_datasheet_new(const char *id,
const gchar *text, PurpleRequestDatasheet *sheet);
/**
- * Returns a datasheet for a field.
+ * purple_request_field_datasheet_get_sheet:
+ * @field: The field.
*
- * @field: The field.
+ * Returns a datasheet for a field.
*
* Returns: (transfer none): The datasheet object.
*/
@@ -1707,28 +1877,30 @@
/*@{*/
/**
+ * purple_request_field_email_validator:
+ * @field: The field.
+ * @errmsg: (Optional) destination for error message.
+ * @user_data: Ignored.
+ *
* Validates a field which should contain an email address.
*
* @see purple_request_field_set_validator
*
- * @field: The field.
- * @errmsg: (Optional) destination for error message.
- * @user_data: Ignored.
- *
* Returns: TRUE, if field contains valid email address.
*/
gboolean purple_request_field_email_validator(PurpleRequestField *field,
gchar **errmsg, void *user_data);
/**
+ * purple_request_field_alphanumeric_validator:
+ * @field: The field.
+ * @errmsg: (Optional) destination for error message.
+ * @user_data: (Optional) allowed character list (NULL-terminated string).
+ *
* Validates a field which should contain alphanumeric content.
*
* @see purple_request_field_set_validator
*
- * @field: The field.
- * @errmsg: (Optional) destination for error message.
- * @user_data: (Optional) allowed character list (NULL-terminated string).
- *
* Returns: TRUE, if field contains only alphanumeric characters.
*/
gboolean purple_request_field_alphanumeric_validator(PurpleRequestField *field,
@@ -1742,8 +1914,7 @@
/*@{*/
/**
- * Prompts the user for text input.
- *
+ * purple_request_input:
* @handle: The plugin or connection handle. For some
* things this is <em>extremely</em> important. The
* handle is used to programmatically close the request
@@ -1770,17 +1941,19 @@
* @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 @c OK button, which may not be %NULL.
- * @ok_cb: The callback for the @c OK button, which may not be @c
- * NULL.
- * @cancel_text: The text for the @c Cancel button, which may not be @c
- * NULL.
- * @cancel_cb: The callback for the @c Cancel button, which may be
+ * @ok_text: The text for the <tt>OK</tt> button, which may not be %NULL.
+ * @ok_cb: The callback for the <tt>OK</tt> button, which may not be
+ * %NULL.
+ * @cancel_text: The text for the <tt>Cancel</tt> button, which may not be
+ * %NULL.
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, which may be
* %NULL.
* @cpar: The #PurpleRequestCommonParameters object, which gets
* unref'ed after this call.
* @user_data: The data to pass to the callback.
*
+ * Prompts the user for text input.
+ *
* Returns: A UI-specific handle.
*/
void *purple_request_input(void *handle, const char *title, const char *primary,
@@ -1792,8 +1965,7 @@
void *user_data);
/**
- * Prompts the user for multiple-choice input.
- *
+ * purple_request_choice:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> important. See the comments on
* purple_request_input().
@@ -1804,12 +1976,12 @@
* @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 @c OK button, which may not be %NULL.
- * @ok_cb: The callback for the @c OK button, which may not be @c
- * NULL.
- * @cancel_text: The text for the @c Cancel button, which may not be @c
- * NULL.
- * @cancel_cb: The callback for the @c Cancel button, or %NULL to
+ * @ok_text: The text for the <tt>OK</tt> button, which may not be %NULL.
+ * @ok_cb: The callback for the <tt>OK</tt> button, which may not be
+ * %NULL.
+ * @cancel_text: The text for the <tt>Cancel</tt> button, which may not be
+ * %NULL.
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, or %NULL to
* do nothing.
* @cpar: The #PurpleRequestCommonParameters object, which gets
* unref'ed after this call.
@@ -1818,6 +1990,8 @@
* descriptions and <tt>int</tt> values, terminated with a
* %NULL parameter.
*
+ * Prompts the user for multiple-choice input.
+ *
* Returns: A UI-specific handle.
*/
void *purple_request_choice(void *handle, const char *title, const char *primary,
@@ -1828,6 +2002,8 @@
void *user_data, ...) G_GNUC_NULL_TERMINATED;
/**
+ * purple_request_choice_varg:
+ *
* <tt>va_list</tt> version of purple_request_choice(); see its documentation.
*/
void *purple_request_choice_varg(void *handle, const char *title,
@@ -1838,10 +2014,7 @@
void *user_data, va_list choices);
/**
- * Prompts the user for an action.
- *
- * This is often represented as a dialog with a button for each action.
- *
+ * purple_request_action:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> important. See the comments on
* purple_request_input().
@@ -1866,6 +2039,10 @@
* second of each pair is the #PurpleRequestActionCb
* function to use when the button is clicked.
*
+ * Prompts the user for an action.
+ *
+ * This is often represented as a dialog with a button for each action.
+ *
* Returns: A UI-specific handle.
*/
void *
@@ -1875,6 +2052,8 @@
size_t action_count, ...);
/**
+ * purple_request_action_varg:
+ *
* <tt>va_list</tt> version of purple_request_action(); see its documentation.
*/
void *
@@ -1884,8 +2063,7 @@
size_t action_count, va_list actions);
/**
- * Displays a "please wait" dialog.
- *
+ * purple_request_wait:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> important. See the comments on
* purple_request_input().
@@ -1896,12 +2074,14 @@
* @secondary: Secondary information, or %NULL if there is none.
* @with_progress: %TRUE, if we want to display progress bar, %FALSE
* otherwise
- * @cancel_cb: The callback for the @c Cancel button, which may be
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, which may be
* %NULL.
* @cpar: The #PurpleRequestCommonParameters object, which gets
* unref'ed after this call.
* @user_data: The data to pass to the callback.
*
+ * Displays a "please wait" dialog.
+ *
* Returns: A UI-specific handle.
*/
void *
@@ -1911,27 +2091,28 @@
void *user_data);
/**
+ * purple_request_wait_pulse:
+ * @ui_handle: The request UI handle.
+ *
* Notifies the "please wait" dialog that some progress has been made, but you
* don't know how much.
- *
- * @ui_handle: The request UI handle.
*/
void
purple_request_wait_pulse(void *ui_handle);
/**
- * Notifies the "please wait" dialog about progress has been made.
- *
+ * purple_request_wait_progress:
* @ui_handle: The request UI handle.
* @fraction: The part of task that is done (between 0.0 and 1.0,
* inclusive).
+ *
+ * Notifies the "please wait" dialog about progress has been made.
*/
void
purple_request_wait_progress(void *ui_handle, gfloat fraction);
/**
- * Displays groups of fields for the user to fill in.
- *
+ * purple_request_fields:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> important. See the comments on
* purple_request_input().
@@ -1941,17 +2122,19 @@
* feeling enigmatic.
* @secondary: Secondary information, or %NULL if there is none.
* @fields: The list of fields.
- * @ok_text: The text for the @c OK button, which may not be %NULL.
- * @ok_cb: The callback for the @c OK button, which may not be @c
- * NULL.
- * @cancel_text: The text for the @c Cancel button, which may not be @c
- * NULL.
- * @cancel_cb: The callback for the @c Cancel button, which may be
+ * @ok_text: The text for the <tt>OK</tt> button, which may not be %NULL.
+ * @ok_cb: The callback for the <tt>OK</tt> button, which may not be
+ * %NULL.
+ * @cancel_text: The text for the <tt>Cancel</tt> button, which may not be
+ * %NULL.
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, which may be
* %NULL.
* @cpar: The #PurpleRequestCommonParameters object, which gets
* unref'ed after this call.
* @user_data: The data to pass to the callback.
*
+ * Displays groups of fields for the user to fill in.
+ *
* Returns: A UI-specific handle.
*/
void *
@@ -1963,48 +2146,55 @@
void *user_data);
/**
- * Checks, if passed UI handle is valid.
- *
+ * purple_request_is_valid_ui_handle:
* @ui_handle: The UI handle.
* @type: The pointer to variable, where request type may be stored
* (may be %NULL).
*
+ * Checks, if passed UI handle is valid.
+ *
* Returns: TRUE, if handle is valid, FALSE otherwise.
*/
gboolean
purple_request_is_valid_ui_handle(void *ui_handle, PurpleRequestType *type);
/**
- * Adds a function called when notification dialog is closed.
- *
+ * purple_request_add_close_notify:
* @ui_handle: The UI handle.
* @notify: The function to be called.
* @notify_data: The data to be passed to the callback function.
+ *
+ * Adds a function called when notification dialog is closed.
*/
void
purple_request_add_close_notify(void *ui_handle, GDestroyNotify notify,
gpointer notify_data);
/**
- * Closes a request.
- *
+ * purple_request_close:
* @type: The request type.
* @uihandle: The request UI handle.
+ *
+ * Closes a request.
*/
void purple_request_close(PurpleRequestType type, void *uihandle);
/**
- * Closes all requests registered with the specified handle.
+ * purple_request_close_with_handle:
+ * @handle: The handle, as supplied as the @handle parameter to one of the
+ * <tt>purple_request_*</tt> functions.
*
- * @handle: The handle, as supplied as the @a handle parameter to one of the
- * <tt>purple_request_*</tt> functions.
+ * Closes all requests registered with the specified handle.
*
* @see purple_request_input().
*/
void purple_request_close_with_handle(void *handle);
/**
- * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.
+ * purple_request_yes_no:
+ *
+ * A wrapper for purple_request_action() that uses <tt>Yes</tt> and <tt>No</tt>
+ * buttons.
*/
#define purple_request_yes_no(handle, title, primary, secondary, \
default_action, cpar, user_data, yes_cb, no_cb) \
@@ -2013,7 +2203,10 @@
_("_No"), (no_cb))
/**
- * A wrapper for purple_request_action() that uses @c OK and @c Cancel buttons.
+ * purple_request_ok_cancel:
+ *
+ * A wrapper for purple_request_action() that uses <tt>OK</tt> and
+ * <tt>Cancel</tt> buttons.
*/
#define purple_request_ok_cancel(handle, title, primary, secondary, \
default_action, cpar, user_data, ok_cb, cancel_cb) \
@@ -2022,6 +2215,8 @@
_("_Cancel"), (cancel_cb))
/**
+ * purple_request_accept_cancel:
+ *
* A wrapper for purple_request_action() that uses Accept and Cancel buttons.
*/
#define purple_request_accept_cancel(handle, title, primary, secondary, \
@@ -2031,9 +2226,7 @@
(accept_cb), _("_Cancel"), (cancel_cb))
/**
- * 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.
- *
+ * purple_request_file:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> important. See the comments on
* purple_request_input().
@@ -2042,12 +2235,15 @@
* @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 @c OK button.
- * @cancel_cb: The callback for the @c Cancel button, which may be %NULL.
+ * @ok_cb: The callback for the <tt>OK</tt> button.
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, which may be %NULL.
* @cpar: The #PurpleRequestCommonParameters object, which gets
* unref'ed after this call.
* @user_data: The data to pass to the callback.
*
+ * 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.
+ *
* Returns: A UI-specific handle.
*/
void *
@@ -2056,21 +2252,22 @@
PurpleRequestCommonParameters *cpar, void *user_data);
/**
- * Displays a folder select dialog. Returns the selected filename to
- * the callback.
- *
+ * purple_request_folder:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> 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 @c OK button.
- * @cancel_cb: The callback for the @c Cancel button, which may be %NULL.
+ * @ok_cb: The callback for the <tt>OK</tt> button.
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, which may be %NULL.
* @cpar: The #PurpleRequestCommonParameters object, which gets
* unref'ed after this call.
* @user_data: The data to pass to the callback.
*
+ * Displays a folder select dialog. Returns the selected filename to
+ * the callback.
+ *
* Returns: A UI-specific handle.
*/
void *
@@ -2079,10 +2276,7 @@
PurpleRequestCommonParameters *cpar, void *user_data);
/**
- * Prompts the user for action over a certificate.
- *
- * This is often represented as a dialog with a button for each action.
- *
+ * purple_request_certificate:
* @handle: The plugin or connection handle. For some things this
* is <em>extremely</em> important. See the comments on
* purple_request_input().
@@ -2092,15 +2286,19 @@
* feeling enigmatic.
* @secondary: Secondary information, or %NULL if there is none.
* @cert: The #PurpleCertificate associated with this request.
- * @ok_text: The text for the @c OK button, which may not be %NULL.
- * @ok_cb: The callback for the @c OK button, which may not be
+ * @ok_text: The text for the <tt>OK</tt> button, which may not be %NULL.
+ * @ok_cb: The callback for the <tt>OK</tt> button, which may not be
* %NULL.
- * @cancel_text: The text for the @c Cancel button, which may not be
+ * @cancel_text: The text for the <tt>Cancel</tt> button, which may not be
* %NULL.
- * @cancel_cb: The callback for the @c Cancel button, which may be
+ * @cancel_cb: The callback for the <tt>Cancel</tt> button, which may be
* %NULL.
* @user_data: The data to pass to the callback.
*
+ * Prompts the user for action over a certificate.
+ *
+ * This is often represented as a dialog with a button for each action.
+ *
* Returns: A UI-specific handle.
*/
void *purple_request_certificate(void *handle, const char *title,
@@ -2117,14 +2315,17 @@
/*@{*/
/**
+ * purple_request_set_ui_ops:
+ * @ops: The UI operations structure.
+ *
* Sets the UI operations structure to be used when displaying a
* request.
- *
- * @ops: The UI operations structure.
*/
void purple_request_set_ui_ops(PurpleRequestUiOps *ops);
/**
+ * purple_request_get_ui_ops:
+ *
* Returns the UI operations structure to be used when displaying a
* request.
*