diff pidgin/pidgintooltip.h @ 21885:f5d961556972

Refactor some of the tooltip drawing functions. And add some pretend docs. Also, fix a bug where a tooltip would popup when hovering over the treeview headers (in the roomlist, for example).

--- a/pidgin/pidgintooltip.h	Tue Dec 18 06:32:42 2007 +0000
+++ b/pidgin/pidgintooltip.h	Tue Dec 18 09:17:39 2007 +0000
@@ -28,26 +28,57 @@
 
 #include <gtk/gtk.h>
 
-typedef gboolean (*PidginTooltipCreateForTree)(GtkWidget *window, GtkTreePath *path, gpointer userdata, int *w, int *h);
-typedef gboolean (*PidginTooltipCreate)(GtkWidget *window, gpointer userdata, int *w, int *h);
-typedef gboolean (*PidginTooltipPaint)(GtkWidget *widget, GdkEventExpose *event, gpointer data);
+/**
+ * @param tipwindow  The window for the tooltip.
+ * @param path       The GtkTreePath representing the row under the cursor.
+ * @param userdata   The userdata set during pidgin_tooltip_setup_for_treeview.
+ * @param w          The value of this should be set to the desired width of the tooltip window.
+ * @param h          The value of this should be set to the desired height of the tooltip window.
+ *
+ * @return  @c TRUE if the tooltip was created correctly, @c FALSE otherwise.
+ * @since 2.4.0
+ */
+typedef gboolean (*PidginTooltipCreateForTree)(GtkWidget *tipwindow,
+			GtkTreePath *path, gpointer userdata, int *w, int *h);
+
+/**
+ * @param tipwindow  The window for the tooltip.
+ * @param userdata   The userdata set during pidgin_tooltip_show.
+ * @param w          The value of this should be set to the desired width of the tooltip window.
+ * @param h          The value of this should be set to the desired height of the tooltip window.
+ *
+ * @return  @c TRUE if the tooltip was created correctly, @c FALSE otherwise.
+ * @since 2.4.0
+ */
+typedef gboolean (*PidginTooltipCreate)(GtkWidget *tipwindow,
+			gpointer userdata, int *w, int *h);
+
+/**
+ * @param  tipwindow   The window for the tooltip.
+ * @param  userdata    The userdata set during pidgin_tooltip_setup_for_treeview or pidgin_tooltip_show.
+ *
+ * @return  @c TRUE if the tooltip was painted correctly, @c FALSE otherwise.
+ * @since 2.4.0
+ */
+typedef gboolean (*PidginTooltipPaint)(GtkWidget *tipwindow, gpointer userdata);
 
 /**
  * Setup tooltip drawing functions for a treeview.
  *
  * @param tree         The treeview
  * @param userdata     The userdata to send to the callback functions
- * @param create_cb    Callback function to create the tooltip from the GtkTreePath
+ * @param create_cb    Callback function to create the tooltip for a GtkTreePath
  * @param paint_cb     Callback function to paint the tooltip
  *
  * @return   @c TRUE if the tooltip callbacks were setup correctly.
- * @since
+ * @since 2.4.0
  */
 gboolean pidgin_tooltip_setup_for_treeview(GtkWidget *tree, gpointer userdata,
 		PidginTooltipCreateForTree create_cb, PidginTooltipPaint paint_cb);
 
 /**
  * Destroy the tooltip.
+ * @since 2.4.0
  */
 void pidgin_tooltip_destroy(void);
 
@@ -59,7 +90,7 @@
  * @param create_cb    Callback function to create the tooltip from the GtkTreePath
  * @param paint_cb     Callback function to paint the tooltip
  *
- * @since
+ * @since 2.4.0
  */
 void pidgin_tooltip_show(GtkWidget *widget, gpointer userdata,
 		PidginTooltipCreate create_cb, PidginTooltipPaint paint_cb);