Added ToolTipProvider interface, and track and pass along the mouse

position associated with tool tip display so that tool tips can be
positioned more appropriately within their container.


git-svn-id: https://samskivert.googlecode.com/svn/trunk@313 6335cc39-0255-0410-8fd6-9bcaacd3b74c

projects/samskivert/src/java/com/samskivert/swing/ToolTipManager.java

@@ -1,5 +1,5 @@
 //
-// $Id: ToolTipManager.java,v 1.2 2001/08/23 00:16:21 shaper Exp $
+// $Id: ToolTipManager.java,v 1.3 2001/08/28 23:51:48 shaper Exp $
 
 package com.samskivert.swing;
 
@@ -40,6 +40,7 @@ public class ToolTipManager implements Interval, AncestorListener
 
 	// set up our starting state
 	_lastmove = System.currentTimeMillis();
+	_lastx = _lasty = -1;
 	_fastshow = false;
 	_tipdelay = TIP_INTERVAL;
 
@@ -111,7 +112,7 @@ public class ToolTipManager implements Interval, AncestorListener
 	return (_fastshow || (now - _lastmove >= _tipdelay));
     }
 
-    protected void updateObject (Object target)
+    protected void updateObject (ToolTipProvider target)
     {
 	_curobj = target;
 	_lastmove = System.currentTimeMillis();
@@ -126,21 +127,23 @@ public class ToolTipManager implements Interval, AncestorListener
      * manages is entered.
      *
      * @param target the object entered.
+     * @param x the mouse x-position.
+     * @param y the mouse y-position.
      */
-    public void handleMouseEntered (Object target)
+    public void handleMouseEntered (ToolTipProvider target, int x, int y)
     {
 	_action = A_SHOW;
 	updateObject(target);
+	_lastx = x;
+	_lasty = y;
     }
 
     /**
      * Handle mouse exited events for a given object.  The {@link
      * ToolTipObserver} should call this method whenever an object it
      * manages is exited.
-     *
-     * @param target the object exited.
      */
-    public void handleMouseExited (Object target)
+    public void handleMouseExited ()
     {
 	_action = A_HIDE;
 	updateObject(null);
@@ -153,7 +156,7 @@ public class ToolTipManager implements Interval, AncestorListener
      *
      * @param target the object clicked on.
      */
-    public void handleMouseClicked (Object target)
+    public void handleMouseClicked (ToolTipProvider target)
     {
 	_action = A_HIDE;
 	updateObject(target);
@@ -166,12 +169,19 @@ public class ToolTipManager implements Interval, AncestorListener
      * Handle mouse moved events.  The {@link ToolTipObserver} should
      * call this method whenever the mouse is moved within its
      * container bounds.
+     *
+     * @param x the mouse x-position.
+     * @param y the mouse y-position.
      */
-    public void handleMouseMoved ()
+    public void handleMouseMoved (int x, int y)
     {
 	// just update the last moved time since we don't perform any
 	// tip antics purely as a result of mouse movement
 	_lastmove = System.currentTimeMillis();
+
+	// and save the mouse position
+	_lastx = x;
+	_lasty = y;
     }
 
     /**
@@ -195,7 +205,7 @@ public class ToolTipManager implements Interval, AncestorListener
      */
     class TipTask implements Runnable
     {
-	public TipTask (Object obj, int action)
+	public TipTask (ToolTipProvider obj, int action)
 	{
 	    _obj = obj;
 	    _action = action;
@@ -204,12 +214,12 @@ public class ToolTipManager implements Interval, AncestorListener
 	public void run ()
 	{
 	    switch (_action) {
-	    case A_SHOW: _obs.showToolTip(_obj); break;
+	    case A_SHOW: _obs.showToolTip(_obj, _lastx, _lasty); break;
 	    case A_HIDE: _obs.hideToolTip(); break;
 	    }
 	}
 
-	protected Object _obj;
+	protected ToolTipProvider _obj;
 	protected int _action;
     }
 
@@ -247,7 +257,10 @@ public class ToolTipManager implements Interval, AncestorListener
     protected long _lastmove;
 
     /** The current object the mouse is within. */
-    protected Object _curobj;
+    protected ToolTipProvider _curobj;
+
+    /** The last known mouse position. */
+    protected int _lastx, _lasty;
 
     /** The next tool tip action to perform. */
     protected int _action;

projects/samskivert/src/java/com/samskivert/swing/ToolTipObserver.java

@@ -1,5 +1,5 @@
 //
-// $Id: ToolTipObserver.java,v 1.2 2001/08/23 00:16:21 shaper Exp $
+// $Id: ToolTipObserver.java,v 1.3 2001/08/28 23:51:48 shaper Exp $
 
 package com.samskivert.swing;
 
@@ -13,12 +13,14 @@ import javax.swing.JComponent;
 public interface ToolTipObserver
 {
     /**
-     * Called when the tool tip associated with the given target
+     * Called when the tool tip associated with the given provider
      * should be displayed.
      *
-     * @param target the object whose tool tip should be shown.
+     * @param tipper the tool tip provider.
+     * @param x the last mouse x-position.
+     * @param y the last mouse y-position.
      */
-    public void showToolTip (Object target);
+    public void showToolTip (ToolTipProvider tipper, int x, int y);
 
     /**
      * Called when any visible tool tip should be hidden and so the

projects/samskivert/src/java/com/samskivert/swing/ToolTipProvider.java

@@ -0,0 +1,29 @@
+//
+// $Id: ToolTipProvider.java,v 1.1 2001/08/28 23:51:48 shaper Exp $
+
+package com.samskivert.swing;
+
+import java.awt.*;
+
+/**
+ * An interface to be implemented by objects that may have a tool tip
+ * associated with themselves.
+ */
+public interface ToolTipProvider
+{
+    /**
+     * Render a tool tip for this object to the given graphics context.
+     *
+     * @param g the graphics context.
+     * @param x the x-position at which the tip should be drawn.
+     * @param y the y-position at which the tip should be drawn.
+     */
+    public void paintToolTip (Graphics g, int x, int y);
+
+    /**
+     * Return the dimensions of the tool tip.
+     *
+     * @param g the graphics context to which the tip will be rendered.
+     */
+    public Dimension getToolTipSize (Graphics g);
+}

projects/samskivert/src/java/com/samskivert/swing/util/ToolTipUtil.java

@@ -0,0 +1,50 @@
+//
+// $Id: ToolTipUtil.java,v 1.1 2001/08/28 23:51:48 shaper Exp $
+
+package com.samskivert.swing.util;
+
+import java.awt.*;
+
+/**
+ * Miscellaneous useful tool tip related utility functions.
+ */
+public class ToolTipUtil
+{
+    /**
+     * Returns an eminently reasonable position at which the tool tip
+     * may be displayed so as to maximize its visibility while still
+     * placing it as near the relevant mouse position as is feasible.
+     *
+     * @param x the mouse x-position associated with the tool tip.
+     * @param y the mouse y-position associated with the tool tip.
+     * @param tip the tool tip dimensions.
+     * @param bounds the tool tip container's bounding rectangle.
+     */
+    public static Point getTipPosition (
+	int x, int y, Dimension tip, Rectangle bounds)
+    {
+	Rectangle tiprect = new Rectangle(x, y, tip.width, tip.height);
+
+	// make sure left edge of tip is within bounds
+	if (tiprect.x < bounds.x) {
+	    tiprect.x = bounds.x;
+	}
+
+	// make sure top edge of tip is within bounds
+	if (tiprect.y < bounds.y) {
+	    tiprect.y = bounds.y;
+	}
+
+	// do our best to fit entire tip into bounds horizontally
+	if ((tiprect.x + tiprect.width) > (bounds.x + bounds.width)) {
+	    tiprect.x = (bounds.x + bounds.width) - tiprect.width;
+	}
+
+	// do our best to fit entire tip into bounds vertically
+	if ((tiprect.y + tiprect.height) > (bounds.y + bounds.height)) {
+	    tiprect.y = (bounds.y + bounds.height) - tiprect.height;
+	}
+
+	return new Point(tiprect.x, tiprect.y);
+    }
+}