1 /* 2 * Copyright (c) 1999-2000, Eric Moon. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions, and the following disclaimer. 11 * 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions, and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * 3. The name of the author may not be used to endorse or promote products 17 * derived from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR 20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 26 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 27 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 31 32 // TipManager.h 33 // 34 // PURPOSE 35 // Maintains a set of pop-up tips bound to rectangular 36 // regions of any number of views. Also provides for 37 // simple 'manual' operation: call showTip() with text and 38 // a screen rectangle, and the tip will be displayed after 39 // the mouse has idled in that rectangle. 40 // 41 // HISTORY 42 // e.moon 27oct99: Substantial bugfixes (removal of entire 43 // view hierarchies' tips now works). 44 // 45 // e.moon 19oct99: TipManager now derives from BWindow. 46 // 47 // e.moon 17oct99: reworked the tip window: now exposed via the 48 // TipWindow & TipView classes. 49 // 50 // e.moon 27sep99: optimized TipManager::run() (no longer pounds 51 // the CPU when idling in a view) 52 // 53 // e.moon 13may99: moved TipManager's privates into 54 // TipManagerImpl.h 55 // 56 // e.moon 12may99: expanded to TipManager 57 // e.moon 11may99: begun as TipTriggerThread 58 59 #ifndef __TipManager_H__ 60 #define __TipManager_H__ 61 62 #include <SupportDefs.h> 63 #include <Font.h> 64 #include <Point.h> 65 #include <Rect.h> 66 #include <GraphicsDefs.h> 67 #include <String.h> 68 69 #include <Locker.h> 70 #include <Window.h> 71 72 class BView; 73 74 #include "cortex_defs.h" 75 __BEGIN_CORTEX_NAMESPACE 76 77 class TipWindow; 78 79 class _TipManagerView; 80 class _ViewEntry; 81 class _WindowEntry; 82 83 class TipManager : 84 protected BWindow { 85 typedef BWindow _inherited; 86 87 public: 88 static const BPoint s_useDefaultOffset; 89 static const BPoint s_defaultOffset; 90 91 static const bigtime_t s_defIdleTime; 92 static const bigtime_t s_sleepPeriod; 93 94 public: // *** types & constants 95 enum flag_t { 96 NONE 97 }; 98 99 enum offset_mode_t { 100 // offset determines left/top point of tip window 101 LEFT_OFFSET_FROM_RECT, // from the right bound 102 LEFT_OFFSET_FROM_POINTER, 103 104 // offset determines right/top point of tip window 105 // (x offset is inverted; y isn't) 106 RIGHT_OFFSET_FROM_RECT, // from the left bound 107 RIGHT_OFFSET_FROM_POINTER 108 }; 109 110 public: // *** dtor 111 virtual ~TipManager(); 112 113 public: // *** singleton access 114 static TipManager* Instance(); 115 static void QuitInstance(); 116 117 private: // hidden constructor (use Instance() to access 118 // a single instance) 119 TipManager(); 120 121 public: // *** add and remove tips 122 123 // add or modify a tip: 124 125 // child allows tips to be added to child views of the main 126 // target view. rect is in view coordinates; only one tip 127 // may exist for a particular view with a given top-left 128 // corner -- you don't want tip rectangles to overlap in general, 129 // but TipManager won't stop you from trying. Yet. 130 // [13may99] 131 132 status_t setTip( 133 const BRect& rect, 134 const char* text, 135 BView* view, 136 offset_mode_t offsetMode =LEFT_OFFSET_FROM_POINTER, 137 BPoint offset =s_useDefaultOffset, 138 uint32 flags =NONE); 139 140 // This version of setTip() maps a tip to the entire frame 141 // rectangle of a child view. This call will fail if tips 142 // are already being managed for that view; once a 143 // full-view tip has been added future attempts call any 144 // version of setTip() for that view will also fail. 145 // [13may99] 146 147 status_t setTip( 148 const char* text, 149 BView* view, 150 offset_mode_t offsetMode =LEFT_OFFSET_FROM_POINTER, 151 BPoint offset =s_useDefaultOffset, 152 uint32 flags =NONE); 153 154 // Remove all tips matching the given rectangle and/or child 155 // view. 156 157 status_t removeTip( 158 const BRect& rect, 159 BView* view); 160 161 status_t removeAll( 162 BView* view); 163 164 status_t removeAll( 165 BWindow* window); 166 167 public: // *** manual tip arming 168 169 // [e.moon 19oct99] 170 // Call when the mouse has entered a particular region of 171 // the screen for which you want a tip to be displayed. 172 // The tip will be displayed if the mouse stops moving 173 // for idleTime microseconds within the rectangle screenRect. 174 175 status_t showTip( 176 const char* text, 177 BRect screenRect, 178 offset_mode_t offsetMode =LEFT_OFFSET_FROM_POINTER, 179 BPoint offset =s_useDefaultOffset, 180 uint32 flags =NONE); 181 182 // [e.moon 22oct99] 183 // Call to immediately hide a visible tip. You need to know 184 // the screen rectangle for which the tip was shown (which is easy 185 // if was displayed due to a showTip() call -- pass the same 186 // screenRect argument.) 187 // If the tip was found & hidden, returns B_OK; if there's 188 // no visible tip or it was triggered by a different rectangle, 189 // returns B_BAD_VALUE. 190 191 status_t hideTip( 192 BRect screenRect); 193 194 public: // *** BWindow 195 196 public: // *** BLooper 197 198 virtual bool QuitRequested(); 199 200 public: // *** BHandler 201 202 virtual void MessageReceived( 203 BMessage* message); 204 205 private: 206 207 // --------------------------------------------------------------- // 208 // *** GUTS *** 209 // --------------------------------------------------------------- // 210 211 // implements TipManager & enjoys direct (non-polling) access to 212 // mouse events: 213 _TipManagerView* m_view; 214 215 216 private: 217 static TipManager* s_instance; 218 static BLocker s_instanceLock; 219 }; 220 221 __END_CORTEX_NAMESPACE 222 #endif /*__TipManager_H__*/ 223