1 // TipManager.h 2 // 3 // PURPOSE 4 // Maintains a set of pop-up tips bound to rectangular 5 // regions of any number of views. Also provides for 6 // simple 'manual' operation: call showTip() with text and 7 // a screen rectangle, and the tip will be displayed after 8 // the mouse has idled in that rectangle. 9 // 10 // HISTORY 11 // e.moon 27oct99: Substantial bugfixes (removal of entire 12 // view hierarchies' tips now works). 13 // 14 // e.moon 19oct99: TipManager now derives from BWindow. 15 // 16 // e.moon 17oct99: reworked the tip window: now exposed via the 17 // TipWindow & TipView classes. 18 // 19 // e.moon 27sep99: optimized TipManager::run() (no longer pounds 20 // the CPU when idling in a view) 21 // 22 // e.moon 13may99: moved TipManager's privates into 23 // TipManagerImpl.h 24 // 25 // e.moon 12may99: expanded to TipManager 26 // e.moon 11may99: begun as TipTriggerThread 27 28 #ifndef __TipManager_H__ 29 #define __TipManager_H__ 30 31 #include <SupportDefs.h> 32 #include <Font.h> 33 #include <Point.h> 34 #include <Rect.h> 35 #include <GraphicsDefs.h> 36 #include <String.h> 37 38 #include <Locker.h> 39 #include <Window.h> 40 41 class BView; 42 43 #include "cortex_defs.h" 44 __BEGIN_CORTEX_NAMESPACE 45 46 class TipWindow; 47 48 class _TipManagerView; 49 class _ViewEntry; 50 class _WindowEntry; 51 52 class TipManager : 53 protected BWindow { 54 typedef BWindow _inherited; 55 56 public: 57 static const BPoint s_useDefaultOffset; 58 static const BPoint s_defaultOffset; 59 60 static const bigtime_t s_defIdleTime; 61 static const bigtime_t s_sleepPeriod; 62 63 public: // *** types & constants 64 enum flag_t { 65 NONE 66 }; 67 68 enum offset_mode_t { 69 // offset determines left/top point of tip window 70 LEFT_OFFSET_FROM_RECT, // from the right bound 71 LEFT_OFFSET_FROM_POINTER, 72 73 // offset determines right/top point of tip window 74 // (x offset is inverted; y isn't) 75 RIGHT_OFFSET_FROM_RECT, // from the left bound 76 RIGHT_OFFSET_FROM_POINTER 77 }; 78 79 public: // *** dtor 80 virtual ~TipManager(); 81 82 public: // *** singleton access 83 static TipManager* Instance(); 84 static void QuitInstance(); 85 86 private: // hidden constructor (use Instance() to access 87 // a single instance) 88 TipManager(); 89 90 public: // *** add and remove tips 91 92 // add or modify a tip: 93 94 // child allows tips to be added to child views of the main 95 // target view. rect is in view coordinates; only one tip 96 // may exist for a particular view with a given top-left 97 // corner -- you don't want tip rectangles to overlap in general, 98 // but TipManager won't stop you from trying. Yet. 99 // [13may99] 100 101 status_t setTip( 102 const BRect& rect, 103 const char* text, 104 BView* view, 105 offset_mode_t offsetMode =LEFT_OFFSET_FROM_POINTER, 106 BPoint offset =s_useDefaultOffset, 107 uint32 flags =NONE); 108 109 // This version of setTip() maps a tip to the entire frame 110 // rectangle of a child view. This call will fail if tips 111 // are already being managed for that view; once a 112 // full-view tip has been added future attempts call any 113 // version of setTip() for that view will also fail. 114 // [13may99] 115 116 status_t setTip( 117 const char* text, 118 BView* view, 119 offset_mode_t offsetMode =LEFT_OFFSET_FROM_POINTER, 120 BPoint offset =s_useDefaultOffset, 121 uint32 flags =NONE); 122 123 // Remove all tips matching the given rectangle and/or child 124 // view. 125 126 status_t removeTip( 127 const BRect& rect, 128 BView* view); 129 130 status_t removeAll( 131 BView* view); 132 133 status_t removeAll( 134 BWindow* window); 135 136 public: // *** manual tip arming 137 138 // [e.moon 19oct99] 139 // Call when the mouse has entered a particular region of 140 // the screen for which you want a tip to be displayed. 141 // The tip will be displayed if the mouse stops moving 142 // for idleTime microseconds within the rectangle screenRect. 143 144 status_t showTip( 145 const char* text, 146 BRect screenRect, 147 offset_mode_t offsetMode =LEFT_OFFSET_FROM_POINTER, 148 BPoint offset =s_useDefaultOffset, 149 uint32 flags =NONE); 150 151 // [e.moon 22oct99] 152 // Call to immediately hide a visible tip. You need to know 153 // the screen rectangle for which the tip was shown (which is easy 154 // if was displayed due to a showTip() call -- pass the same 155 // screenRect argument.) 156 // If the tip was found & hidden, returns B_OK; if there's 157 // no visible tip or it was triggered by a different rectangle, 158 // returns B_BAD_VALUE. 159 160 status_t hideTip( 161 BRect screenRect); 162 163 public: // *** BWindow 164 165 public: // *** BLooper 166 167 virtual bool QuitRequested(); 168 169 public: // *** BHandler 170 171 virtual void MessageReceived( 172 BMessage* message); 173 174 private: 175 176 // --------------------------------------------------------------- // 177 // *** GUTS *** 178 // --------------------------------------------------------------- // 179 180 // implements TipManager & enjoys direct (non-polling) access to 181 // mouse events: 182 _TipManagerView* m_view; 183 184 185 private: 186 static TipManager* s_instance; 187 static BLocker s_instanceLock; 188 }; 189 190 __END_CORTEX_NAMESPACE 191 #endif /*__TipManager_H__*/ 192