Mercurial > pidgin

changeset 21233:110f23ef3542

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Document the with_hint API changes.
author Richard Laager <rlaager@wiktel.com>
date Sun, 14 Oct 2007 03:07:06 +0000
parents b9680933c2c6
children aabe638f56d9 a0769bab5a3d
files ChangeLog.API libpurple/request.h
diffstat 2 files changed, 242 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/ChangeLog.API	Sun Oct 14 02:49:47 2007 +0000
+++ b/ChangeLog.API	Sun Oct 14 03:07:06 2007 +0000
@@ -14,6 +14,7 @@
 		  to unload a plugin--fails.  This then prevents the plugin
 		  from being saved in the saved plugins list, so it'll won't
 		  be loaded at the next startup.
+
 		* pidgin_dialogs_about_with_parent()
 		* pidgin_log_show_contact_with_parent()
 		* pidgin_log_show_with_parent()
@@ -22,6 +23,18 @@
 		* pidgin_pounces_manager_show_with_parent()
 		* pidgin_syslog_show_with_parent()
 
+		* purple_request_accept_cancel_with_hint()
+		* purple_request_action_varg_with_hint()
+		* purple_request_action_with_hint()
+		* purple_request_choice_varg_with_hint()
+		* purple_request_choice_with_hint()
+		* purple_request_fields_with_hint()
+		* purple_request_file_with_hint()
+		* purple_request_folder_with_hint()
+		* purple_request_input_with_hint()
+		* purple_request_ok_cancel_with_hint()
+		* purple_request_yes_no_with_hint()
+
 		Changed:
 		* purple_plugin_unload() now honors the return value of a
 		  plugin's unload function and can actually return FALSE now.
@@ -38,6 +51,18 @@
 		* pidgin_pounces_manager_show()
 		* pidgin_syslog_show()
 
+		* purple_request_accept_cancel()
+		* purple_request_action_varg()
+		* purple_request_action()
+		* purple_request_choice_varg()
+		* purple_request_choice()
+		* purple_request_fields()
+		* purple_request_file()
+		* purple_request_folder()
+		* purple_request_input()
+		* purple_request_ok_cancel()
+		* purple_request_yes_no()
+
 version 2.2.2 (??/??/????):
 	libpurple:
 		Changed:
--- a/libpurple/request.h	Sun Oct 14 02:49:47 2007 +0000
+++ b/libpurple/request.h	Sun Oct 14 03:07:06 2007 +0000
@@ -1303,6 +1303,8 @@
  * @param user_data     The data to pass to the callback.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_input_with_hint(void *handle, const char *title,
 						 const char *primary, const char *secondary,
@@ -1314,6 +1316,42 @@
 						 const char *ui_hint, void *user_data);
 
 /**
+ * Prompts the user for text input.
+ *
+ * @param 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, say, when
+ *                      you sign offline.  If the request is NOT
+ *                      closed it is VERY likely to cause a crash
+ *                      whenever the callback handler functions are
+ *                      triggered.
+ * @param title         The title of the message.
+ * @param primary       The main point of the message.
+ * @param secondary     The secondary information.
+ * @param default_value The default value.
+ * @param multiline     TRUE if the inputted text can span multiple lines.
+ * @param masked        TRUE if the inputted text should be masked in some way.
+ * @param hint          Optionally suggest how the input box should appear.
+ *                      Use "html," for example, to allow the user to enter
+ *                      HTML.
+ * @param ok_text       The text for the @c OK button.
+ * @param ok_cb         The callback for the @c OK button.
+ * @param cancel_text   The text for the @c Cancel button.
+ * @param cancel_cb     The callback for the @c Cancel button.
+ * @param account		The PurpleAccount associated with this request, or NULL if none is
+ * @param who			The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv			The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint       UI hint
+ * @param user_data     The data to pass to the callback.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_input_with_hint() instead.
  */
 void *purple_request_input(void *handle, const char *title,
@@ -1348,6 +1386,8 @@
  *                      terminated with a NULL parameter.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_choice_with_hint(void *handle, const char *title,
 						  const char *primary, const char *secondary,
@@ -1358,6 +1398,29 @@
 						  const char *ui_hint, void *user_data, ...) G_GNUC_NULL_TERMINATED;
 
 /**
+ * Prompts the user for multiple-choice input.
+ *
+ * @param handle        The plugin or connection handle.  For some
+ *                      things this is EXTREMELY important.  See
+ *                      the comments on purple_request_input.
+ * @param title         The title of the message.
+ * @param primary       The main point of the message.
+ * @param secondary     The secondary information.
+ * @param default_value The default value.
+ * @param ok_text       The text for the @c OK button.
+ * @param ok_cb         The callback for the @c OK button.
+ * @param cancel_text   The text for the @c Cancel button.
+ * @param cancel_cb     The callback for the @c Cancel button.
+ * @param account		The PurpleAccount associated with this request, or NULL if none is
+ * @param who			The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv			The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint       UI hint
+ * @param user_data     The data to pass to the callback.
+ * @param ...           The choices.  This argument list should be
+ *                      terminated with a NULL parameter.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_choice_with_hint() instead.
  */
 void *purple_request_choice(void *handle, const char *title,
@@ -1391,6 +1454,8 @@
  *                      terminated with a @c NULL parameter.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_choice_varg_with_hint(void *handle, const char *title,
 							   const char *primary, const char *secondary,
@@ -1401,6 +1466,29 @@
 							   const char *ui_hint, void *user_data, va_list choices);
 
 /**
+ * Prompts the user for multiple-choice input.
+ *
+ * @param handle        The plugin or connection handle.  For some
+ *                      things this is EXTREMELY important.  See
+ *                      the comments on purple_request_input.
+ * @param title         The title of the message.
+ * @param primary       The main point of the message.
+ * @param secondary     The secondary information.
+ * @param default_value The default value.
+ * @param ok_text       The text for the @c OK button.
+ * @param ok_cb         The callback for the @c OK button.
+ * @param cancel_text   The text for the @c Cancel button.
+ * @param cancel_cb     The callback for the @c Cancel button.
+ * @param account		The PurpleAccount associated with this request, or NULL if none is
+ * @param who			The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv			The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint       UI hint
+ * @param user_data     The data to pass to the callback.
+ * @param choices       The choices.  This argument list should be
+ *                      terminated with a @c NULL parameter.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_choice_varg_with_hint() instead.
  */
 void *purple_request_choice_varg(void *handle, const char *title,
@@ -1438,6 +1526,8 @@
  *                       function to use when the button is clicked.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_action_with_hint(void *handle, const char *title,
 						  const char *primary, const char *secondary,
@@ -1446,6 +1536,33 @@
 						  const char *ui_hint, 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.
+ *
+ * @param handle         The plugin or connection handle.  For some
+ *                       things this is EXTREMELY important.  See
+ *                       the comments on purple_request_input.
+ * @param title          The title of the message.
+ * @param primary        The main point of the message.
+ * @param secondary      The secondary information.
+ * @param default_action The default value.
+ * @param account		 The PurpleAccount associated with this request, or NULL if none is
+ * @param who			 The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv			 The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint        UI hint
+ * @param user_data      The data to pass to the callback.
+ * @param action_count   The number of actions.
+ * @param ...            A list of actions.  These are pairs of
+ *                       arguments.  The first of each pair is the
+ *                       string 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 callback
+ *                       function to use when the button is clicked.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_action_with_hint() instead.
  */
 void *purple_request_action(void *handle, const char *title,
@@ -1475,6 +1592,8 @@
  * @param actions        A list of actions and callbacks.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_action_varg_with_hint(void *handle, const char *title,
 							   const char *primary, const char *secondary,
@@ -1484,6 +1603,27 @@
 							   va_list actions);
 
 /**
+ * Prompts the user for an action.
+ *
+ * This is often represented as a dialog with a button for each action.
+ *
+ * @param handle         The plugin or connection handle.  For some
+ *                       things this is EXTREMELY important.  See
+ *                       the comments on purple_request_input.
+ * @param title          The title of the message.
+ * @param primary        The main point of the message.
+ * @param secondary      The secondary information.
+ * @param default_action The default value.
+ * @param account		 The PurpleAccount associated with this request, or NULL if none is
+ * @param who			 The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv			 The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint        UI hint
+ * @param user_data      The data to pass to the callback.
+ * @param action_count   The number of actions.
+ * @param actions        A list of actions and callbacks.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_action_varg_with_hint() instead.
  */
 void *purple_request_action_varg(void *handle, const char *title,
@@ -1514,6 +1654,8 @@
  * @param user_data   The data to pass to the callback.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_fields_with_hint(void *handle, const char *title,
 						  const char *primary, const char *secondary,
@@ -1524,6 +1666,27 @@
 						  const char *ui_hint, void *user_data);
 
 /**
+ * Displays groups of fields for the user to fill in.
+ *
+ * @param handle      The plugin or connection handle.  For some
+ *                    things this is EXTREMELY important.  See
+ *                    the comments on purple_request_input.
+ * @param title       The title of the message.
+ * @param primary     The main point of the message.
+ * @param secondary   The secondary information.
+ * @param fields      The list of fields.
+ * @param ok_text     The text for the @c OK button.
+ * @param ok_cb       The callback for the @c OK button.
+ * @param cancel_text The text for the @c Cancel button.
+ * @param cancel_cb   The callback for the @c Cancel button.
+ * @param account	  The PurpleAccount associated with this request, or NULL if none is
+ * @param who		  The username of the buddy associated with this request, or NULL if none is
+ * @param conv		  The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint     UI hint
+ * @param user_data   The data to pass to the callback.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_fields_with_hint() instead.
  */
 void *purple_request_fields(void *handle, const char *title,
@@ -1551,6 +1714,8 @@
 
 /**
  * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.
+ *
+ * @since 2.3.0
  */
 #define purple_request_yes_no_with_hint(handle, title, primary, secondary, \
 							default_action, account, who, conv, \
@@ -1560,6 +1725,8 @@
 						_("_Yes"), (yes_cb), _("_No"), (no_cb))
 
 /**
+ * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.
+ *
  * @deprecated Please use purple_request_yes_no_with_hint instead.
  */
 #define purple_request_yes_no(handle, title, primary, secondary, \
@@ -1571,6 +1738,8 @@
 
 /**
  * A wrapper for purple_request_action() that uses @c OK and @c Cancel buttons.
+ *
+ * @since 2.3.0
  */
 #define purple_request_ok_cancel_with_hint(handle, title, primary, secondary, \
 							default_action, account, who, conv, \
@@ -1580,6 +1749,8 @@
 						_("_OK"), (ok_cb), _("_Cancel"), (cancel_cb))
 
 /**
+ * A wrapper for purple_request_action() that uses @c OK and @c Cancel buttons.
+ *
  * @deprecated Please use purple_request_ok_cancel_with_hint instead.
  */
 #define purple_request_ok_cancel(handle, title, primary, secondary, \
@@ -1591,6 +1762,8 @@
 
 /**
  * A wrapper for purple_request_action() that uses Accept and Cancel buttons.
+ *
+ * @since 2.3.0
  */
 #define purple_request_accept_cancel_with_hint(handle, title, primary, secondary, \
 								   default_action, account, who, conv, \
@@ -1600,6 +1773,8 @@
 						_("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
 
 /**
+ * A wrapper for purple_request_action() that uses Accept and Cancel buttons.
+ *
  * @deprecated Please use purple_request_accept_cancel_with_hint instead.
  */
 #define purple_request_accept_cancel(handle, title, primary, secondary, \
@@ -1629,6 +1804,8 @@
  * @param user_data   The data to pass to the callback.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_file_with_hint(void *handle, const char *title, const char *filename,
 						gboolean savedialog,
@@ -1637,6 +1814,26 @@
 						const char *ui_hint, 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.
+ *
+ * @param handle      The plugin or connection handle.  For some
+ *                    things this is EXTREMELY important.  See
+ *                    the comments on purple_request_input.
+ * @param title       The title for the dialog (may be @c NULL)
+ * @param filename    The default filename (may be @c NULL)
+ * @param savedialog  True if this dialog is being used to save a file.
+ *                    False if it is being used to open a file.
+ * @param ok_cb       The callback for the @c OK button.
+ * @param cancel_cb   The callback for the @c Cancel button.
+ * @param account	  The PurpleAccount associated with this request, or NULL if none is
+ * @param who		  The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv		  The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint     UI hint
+ * @param user_data   The data to pass to the callback.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_file_with_hint() instead.
  */
 void *purple_request_file(void *handle, const char *title, const char *filename,
@@ -1663,6 +1860,8 @@
  * @param user_data   The data to pass to the callback.
  *
  * @return A UI-specific handle.
+ *
+ * @since 2.3.0
  */
 void *purple_request_folder_with_hint(void *handle, const char *title, const char *dirname,
 						GCallback ok_cb, GCallback cancel_cb,
@@ -1670,6 +1869,24 @@
 						const char *ui_hint, void *user_data);
 
 /**
+ * Displays a folder select dialog. Returns the selected filename to
+ * the callback.
+ *
+ * @param handle      The plugin or connection handle.  For some
+ *                    things this is EXTREMELY important.  See
+ *                    the comments on purple_request_input.
+ * @param title       The title for the dialog (may be @c NULL)
+ * @param dirname     The default directory name (may be @c NULL)
+ * @param ok_cb       The callback for the @c OK button.
+ * @param cancel_cb   The callback for the @c Cancel button.
+ * @param account	  The PurpleAccount associated with this request, or NULL if none is
+ * @param who		  The username of the buddy assocaited with this request, or NULL if none is
+ * @param conv		  The PurpleConversation associated with this request, or NULL if none is
+ * @param ui_hint     UI hint
+ * @param user_data   The data to pass to the callback.
+ *
+ * @return A UI-specific handle.
+ *
  * @deprecated Please use purple_request_folder_with_hint() instead.
  */
 void *purple_request_folder(void *handle, const char *title, const char *dirname,