| 1 | // |
---|
| 2 | // AISmoothTooltipTracker.h |
---|
| 3 | // Adium |
---|
| 4 | // |
---|
| 5 | // Created by Adam Iser on Tue Jul 27 2004. |
---|
| 6 | // Copyright (c) 2004-2005 The Adium Team. All rights reserved. |
---|
| 7 | // |
---|
| 8 | |
---|
| 9 | |
---|
| 10 | //Delegate handles displaying the tooltips, we handle all the tracking |
---|
| 11 | /*! |
---|
| 12 | * @protocol AISmoothTooltipTrackerDelegate |
---|
| 13 | * @brief Protocol implemented by the <tt>AISmoothTooltipTracker</tt> delegate |
---|
| 14 | * |
---|
| 15 | * An AISmoothTooltipTracker delegate is required to implement <tt>AISmoothTooltipTrackerDelegate</tt>. |
---|
| 16 | */ |
---|
| 17 | @protocol AISmoothTooltipTrackerDelegate |
---|
| 18 | /*! |
---|
| 19 | * @brief Informs the delegate the point at which the mouse is hovering. |
---|
| 20 | * |
---|
| 21 | * Sent continuously as the mouse moves within the visible view monitored by the <tt>AISmoothTooltipTracker</tt>. It is initially sent after the mouse hovers for at least a second in a single location within the view. Sent regardless of whether the application is active or not. |
---|
| 22 | * @param screenPoint The point, in screen coordinates, at which the mouse is hovering. |
---|
| 23 | */ |
---|
| 24 | - (void)showTooltipAtPoint:(NSPoint)screenPoint; |
---|
| 25 | |
---|
| 26 | /*! |
---|
| 27 | * @brief Informs the delegate that the mouse has left the view so the tooltip should be hidden. |
---|
| 28 | * |
---|
| 29 | * Informs the delegate that the mouse has left the view so the tooltip should be hidden. Sent when the mouse leaves the view or it becomes obscured or hidden. |
---|
| 30 | */ |
---|
| 31 | - (void)hideTooltip; |
---|
| 32 | @end |
---|
| 33 | |
---|
| 34 | /*! |
---|
| 35 | * @class AISmoothTooltipTracker |
---|
| 36 | * @brief Controller to track the mouse when it hovers over a view, informing a delegate of the hover point |
---|
| 37 | * |
---|
| 38 | * <p>An <tt>AISmoothTooltipTracker</tt> is created for a specific view. It informs its delegate when the mouse hovers over the view for about a second.</p> |
---|
| 39 | * <p>The delegate will be informed of the mouse hover even if the application is not currently active (so long as the view is visible to the user).</p> |
---|
| 40 | * The delegate is updated as the mouse moves (via showTooltipAtPoint:), and is informed when the mouse leaves or the view is obscured or hidden (via hideTooltip)</p> |
---|
| 41 | * <p>Note: The delegate is not retained. For maximum stability, the delegate should call setDelegate:nil some time before it deallocs. Not all implementations will -need- this, but it is recommended.</p> |
---|
| 42 | */ |
---|
| 43 | @interface AISmoothTooltipTracker : NSObject { |
---|
| 44 | NSView *view; //View we are tracking tooltips for |
---|
| 45 | id<AISmoothTooltipTrackerDelegate> delegate; //Our delegate |
---|
| 46 | |
---|
| 47 | BOOL mouseInside; |
---|
| 48 | |
---|
| 49 | NSPoint lastMouseLocation; //Last known location of the mouse, used for movement tracking |
---|
| 50 | NSTimer *tooltipMouseLocationTimer; //Checks for mouse movement |
---|
| 51 | NSPoint tooltipLocation; //Last tooltip location we told our delegate about |
---|
| 52 | NSTrackingRectTag tooltipTrackingTag; //Tag for our tracking rect |
---|
| 53 | int tooltipCount; //Used to determine how long before a tooltip appears |
---|
| 54 | } |
---|
| 55 | |
---|
| 56 | /*! |
---|
| 57 | * @brief Create an <tt>AISmoothTooltipTracker</tt> |
---|
| 58 | * |
---|
| 59 | * Create and return an autoreleased <tt>AISmoothTooltipTracker</tt> for <tt>inView</tt> and <tt>inDelegate</tt>. |
---|
| 60 | * @param inView The view in which to track mouse movements |
---|
| 61 | * @param inDelegate The |
---|
| 62 | * @result An <tt>AISmoothTooltipTracker</tt> instance |
---|
| 63 | */ |
---|
| 64 | + (AISmoothTooltipTracker *)smoothTooltipTrackerForView:(NSView *)inView withDelegate:(id <AISmoothTooltipTrackerDelegate>)inDelegate; |
---|
| 65 | |
---|
| 66 | /*! |
---|
| 67 | * @brief Set the delegate |
---|
| 68 | * |
---|
| 69 | * Set the delegate. See <tt>AISmoothTooltipTrackerDelegate</tt> protocol discussion for details. |
---|
| 70 | */ |
---|
| 71 | - (void)setDelegate:(id<AISmoothTooltipTrackerDelegate>)inDelegate; |
---|
| 72 | |
---|
| 73 | /*! @brief Retrieve the view that this object tracks |
---|
| 74 | * |
---|
| 75 | * @return The view that was originally passed to <code>+smoothTooltipTrackerForView:withDelegate:</code>. |
---|
| 76 | */ |
---|
| 77 | - (NSView *)view; |
---|
| 78 | |
---|
| 79 | /* |
---|
| 80 | * @brief This should be called when the view for which we are tracking will be removed from its window without the window closing |
---|
| 81 | * |
---|
| 82 | * This allows us to remove our cursor rects (there isn't a notification by which we can do it automatically) |
---|
| 83 | */ |
---|
| 84 | - (void)viewWillBeRemovedFromWindow; |
---|
| 85 | |
---|
| 86 | /* |
---|
| 87 | * @brief After calling viewWillBeRemovedFromWindow, call viewWasAddedToWindow to reinitiate tracking |
---|
| 88 | */ |
---|
| 89 | - (void)viewWasAddedToWindow; |
---|
| 90 | |
---|
| 91 | @end |
---|