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
72class BView;
73
74#include "cortex_defs.h"
75__BEGIN_CORTEX_NAMESPACE
76
77class TipWindow;
78
79class _TipManagerView;
80class _ViewEntry;
81class _WindowEntry;
82
83class TipManager :
84	protected	BWindow {
85	typedef		BWindow _inherited;
86
87public:
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
94public:										// *** 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
110public:										// *** dtor
111	virtual ~TipManager();
112
113public:										// *** singleton access
114	static TipManager* Instance();
115	static void QuitInstance();
116
117private:									// hidden constructor (use Instance() to access
118													// a single instance)
119	TipManager();
120
121public:										// *** 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
167public:										// *** 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
194public:										// *** BWindow
195
196public:										// *** BLooper
197
198	virtual bool QuitRequested();
199
200public:										// *** BHandler
201
202	virtual void MessageReceived(
203		BMessage*							message);
204
205private:
206
207	// --------------------------------------------------------------- //
208	//                           *** GUTS ***
209	// --------------------------------------------------------------- //
210
211	// implements TipManager & enjoys direct (non-polling) access to
212	// mouse events:
213	_TipManagerView*				m_view;
214
215
216private:
217	static TipManager*			s_instance;
218	static BLocker					s_instanceLock;
219};
220
221__END_CORTEX_NAMESPACE
222#endif /*__TipManager_H__*/
223