═══ 1. Introduction ═══ Introduction The Hint Bubble control is brought to you by Secant Technologies, makers of ObjectPM, ObjectPM Control Pack, and other fine OS/2 software. It is a "teaser" in hopes of generating interest in us and our software packages. We also hope to generate an interest in OS/2 custom -controls, as there is a lack of them in the marketplace. It is provided with a "C" interface only. You can go ahead and wrap it in OWL, ICLUI, ObjectPM, or whatever, or possibly look for the Hint Bubble and wrappers in the next release of the ObjectPM Control Pack. Give us some feedback at info@secant.com about the Hint Bubble or other custom controls you would like to see. Come and see us at http://www.secant.com ═══ 2. Hint Bubble Custom Control ═══ ═══ 2.1. Hint Bubble Description ═══ Hint Bubble Custom Control The Hint Bubble control can be attached to any other control to display some helpful information about the control. It is often used in toolbars where the array of icons can become confusing. It normally pops up after some specified time when the user keeps the mouse pointer over the control. As can be seen below, the Hint Bubble consists of a bubble area in which text is displayed and a triangular piece leading from the attached control. The positioning of the "point" of the triangular piece can be specified absolutely or by mouse pointer position. Also, the "side" on which the bubble appears can be specified through style flags. You do not need to specify a size for the control, as it automatically sizes based upon the text it is to display. You can insert line breaks in the hint text by embedding "\n" in the text. The text will then be displayed as multiple lines in the bubble area. What to put in the .RC file When designing a dialog, specify "HINTBUBBLE" for the class name of any Hint Bubble control you would like to use as in: CONTROL "Hint Text", 101, 8, 23, 153, 36, "HINTBUBBLE", WS_VISIBLE What it looks like ═══ 2.2. Hint Bubble C Interface ═══ Hint Bubble C Interface This section describes the messages, styles, notification codes and structures needed for the C language interface to the Hint Bubble Custom Control. ═══ 2.2.1. Hint Bubble Class Name ═══ Hint Bubble Class Name The class name of the Hint Bubble control to use in the WinCreateWindow() OS/2 API call is "HINTBUBBLE" This is also the class name you must use when putting a Hint Bubble in a dialog box as in: CONTROL "Hint Text", 101, 8, 23, 153, 36, "HINTBUBBLE" ═══ 2.2.2. Hint Bubble Styles ═══ Hint Bubble Styles The following style bits may be logically OR'ed together along with the normal WS_* style bits: Style Description HBS_BOTTOM Bubble appears below the attached control HBS_TOP Bubble appears above the attached control HBS_LEFT Bubble appears to the left of the attached control HBS_RIGHT Bubble appears to the right of the attached control HBS_CENTERTEXT Text is centered based upon the widest line HBS_USEMOUSEPOS Bubble appears at the mouse position instead of the position specified in the control data. HBS_HIDEONMOVE After the hint bubble is shown, it is hidden when the user moves the mouse. It is redisplayed again after the delay time is the user keeps the mouse over the attached control. HBS_SHOWONCE Only meaningful when used with HBS_HIDEONMOVE. Prevents the bubble from being shown again after the user moves the mouse, even if the user keeps the mouse over the control. ═══ 2.2.3. Hint Bubble Structures ═══ Hint Bubble Structures Control Data The control data can be used to set and retrieve the attached control, bubble "point" position and delay in milliseconds before the bubble is displayed. typedef struct { long cb; // size of the struct HWND linkedCtl; // window handle of the linked control long linkX; // x position of bubble "point" long linkY; // y position of bubble "point" long delay; // delay in milliseconds before display long hidedelay; // delay in milliseconds before hiding the bubble // after displaying it. 0=as long as it is // over the attached control } HBUBBLECTLDATA; typedef HBUBBLECTLDATA *PHBUBBLECTLDATA; ═══ 2.2.4. Hint Bubble Presentation Parameters ═══ Hint Bubble Presentation Parameters The Hint Bubble uses the following presentation parameters to set its colors (please note that the equivalent RGB PP_* can also be used - EG PP_FOREGROUNDCOLOR vs PP_FOREGROUNDCOLORINDEX): PP_* Description (Default) PP_FOREGROUNDCOLORINDEX Hint text (RGB 255,255,255 - white) PP_BACKGROUNDCOLORINDEX Background (RGB 0,130,130 - blue-green) PP_FONTNAMESIZE Font ("System Propertional.10") ═══ 2.2.5. WM_SETWINDOWPARAMS ═══ WM_SETWINDOWPARAMS All operations on the control are done through its control data. For instance to link to a control, you would do the following: WNDPARAMS wp; HBUBBLECTLDATA data; data.cb = sizeof (HBUBBLECTLDATA); // set the size data.linkedCtl = hwnd; // handle of attached control data.linkX = 10; // set "point" to position data.linkY = 10; // (10,10) data.delay = 1000; // wait 1 second before showing data.hidedelay = 3000; // hide again after 3 seconds wp.fsStatus = WPM_CTLDATA; wp.pCtlData = (void *)&data; // and set it WinSendMsg(hintHwnd, WM_SETWINDOWPARAMS, (MPARAM)&wp, NULL); Arguments mp1 Pointer to a WNDPARAMS structure containing the hint bubble control data. mp2 Not used, should be 0. Return Value TRUE if successful, FALSE if not. ═══ 2.2.6. void HintBubbleRegister(HAB hab); ═══ void HintBubbleRegister(HAB hab); Registers the Hint Bubble control with OS/2 and must be called before any instances of a Hint Bubble control can be created (with WinCreateWindow() or on a dialog). Arguments hab Handle to the anchor block from the WinInitialize() OS/2 API call.