src/apps/cortex/TipManager/TipManager.h

   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__*/