diff libgaim/notify.h @ 15144:b81e4e44b509

[gaim-migrate @ 17929] User Info and Tooltips now use the GaimNotifyUserInfo object and methods defined in notify.h. GaimNotifyUserInfo objects encapsulate a list of GaimNotifyUserInfoEntry objects, each of which may have a label, a value, and be specified to be a section header. This moves the burden of UI generation of user information from the various prpls to the UI. The UI can choose how to display the information rather than being fenced into a particular HTML formatting. Consistency across the prpls' information presentation is now enforced, as well. gaim_notify_user_info_get_text_with_newline() generates text in the: <b>label</b>: value <b>label</b>: value format as was passed by convention from prpls in the past. committer: Tailor Script <[e-mail]>

--- a/libgaim/notify.h	Sat Dec 09 20:20:17 2006 +0000
+++ b/libgaim/notify.h	Sun Dec 10 02:53:09 2006 +0000
@@ -29,9 +29,11 @@
 #include <glib-object.h>
 #include <glib.h>
 
+typedef struct _GaimNotifyUserInfoEntry	GaimNotifyUserInfoEntry;
+typedef struct _GaimNotifyUserInfo	GaimNotifyUserInfo;
+
 #include "connection.h"
 
-
 /**
  * Notification close callbacks.
  */
@@ -154,7 +156,7 @@
 	                                      void *data);
 
 	void *(*notify_userinfo)(GaimConnection *gc, const char *who,
-	                         const char *text);
+	                         GaimNotifyUserInfo *user_info);
 
 	void *(*notify_uri)(const char *uri);
 
@@ -403,20 +405,113 @@
  * The text is essentially a stripped-down format of HTML, the same that
  * IMs may send.
  *
- * @param gc	    The GaimConnection handle associated with the information.
- * @param who	    The username associated with the information.
- * @param text      The formatted text.
- * @param cb        The callback to call when the user closes
- *                  the notification.
- * @param user_data The data to pass to the callback.
+ * @param gc		         The GaimConnection handle associated with the information.
+ * @param who				 The username associated with the information.
+ * @param user_info          The GaimNotifyUserInfo which contains the information
+ * @param cb                 The callback to call when the user closes
+ *                           the notification.
+ * @param user_data          The data to pass to the callback.
  *
  * @return A UI-specific handle.
  */
 void *gaim_notify_userinfo(GaimConnection *gc, const char *who,
-						   const char *text, GaimNotifyCloseCallback cb,
+						   GaimNotifyUserInfo *user_info, GaimNotifyCloseCallback cb,
 						   gpointer user_data);
 
 /**
+ * Create a new GaimNotifyUserInfo which is suitable for passing to gaim_notify_userinfo()
+ *
+ * @return A new GaimNotifyUserInfo, which the caller must destroy when done
+ */
+GaimNotifyUserInfo *gaim_notify_user_info_new();
+
+/**
+ * Destroy a GaimNotifyUserInfo
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ */
+void gaim_notify_user_info_destroy(GaimNotifyUserInfo *user_info);
+
+/**
+ * Retrieve the array of GaimNotifyUserInfoEntry objects from a GaimNotifyUserInfo
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ *
+ * @result                   A GList of GaimNotifyUserInfoEntry objects
+ */
+GList *gaim_notify_user_info_get_entries(GaimNotifyUserInfo *user_info);
+
+/**
+ * Create a textual representation of a GaimNotifyUserInfo, separating entries with newline
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ * @param newline            The separation character
+ */
+char *gaim_notify_user_info_get_text_with_newline(GaimNotifyUserInfo *user_info, const char *newline);
+
+/**
+ * Add a label/value pair to a GaimNotifyUserInfo object.  GaimNotifyUserInfo keeps track of the order in which pairs are added.
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
+ *                           If NULL, value will be displayed without a label.
+ * @param value              The value, which might be displayed by a UI after the label.
+ *                           If NULL, label will still be displayed; the UI should then treat label as independent
+ *                           and not include a colon if it would otherwise.
+ */
+void gaim_notify_user_info_add_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);
+
+/**
+ * Prepend a label/value pair to a GaimNotifyUserInfo object
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
+ *                           If NULL, value will be displayed without a label.
+ * @param value              The value, which might be displayed by a UI after the label.
+ *                           If NULL, label will still be displayed; the UI should then treat label as independent
+ *                           and not include a colon if it would otherwise.
+ */
+void gaim_notify_user_info_prepend_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);
+
+/**
+ * Add a section break.  A UI might display this as a horizontal line.
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ */
+void gaim_notify_user_info_add_section_break(GaimNotifyUserInfo *user_info);
+
+/**
+ * Add a section header.  A UI might display this in a different font from other text.
+ *
+ * @param user_info          The GaimNotifyUserInfo
+ * @param label              The name of the section
+ */
+void gaim_notify_user_info_add_section_header(GaimNotifyUserInfo *user_info, const char *label);
+
+/**
+ * Remove the last item which was added to a GaimNotifyUserInfo. This could be used to remove a section header which is not needed.
+ */
+void gaim_notify_user_info_remove_last_item(GaimNotifyUserInfo *user_info);
+
+/**
+ * Get the label for a GaimNotifyUserInfoEntry
+ *
+ * @param user_info_entry     The GaimNotifyUserInfoEntry
+ *
+ * @result                    The label
+ */
+gchar *gaim_notify_user_info_entry_get_label(GaimNotifyUserInfoEntry *user_info_entry);
+
+/**
+ * Get the value for a GaimNotifyUserInfoEntry
+ *
+ * @param user_info_entry     The GaimNotifyUserInfoEntry
+ *
+ * @result                    The value
+ */
+gchar *gaim_notify_user_info_entry_get_value(GaimNotifyUserInfoEntry *user_info_entry);
+
+/**
  * Opens a URI or somehow presents it to the user.
  *
  * @param handle The plugin or connection handle.