OWLNext    7.0
Borland's Object Windows Library for the modern age
Loading...
Searching...
No Matches
tooltip.cpp
Go to the documentation of this file.
1//----------------------------------------------------------------------------
2// ObjectWindows
3// Copyright (c) 1995, 1996 by Borland International, All Rights Reserved
4//
5/// \file
6/// Implements the TTooltip class
7//----------------------------------------------------------------------------
8#include <owl/pch.h>
9
10#include <owl/window.h>
11#include <owl/gdiobjec.h>
12#include <owl/tooltip.h>
13#include <owl/commctrl.h>
14#include <owl/uimetric.h>
15
16namespace
17{
18
19 //
20 // This function solves a problem for Unicode builds without a manifest for Common Controls
21 // version 6. In this case, the classic non-themed version of Common Controls is used (5.x),
22 // and this version expects the old size of the TOOLINFO structure. Consequently, naively using
23 // the size of TOOLINFO to initialize TOOLINFO::cbSize will cause tool tips to not show.
24 //
25 auto GetToolInfoStructSize_() -> int
26 {
27 static const auto v = owl::GetCommCtrlVersion();
28 return static_cast<int>(v >= 0x60000 ? sizeof(TOOLINFO) : TTTOOLINFO_V1_SIZE);
29 }
30
31} // namespace
32
33namespace owl {
34
36DIAG_DECLARE_GROUP(OwlControl); // General Controls diagnostic group
37
38//
39// Size of container of tools
40//
41const int InitSize = 5; // Initial size of tool container
42const int InitDelta= 5; // Inc/Dec of tools container
43const int DefDelay = 500; // Default delay is 1/2 second
44const int HorzPad = 4; // Side pads around text of tooltip
45const int VertPad = 2; // Top/Down pads around text of tooltip
46const int DefTipTextCacheSize = 128; // Default cache size of tip text
47
48//
49// Timer id used by Tooltip window
50//
51const unsigned TOOLTIP_TIMERID = 0xABBA;
52
53//
54/// This is the default constructor of TToolInfo. It's used mainly when retrieving
55/// information about the current tool of the tooltip control or for initializing a
56/// brand new tool to be registered with the control. For example:
57/// \code
58/// TToolInfo ti;
59/// tooltip.GetCurrentTool(ti);
60/// \endcode
61//
63{
64 memset(this, 0, sizeof(TOOLINFO));
66 if (allocCache) {
67 CacheText = new tchar[DefTipTextCacheSize];
68 lpszText = (tchar*)CacheText;
69 }
70}
71
72//
73/// Constructor for a tool implemented as a rectangular area within a window's
74/// client area. The window argument receives the TTN_NEEDTEXT notification in case
75/// the txt argument defaults to LPSTR_TEXTCALLBACK.
76//
78 LPCTSTR txt /*=LPSTR_TEXTCALLBACK*/)
79{
80 memset(this, 0, sizeof(TOOLINFO));
82 SetToolInfo(window, toolId);
83 SetRect(rc);
84
85 // NOTE: When we're using the Common Control implementation we don't want
86 // to cache the text since we won't keep a copy of the TToolInfo
87 // structure around.
88 //
89 SetText(txt, false);
90}
91
92//
93/// String overload
94//
96{
97 memset(this, 0, sizeof(TOOLINFO));
99 SetToolInfo(window, toolId);
100 SetRect(rc);
101 SetText(txt);
102}
103
104//
105/// Constructor for a tool implemented as a rectangular area within a window's
106/// client area. The strRes and hInst arguments specify a string resource of the
107/// message to be used by the tooltip window.
108//
111{
112 memset(this, 0, sizeof(TOOLINFO));
114 SetToolInfo(window, toolId, rc);
116}
117
118//
119/// Constructor for a tool implemented as windows (child/controls). The parent
120/// argument receives the TTN_NEEDTEXT notification in case the txt argument
121/// defaults to LPSTR_TEXTCALLBACK.
122//
124 LPCTSTR txt /*=LPSTR_TEXTCALLBACK*/)
125{
126 memset(this, 0, sizeof(TOOLINFO));
128 SetToolInfo(toolWnd, parent);
129 SetText(txt, false);
130}
131
132//
133/// String overload
134//
136{
137 memset(this, 0, sizeof(TOOLINFO));
139 SetToolInfo(toolWnd, parent);
140 SetText(txt);
141}
142
143//
144/// Constructor for a tool implemented as a window (child/control). The strRes and
145/// hInst arguments specify a string resource to be used by the tooltip window.
146//
149{
150 memset(this, 0, sizeof(TOOLINFO));
152 SetToolInfo(toolWnd, parent);
154}
155
156//
157//
158//
160{
161 // Use assignment operator
162 //
163 *this = other;
164}
165
166//
167//
168//
171{
172 if (&other != this) {
173 *((TOOLINFO*)this) = *((TOOLINFO*)&other);
174 if (other.lpszText == other.GetCacheText())
175 SetText(other.GetCacheText());
176 /***
177 else
178 'other.lpszText' is assumed to be NULL, LPSTR_CALLBACK or pointing
179 to a buffer with a long lifetime. In all three cases a shallow copy of
180 the pointer is safe.
181 ***/
182 }
183 return *this;
184}
185
186//
187/// Sets the `hwnd` and `uId` members of the TOOLINFO base.
188/// TOOLINFO::hwnd is set to `window`, and TOOLINFO::uId is set to `toolId`.
189/// The flag TTF_IDISHWND is cleared in TOOLINFO::uFlags.
190//
191void
193{
194 PRECONDITION(::IsWindow(window));
195 hwnd = window;
197 uId = toolId;
198}
199
200//
201/// Sets the `hwnd`, `uId` and `rect` members of the TOOLINFO base.
202/// TOOLINFO::hwnd is set to `window`, TOOLINFO::uId is set to `toolId`, and TOOLINFO::rect is set to `rc`.
203/// The flag TTF_IDISHWND is cleared in TOOLINFO::uFlags.
204//
205void
207{
208 SetToolInfo(window, toolId);
209 SetRect(rc);
210}
211
212//
213/// Sets the `hwnd` and `uId` members of the TOOLINFO base.
214/// TOOLINFO::hwnd is set to `parent`, and TOOLINFO::uId is set to `toolHwnd`.
215/// The flag TTF_IDISHWND is set in TOOLINFO::uFlags.
216//
217void
219{
220 PRECONDITION(::IsWindow(toolHwnd));
221 PRECONDITION(::IsWindow(parent));
222 hwnd = parent;
224 uId = reinterpret_cast<UINT_PTR>(toolHwnd);
225}
226
227//
228/// Sets the text of this tool by providing a buffer that contains
229/// the string. The boolean 'copy' flag specifies whether the method
230/// should make a local copy of the string.
231//
232void
234{
235 if (text == LPSTR_TEXTCALLBACK || !text || !copy)
236 {
237 lpszText = (tchar*)text;
238 CacheText= 0;
239 }
240 else
241 {
242 CacheText = strnewdup(text);
243 lpszText = (tchar*)CacheText;
244 }
245}
246
247//
248/// Returns the actual HWND linked to a tool. For tools implemented as a rectangle
249/// within a client area, the window's handle is returned. For tools associated with
250/// a control, the handle of the control is returned.
251//
252HWND
254{
255 return (uFlags & TTF_IDISHWND) ? HWND(uId) : hwnd;
256}
257
258//
259/// Retrieves the actual RECT linked to a tool. For tools implemented as a rectangle
260/// within a client area, that rectangle is retrieved. For tools associated with a
261/// control, the latter's client area is retrieved.
262//
263void
265{
266 if (uFlags & TTF_IDISHWND) {
267 CHECK(::IsWindow(HWND(uId)));
268 ::GetClientRect(HWND(uId), &rc);
269 }
270 else {
271 rc = rect;
272 }
273}
274
275//
276/// This method determines whether a particular location of a window is relevant to
277/// this tool. For tools implemented as a rectangle within a window's client area,
278/// simply check that the pt argument is within that rectangle. For tools
279/// representing a child window, check that pt is within the client area of the
280/// child window.
281/// Returns true if succesful, or false if it fails.
282/// \note The pt argument must be relative to the window's client area.
283//
284bool
286{
287 HWND window = GetToolWindow();
288 if (window == win) {
289 TRect rc;
291 if (rc.Contains(pt))
292 return true;
293 }
294 return false;
295}
296
297//----------------------------------------------------------------------------
298// TTooltipText
299//
300
301//
302/// Sets text of tooltip to specified buffer.
303/// NOTE: The buffer pointed to by the specified parameter must be
304/// valid for as long as the TTooltipText points to it.
305/// For temporary buffers, use the 'CopyText' method instead.
306//
307void
312
313//
314/// Sets the text of the tooltip. The text is copied into the
315/// buffer owned by the 'TTooltipText'.
316/// \note The internal buffer can only handle 80 characters including the null-terminator.
317/// Longer strings will be truncated. Use SetText instead to avoid this.
318//
319void
321{
322 PRECONDITION(text != nullptr);
323 const size_t maxLen = COUNTOF(szText) - 1;
324 WARNX(OwlControl, _tcslen(text) > maxLen, 0, _T("Tip text is too large (truncated)."));
325 szText[0] = _T('\0');
327}
328
329//
330/// Sets the text of the tooltip. The 'resId' identifies a string resource
331/// found in the module pointed to by the 'hInstance' parameter.
332//
333void
339
340//----------------------------------------------------------------------------
341// TTooltipEnabler
342//
343
344//
345/// Constructs enabler object to be sent to a window so that the latter can provide
346/// the text of the specified tool.
347//
357
358//
359/// Sets the text of the tool specified by the TTooltipEnabler object.
360/// \note The text is copied to the internal buffer in the TTooltipText structure.
361/// This buffer can only handle 80 characters including the null-terminator.
362/// Longer strings will be truncated.
363//
364void
366{
367 TCommandEnabler::Enable(true);// only to set Handled
368 TipText.CopyText(text);
369}
370
371//
372/// SetCheck does nothing but serve as a place-holder function.
373//
374void
376{
377}
378
379//----------------------------------------------------------------------------
380// TTooltip
381//
382
383//
384/// Constructor for Ttooltip. Initializes its data fields using parameters passed
385/// and default values. By default, a Tooltip associated with the TTooltip will be
386/// active regardless of whether it's owner is active or inactive.
387//
389:
390 TControl(parent, 0, _T(""), 0, 0, 0, 0, module)
391{
393 Attr.Style = (WS_POPUP | WS_DISABLED);
394
395 if (alwaysTip)
396 Attr.Style |= TTS_ALWAYSTIP;
397
398
399 Attr.ExStyle |= WS_EX_WINDOWEDGE;
400
401 ///BGM removing this because it makes tooltips (and other popups, such
402 /// as dialogs) show up behind the frame when the window is first created.
403 /// see bug 43291.
404 ///
405 /// Most tooltips don't need to be topmost. However, when the window
406 /// they are servicing is reparented [for example, docking toolbars which
407 /// are docked/undocked], the tooltip's owner may no longer be the
408 /// window's owner. In that case, the tip may show up behind the owner
409 /// of the reparented window [unless, the tooltip has EX_TOPMOST].
410 ///
411
412 Attr.ExStyle |= WS_EX_TOPMOST; //??????????????
413}
414
416 : TControl(parent, 0, _T(""), 0, 0, 0, 0, m)
417{
420
421 // See comment about WS_EX_TOPMOST in the other constructor.
422 //
425 SetFlag(f);
426}
427
428//
429/// Constructor to alias a non-OWL TOOLTIP control. Specially useful when used with
430/// controls that automatically create a tooltip (eg TabControls with TCS_TOOLTIPS
431/// style).
432//
440
441//
442/// Destructor of TTooltip class.
443//
447
449{
450 TTooltip* t = new TTooltip(parent, alwaysTip, m);
451 if (parent->IsWindow())
452 {
453 bool r = t->Create();
454 CHECK(r); InUse(r);
455 }
456 else
458 return t;
459}
460
461//
462/// Returns the native class of the tooltip control or the class implementing OWL's
463/// version of tooltips.
464//
469
470bool
472{
473 TToolInfo t(::GetParent(ctrl), ctrl, tip);
475 return AddTool(t);
476}
477
478bool
480{
482 TModule& module = m ? *m : *GetModule();
483 TToolInfo t(::GetParent(ctrl), ctrl, tipResId, module.GetHandle());
484 t.EnableSubclassing(enableSubclassing);
485 return AddTool(t);
486}
487
488bool
495
496bool
498{
500 TModule& module = m ? *m : *GetModule();
501 TToolInfo t(toolWnd, tipArea, toolId, tipResId, module.GetHandle());
502 t.EnableSubclassing(enableSubclassing);
503 return AddTool(t);
504}
505
506} // OWL namespace
507/* ========================================================================== */
508
#define CHECK(condition)
Definition checks.h:239
#define WARNX(group, condition, level, message)
Definition checks.h:277
#define PRECONDITION(condition)
Definition checks.h:227
#define DIAG_DECLARE_GROUP(group)
Definition checks.h:404
Base class for an extensible interface for auto enabling/disabling of commands (menu items,...
Definition window.h:209
virtual void Enable(bool enable=true)
Enables or disables the command sender.
Definition window.cpp:301
uint Flags
TCommandStatus flags Is TCommandStatus::WasHandled if the command enabler has been handled.
Definition window.h:275
@ NonSender
Command does not generate WM_COMMAND messages.
Definition window.h:269
TControl unifies its derived control classes, such as TScrollBar, TControlGadget, and TButton.
Definition control.h:38
ObjectWindows dynamic-link libraries (DLLs) construct an instance of TModule, which acts as an object...
Definition module.h:75
TPoint is a support class, derived from tagPOINT.
Definition geometry.h:87
TRect is a mathematical class derived from tagRect.
Definition geometry.h:308
TToolInfo contains information about a particular tool (a tool is either a window or an application-d...
Definition tooltip.h:35
TToolInfo & operator=(const TToolInfo &)
Definition tooltip.cpp:170
HWND GetToolWindow() const
Returns the actual HWND linked to a tool.
Definition tooltip.cpp:253
void EnableSubclassing(bool enable=true)
Enable Subclassing have to be called for Dialog controls.
Definition tooltip.h:355
void SetRect(const TRect &rect)
Sets the bounding rectangle of the tool.
Definition tooltip.h:347
void SetText(int resId, HINSTANCE hinstance)
Sets the text of this tool by providing a string resource identifier and the handle of the instance c...
Definition tooltip.h:335
bool IsPointInTool(HWND win, const TPoint &pt) const
This method determines whether a particular location of a window is relevant to this tool.
Definition tooltip.cpp:285
void SetToolInfo(HWND window, uint toolId, const TRect &rc)
Sets the hwnd, uId and rect members of the TOOLINFO base.
Definition tooltip.cpp:206
TToolInfo(bool allocCache=false)
This is the default constructor of TToolInfo.
Definition tooltip.cpp:62
void GetToolRect(TRect &rect) const
Retrieves the actual RECT linked to a tool.
Definition tooltip.cpp:264
virtual void SetCheck(int check)
SetCheck does nothing but serve as a place-holder function.
Definition tooltip.cpp:375
TTooltipEnabler(TTooltipText &tt, HWND hReceiver)
Constructs enabler object to be sent to a window so that the latter can provide the text of the speci...
Definition tooltip.cpp:348
virtual void SetText(LPCTSTR text)
Sets the text of the tool specified by the TTooltipEnabler object.
Definition tooltip.cpp:365
TTooltip encapsulates a tooltip window - i.e.
Definition tooltip.h:175
static TTooltip * Make(TWindow *parent, bool alwaysTip=true, TModule *=nullptr)
Factory for TTooltip If the given parent has a valid handle (IsWindow), i.e.
Definition tooltip.cpp:448
bool AddTool(const TToolInfo &)
Registers a tool with the tooltip control.
Definition tooltip.h:406
~TTooltip()
Destructor of TTooltip class.
Definition tooltip.cpp:444
TTooltip(TWindow *parent, bool alwaysTip=true, TModule *module=nullptr)
Constructor for Ttooltip.
Definition tooltip.cpp:388
virtual auto GetWindowClassName() -> TWindowClassName
Returns the native class of the tooltip control or the class implementing OWL's version of tooltips.
Definition tooltip.cpp:465
TTooltipText identifies a tool for which text is to be displayed.
Definition commctrl.h:153
void SetText(LPCTSTR buff)
Sets text of tooltip to specified buffer.
Definition tooltip.cpp:308
void CopyText(LPCTSTR buff)
Sets the text of the tooltip.
Definition tooltip.cpp:320
Type-safe encapsulation of a Windows class name, a union between ATOM and LPCTSTR.
Definition module.h:47
TWindow, derived from TEventHandler and TStreamableBase, provides window-specific behavior and encaps...
Definition window.h:414
virtual bool Create()
Creates the window interface element to be associated with this ObjectWindows interface element.
Definition window.cpp:2399
TWindow * GetParent() const
Retrieves the OWL object of the parent window. If none exists, returns 0.
Definition window.h:2013
void SetFlag(uint mask)
Sets the specified TWindow wfXxxx constant flags (for example wfAlias, wfTransfer,...
Definition window.h:1783
TModule * GetModule() const
Returns a pointer to the module object.
Definition window.h:1841
bool IsWindow() const
Returns true if an HWND is being used.
Definition window.h:2040
uint32 SetStyle(uint32 style)
Sets the style bits of the underlying window or the 'Style' member of the attribute structure associa...
Definition window.cpp:3567
bool ModifyExStyle(uint32 offBits, uint32 onBits, uint swpFlags=0)
Modifies the style bits of the window.
Definition window.cpp:3599
Definition of classes for CommonControl encapsulation.
#define _tcslen
Definition cygwin.h:74
#define _T(x)
Definition cygwin.h:51
Definition of abstract GDI object class and derived classes.
TWindowFlag
Define bit masks for the internally used flag attributes of TWindow.
Definition window.h:58
@ wfAutoCreate
Create the HWND when our parent is created.
Definition window.h:60
char * strnewdup(const char *s, size_t minAllocSize=0)
Definition memory.cpp:25
Object Windows Library (OWLNext Core)
Definition animctrl.h:22
const unsigned TOOLTIP_TIMERID
Definition tooltip.cpp:51
const int InitDelta
Definition tabctrl.cpp:31
void InitializeCommonControls(uint controlFlags)
Wrapper for the Windows API function InitCommmonControlsEx.
Definition commctrl.cpp:19
const int InitSize
Definition tabctrl.cpp:30
const int DefTipTextCacheSize
Definition tooltip.cpp:46
void InUse(const T &arg)
Handy utility to avoid compiler warnings about unused parameters.
Definition defs.h:299
const int HorzPad
Definition tabctrl.cpp:32
auto GetCommCtrlVersion() -> DWORD
Returns the version number of the Common Control library (ComCtl32.dll).
Definition commctrl.cpp:26
const int DefDelay
Definition tooltip.cpp:43
OWL_DIAGINFO
Definition animctrl.cpp:14
std::string tstring
Definition defs.h:79
const int VertPad
Definition tabctrl.cpp:33
unsigned int uint
Definition number.h:25
#define CONST_CAST(targetType, object)
Definition defs.h:273
#define COUNTOF(s)
Array element count Important: Only use this with an argument of array type.
Definition defs.h:376
Definition of the TTooltip class and helper objects.
Definition of TUIMetric, a UI metrics provider class.
Base window class TWindow definition, including HWND encapsulation.
#define WS_EX_WINDOWEDGE
Definition wsysinc.h:30