diff src/request.h @ 8286:89d9d004e3f3

[gaim-migrate @ 9010] Improved the field request API, adding required fields and account fields, as well as some new utility API functions and bug fixes. These changes allowed me to migrate the New IM dialog over to the field request API, removing a lot of code and improving consistency. committer: Tailor Script <[e-mail]>

--- a/src/request.h	Wed Feb 18 02:39:47 2004 +0000
+++ b/src/request.h	Wed Feb 18 07:22:53 2004 +0000
@@ -29,6 +29,8 @@
 #include <glib-object.h>
 #include <glib.h>
 
+#include "account.h"
+
 /**
  * Request types.
  */
@@ -52,22 +54,53 @@
 	GAIM_REQUEST_FIELD_BOOLEAN,
 	GAIM_REQUEST_FIELD_CHOICE,
 	GAIM_REQUEST_FIELD_LIST,
-	GAIM_REQUEST_FIELD_LABEL
+	GAIM_REQUEST_FIELD_LABEL,
+	GAIM_REQUEST_FIELD_ACCOUNT
 
 } GaimRequestFieldType;
 
 /**
+ * Multiple fields request data.
+ */
+typedef struct
+{
+	GList *groups;
+
+	GHashTable *fields;
+
+	GList *required_fields;
+
+	void *ui_data;
+
+} GaimRequestFields;
+
+/**
+ * A group of fields with a title.
+ */
+typedef struct
+{
+	GaimRequestFields *fields_list;
+
+	char *title;
+
+	GList *fields;
+
+} GaimRequestFieldGroup;
+
+/**
  * A request field.
  */
 typedef struct
 {
 	GaimRequestFieldType type;
+	GaimRequestFieldGroup *group;
 
 	char *id;
 	char *label;
 	char *type_hint;
 
 	gboolean visible;
+	gboolean required;
 
 	union
 	{
@@ -115,6 +148,14 @@
 
 		} list;
 
+		struct
+		{
+			GaimAccount *default_account;
+			GaimAccount *account;
+			gboolean show_all;
+
+		} account;
+
 	} u;
 
 	void *ui_data;
@@ -122,30 +163,6 @@
 } GaimRequestField;
 
 /**
- * Multiple fields request data.
- */
-typedef struct
-{
-	GList *groups;
-
-	GHashTable *fields;
-
-} GaimRequestFields;
-
-/**
- * A group of fields with a title.
- */
-typedef struct
-{
-	GaimRequestFields *fields_list;
-
-	char *title;
-
-	GList *fields;
-
-} GaimRequestFieldGroup;
-
-/**
  * Request UI operations.
  */
 typedef struct
@@ -222,6 +239,47 @@
 GList *gaim_request_fields_get_groups(const GaimRequestFields *fields);
 
 /**
+ * Returns whether or not the field with the specified ID exists.
+ *
+ * @param fields The fields list.
+ * @param id     The ID of the field.
+ *
+ * @return TRUE if the field exists, or FALSE.
+ */
+gboolean gaim_request_fields_exists(const GaimRequestFields *fields,
+									const char *id);
+
+/**
+ * Returns a list of all required fields.
+ *
+ * @param fields The fields list.
+ *
+ * @return The list of required fields.
+ */
+const GList *gaim_request_fields_get_required(const GaimRequestFields *fields);
+
+/**
+ * Returns whether or not a field with the specified ID is required.
+ *
+ * @param fields The fields list.
+ * @param id     The field ID.
+ *
+ * @return TRUE if the specified field is required, or FALSE.
+ */
+gboolean gaim_request_fields_is_field_required(const GaimRequestFields *fields,
+											   const char *id);
+
+/**
+ * Returns whether or not all required fields have values.
+ *
+ * @param fields The fields list.
+ *
+ * @return TRUE if all required fields have values, or FALSE.
+ */
+gboolean gaim_request_fields_all_required_filled(
+	const GaimRequestFields *fields);
+
+/**
  * Return the field with the specified ID.
  *
  * @param fields The fields list.
@@ -276,6 +334,17 @@
 int gaim_request_fields_get_choice(const GaimRequestFields *fields,
 								   const char *id);
 
+/**
+ * Returns the account of a field with the specified ID.
+ *
+ * @param fields The fields list.
+ * @param id     The ID of the field.
+ *
+ * @return The account value, if found, or NULL otherwise.
+ */
+GaimAccount *gaim_request_fields_get_account(const GaimRequestFields *fields,
+											 const char *id);
+
 /*@}*/
 
 /**************************************************************************/
@@ -383,6 +452,15 @@
 									  const char *type_hint);
 
 /**
+ * Sets whether or not a field is required.
+ *
+ * @param field    The field.
+ * @param required TRUE if required, or FALSE.
+ */
+void gaim_request_field_set_required(GaimRequestField *field,
+									 gboolean required);
+
+/**
  * Returns the type of a field.
  *
  * @param field The field.
@@ -427,6 +505,15 @@
  */
 const char *gaim_request_field_get_type_hint(const GaimRequestField *field);
 
+/**
+ * Returns whether or not a field is required.
+ *
+ * @param field The field.
+ *
+ * @return TRUE if the fiels is required, or FALSE.
+ */
+gboolean gaim_request_field_is_required(const GaimRequestField *field);
+
 /*@}*/
 
 /**************************************************************************/
@@ -848,7 +935,7 @@
  * Creates a label field.
  *
  * @param id   The field ID.
- * @param text The optional label of the field.
+ * @param text The label of the field.
  *
  * @return The new field.
  */
@@ -858,6 +945,90 @@
 /*@}*/
 
 /**************************************************************************/
+/** @name Account Field API                                               */
+/**************************************************************************/
+/*@{*/
+
+/**
+ * Creates an account field.
+ *
+ * By default, this field will not show offline accounts.
+ *
+ * @param id      The field ID.
+ * @param text    The text label of the field.
+ * @param account The optional default account.
+ *
+ * @return The new field.
+ */
+GaimRequestField *gaim_request_field_account_new(const char *id,
+												 const char *text,
+												 GaimAccount *account);
+
+/**
+ * Sets the default account on an account field.
+ *
+ * @param field         The account field.
+ * @param default_value The default account.
+ */
+void gaim_request_field_account_set_default_value(GaimRequestField *field,
+												  GaimAccount *default_value);
+
+/**
+ * Sets the account in an account field.
+ *
+ * @param field The account field.
+ * @param value The account.
+ */
+void gaim_request_field_account_set_value(GaimRequestField *field,
+										  GaimAccount *value);
+
+/**
+ * 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.
+ *
+ * @param field    The account field.
+ * @param show_all Whether or not to show all accounts.
+ */
+void gaim_request_field_account_set_show_all(GaimRequestField *field,
+											 gboolean show_all);
+
+/**
+ * Returns the default account in an account field.
+ *
+ * @param field The field.
+ *
+ * @return The default account.
+ */
+GaimAccount *gaim_request_field_account_get_default_value(
+		const GaimRequestField *field);
+
+/**
+ * Returns the user-entered account in an account field.
+ *
+ * @param field The field.
+ *
+ * @return The user-entered account.
+ */
+GaimAccount *gaim_request_field_account_get_value(
+		const GaimRequestField *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.
+ *
+ * @param field    The account field.
+ * @param show_all Whether or not to show all accounts.
+ */
+gboolean gaim_request_field_account_get_show_all(
+		const GaimRequestField *field);
+
+/*@}*/
+
+/**************************************************************************/
 /** @name Request API                                                     */
 /**************************************************************************/
 /*@{*/