From ff38af4cf407d21232ec74f34e0c114a66fd9ab0 Mon Sep 17 00:00:00 2001
From: Thomas Leonard <talex5@gmail.com>
Date: Wed, 18 Jun 2008 11:13:34 +0100
Subject: [PATCH] Documented and cleaned TreeTips API.

---
 zeroinstall/0launch-gui/iface_browser.py |  4 ++--
 zeroinstall/0launch-gui/impl_list.py     |  3 ++-
 zeroinstall/gtkui/treetips.py            | 25 +++++++++++++++++++++----
 3 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/zeroinstall/0launch-gui/iface_browser.py b/zeroinstall/0launch-gui/iface_browser.py
index 849864b..760a6c9 100644
--- a/zeroinstall/0launch-gui/iface_browser.py
+++ b/zeroinstall/0launch-gui/iface_browser.py
@@ -27,8 +27,8 @@ class InterfaceTips(TreeTips):
 	def __init__(self, mainwindow):
 		self.mainwindow = mainwindow
 
-	def get_tooltip_text(self, item):
-		interface, model_column = item
+	def get_tooltip_text(self):
+		interface, model_column = self.item
 		assert interface
 		if model_column == InterfaceBrowser.INTERFACE_NAME:
 			return _("Full name: %s") % interface.uri
diff --git a/zeroinstall/0launch-gui/impl_list.py b/zeroinstall/0launch-gui/impl_list.py
index bc50931..6a81673 100644
--- a/zeroinstall/0launch-gui/impl_list.py
+++ b/zeroinstall/0launch-gui/impl_list.py
@@ -36,7 +36,8 @@ class ImplTips(TreeTips):
 		self.policy = policy
 		self.interface = interface
 
-	def get_tooltip_text(self, impl):
+	def get_tooltip_text(self):
+		impl = self.item
 		if impl.id.startswith('/'):
 			return _("Local: %s") % impl.id
 		if impl.id.startswith('package:'):
diff --git a/zeroinstall/gtkui/treetips.py b/zeroinstall/gtkui/treetips.py
index 9008117..85f4012 100644
--- a/zeroinstall/gtkui/treetips.py
+++ b/zeroinstall/gtkui/treetips.py
@@ -1,9 +1,17 @@
+"""Add tooltips to a TreeView."""
 # Copyright (C) 2008, Thomas Leonard
 # See the README file for details, or visit http://0install.net.
 
 import time, gobject, gtk
 
 class TreeTips:
+	"""This object allows you to set location-dependent tooltips on a TreeView.
+	Connect your TreeView's leave-notify-event to the L{hide} method.
+	In your motion-notify-event handler, call L{prime} when the pointer moves
+	to an area with a new message. The message will be shown after a delay.
+	If calculation of the message is expensive, override L{get_tooltip_text}
+	instead.
+	"""
 	timeout = None
 	widget = None
 	item = None
@@ -21,7 +29,7 @@ class TreeTips:
 		if self.item is None:
 			return
 
-		text = self.get_tooltip_text(self.item)
+		text = self.get_tooltip_text()
 		if not text:
 			return
 
@@ -60,6 +68,11 @@ class TreeTips:
 		self.time = time.time()
 	
 	def prime(self, parent, item):
+		"""Call this whenever the pointer moves to an area with a different
+		tooltip.
+		@param param: the TreeView widget
+		@param item: the text to display
+		@see L{get_tooltip_text}"""
 		self.hide()
 		assert self.timeout is None
 		self.item = item
@@ -82,9 +95,13 @@ class TreeTips:
 		pass
 	
 	def hide(self):
+		"""Hide the tooltip, if any.
+		Sets L{item} to None."""
 		self.item = None
 		self.show(None)
 	
-	def get_tooltip_text(self, item):
-		"Override in subclasses."
-		return str(item)
+	def get_tooltip_text(self):
+		""""Converts the object passed to L{prime} to a string for display.
+		The default implementation just calls C{str}, but subclasses can override it.
+		@return: the tooltip message"""
+		return str(self.item)
-- 
2.11.4.GIT