ctl32_balloontip
ctl32_balloontip: overview | members | pictures
LINKS:
Properties, Events and Methods of the class
Overview
This class provides a BalloonTip control that can be used in VFP9. This class has two functions:
1. Emulate the "CAPS LOCK ON" warning of XP in a password entry textbox,
2. Display a BalloonTip pointing to any control or point in a form with any text you want.
The balloontip can be customized by adding an icon, a title, change its style from balloontip to tooltip, change its font, colors, position relative to the control, alignment, etc.
This class uses the Windows API functions to create a true Windows common controls ToolTip.
This class uses BINDEVENT with the new features only available in VFP9. It will not work in previous versions of VFP. If you are using a previous version of VFP, you should really upgrade to take advantage of the many new features, and to support VFP.
Quick Start
If you want a ctl32_balloontip on a form, drag the ctl32_balloontip control from the Project Manager window and drop it into the Form. You can only have ONE instance of the class in a form. You use the same control and change its Icon, Title and Text and other properties as required.
Sample Project
See the sample project included in the Sample folder to see examples of how to use the control and what can be done.
BindEvent
This class does Bindevents to the following windows and window messages:
ThisForm.hWnd, WM_KEYDOWN
ThisForm.hWnd, WM_LBUTTONDOWN
ThisForm.hWnd, WM_NOTIFY
If you hook to those same window/event pairs in some other part of your code, recall what the Help file says:
"When binding to Windows message (Win Msg) events, only one hWnd to Windows message pairing can exist."
Icon files used should be included in the project. There is no need to redistribute the icon files to end users. The icon files should contain one 16x16 256 color icon, that is used to display in the statusbar.
Bugs
20060926
There is a bug in the positioning code in tmrShow.ctl32_Show() that sometimes rises an error that thisform.activecontrol is not an object. I have fixed that for next version, and also added more features.
Known Problems
Change Log
2006xxxx
Changed the _ThemeStatus, _HostHWnd, _FormType functions in _util of ctl32_common. Eliminated all references to ThisForm, now the form is determined from the control that is passed as a parameter to this functions.
Changed the way _Util object is added to control, from newobject to addproperty, so it will not count as another control.
Added Chinese traditional and Chinese simplified to caps lock warning message laguages.
Changed the name of the ctl32_SetLangStrings to ctl32_SetLocaleStrings
Add a space to the end of the title strings of some languages to prevent compilation errors on DBCS Windows.
Moved routines for getting language ids to _util class
Added ctlVcxStructs and ctlVcxCommon, they specify the name/location of the ctl32_structs and ctl32_common classes.
20061010
ctlOS() method removed.
20061001
Fixed bug in tmrShow.ctl32_Show().
Added ctlPositionStyle 6: ballontip positions itself relative to the current position of the mouse pointer.
Added ctlOS() method
20060926
The updated structure of TOOLINFO does not seem to work in Vista RC1 5600 so I changed the _toolinfo class to not have the HBITMAP member, see http://windowssdk.msdn.microsoft.com/en-us/library/ms650460.aspx
WindowFromPoint in EvtHandler_WM_LBUTTONDOWN only works in XP and up, in 98 and 2K it always returns the HWND of the form, and not of the ballootip, even if you click on the balloontip.
GetWindowRect is used then in 98 and 2K, the problem is that it includes the area near the stem as part of the window rectangle, but is close enough.
Added Event ctlHide that is raised by clicks in balloontip, outside balloontip, in X close button and links in balloontips
Added bindevent to _Screen.Moved to hide when VFP Screen is moved
Changed ctlBalloon and ctlBorder to ctlStyle.
Added code to deal with textboxes with SelectOnEntry = .T. and when ctlPositionStyle is set to 3, align to cursor caret. It reverts to ctlPositionStyle = 2.
Under The Hood
The class creates a Windows Common Controls ToolTip, and adds only one Tool to it. It uses the TTM_TRACKACTIVATE to display the ToolTip, and TTM_TRACKPOSITION to position the ToolTip.
Starting from INIT(), first all the used API functions are declared in ctl32_RegisterFunctions. The Api functions are dlecared only if they have not been declared before.
Then some properties for internal use are added to the class. Next the HWnd of the window to use as a parent for the control is found. This is because top level forms, or forms with scrollbars have an inner window inside the form window.
Then the language strings are set and stored, and then the actual tooltip control is created.
To position the ToolTip, two methods are used: If you set ctlPositionStyle to 3, the position of the cursor caret in the form is retrieved, and based on that the tooltip is positioned next to it. You should use this position style with controls that have a cursor caret, for example a textbox.
New in version 20061001: A third positioning method is available, the current mouse cursor position.
If the caret is not visible, because some text is selected in the control, or the control does not have a caret, ctlPositionStyle reverts to 2, and the form active control is used for positioning.
The problem with using the caret or the current active control, is that you will put some code to show a tooltip in the GotFocus event of a control. But in the GotFocus event, the previous control still owns the caret or is the current active control.
To overcome this, when you set ctlVisible to TRUE, a timer is activated that waits for 200 milliseconds , so it lets the GotFocus event finish, not because of the time elapsed, but because the timer event code is out of the code flow of the GotFocus.
The ctl32_balloontip_show timer class has a ctl32_Show method that is responsible for positioning and displaying the balloontip.
When the balloontip is visible, it will be hidden automatically when the user clicks on the balloontip, clicks on the form, moves or resizes the form, or moves the VFP window. Also a keypress will hide the balloontip. This is all done by means of BINDEVENTS to some VFP events and window messages. Check ctl32_BindEvents() method of the class.
Also a timer is enabled when the control is made visible, that will hide thecontrol
An event is raised when the ballontip is hidden: ctlHide, with a parameter that tells you the reason code, so you can react different in response to the way the user dismissed the balloontip.
When you set ctlCapsLockStyle to TRUE, the balloontip emulates the "Caps Lock ON" warning ballontip that Windows XP display at the logon screen. You can use this in a password textbox.
TIP: set the PasswordChar of the texbox to "l" and the FontName to "WingDings" to emulate the look of XP password textboxes.
Also check the sample for a way to handle spacebar in a password textbox, to work around a VFP bug. (The space shows in the textbox instead of the PassWordChar).
The "Caps Lock ON" warning title and text is available in 28 languages, and it is set to the operating system user selected locale. You can override the language by setting a locale value in ctlLangID.
Check here for language IDs:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/intl/nls_61df.asp
See the ctl32_SetLangStrings method to see how its done. The language strings where extracted from comctl32.dll version 6. I have not been able to add non-latin charsets languages (lack of knowledge and time, maybe someone interested can help me there).
Starting in Windows XP SP2, you can specify a custom icon to display in the balloontip. this is done by storing the icon file name and path if needed in ctlIcon. The LOADPICTURE VFP function is used to load the icon. The icon file can be included in the project.
Starting with XP, a link can be displayed in the balloontip. To provide compatibility with older versions of Windows, the link is converted to plain text. You fill the ctlLinkLabel and ctlLinkUrl properties, and then you set ctlText to something like "Visit here: " + ctlLink
In Vista, you can choose to display large icons, setting ctlIconLarge to TRUE. The Vista API regarding tooltips controls is not yet firmly defined it seems.
Links
MSDN Windows Vista User Experience Guidelines: Balloons
MSDN Windows Vista User Experience Guidelines: Tooltips and Infotips
Microsoft Visual Studio 2003/.NET Framework 1.1 ToolTip Class
Microsoft Visual Studio 2005/.NET Framework 2.0 ToolTip Class
.NET Framework 3.0 ToolTip Class
Microsoft Visual Studio Codename Orcas ToolTip Class
Carlos Alloatti
