# HG changeset patch # User Richard Laager # Date 1192331226 0 # Node ID 110f23ef354245ebc27c4b05420e6f6e20f0dc49 # Parent b9680933c2c6d81bf83b0765e10dddc8901905e5 Document the with_hint API changes. diff -r b9680933c2c6 -r 110f23ef3542 ChangeLog.API --- 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: diff -r b9680933c2c6 -r 110f23ef3542 libpurple/request.h --- 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,