Displays a balloon information window. Balloon windows are similar in appearance to the balloon captions used in comic books to display the dialog of the characters. For an edit control the balloon window looks like it is attached to the control.
The balloon is displayed for 10 seconds and then goes away. The programmer can also dismiss the balloon sooner using the HideBalloon method. Typically balloon windows are used to convey information to the user without having to put up a message box that the user then needs to dismiss manually.
This method is only available on Windows XP or later operating systems. If the method is used on an unsupported operating system, -4 is returned.
The arguments are:
A title for the balloon window. Titles are limited to 99 characters total in length.
The text of the balloon window. This text is limited to 1024 characters in length. The programmer can use line break characters to control the formatting of the text.
Used to specify which icon is displayed on the title line. The default is the informational icon. The following keywords can be used to specify another icon, or no icon. Only the first letter of the keyword is needed and case is insignificant:
The error icon is used.
The warning icon is used.
No icon is displayed.
The return value will be one of the following:
The value is the negated Operating System Error code. The absolute value of the return can be used to look up the error reason in the Windows documentation.
The operating system does not support this method. Windows XP or later is required.
The title or text arguments are too long for this method, or there is an (internal) problem converting one of the strings to Unicode.
There is an (internal) problem with the dialog or the dialog handle.
There is an (internal) problem with the resource ID or window handle of the edit control.
The method succeeded.
The method failed.
The following code snippet could come from a fictitious inventory program. An edit control is used to enter a product ID. If the user clicks on the edit control a ballon tip is shown displaying extended product information. (In a real application, the extended information might be based on what the user had entered in the edit control.)
Text is set in the edit control to give the user a 'cue' that she can click on the edit control for extra information. When the ballon tip is shown, it will automatically be dismissed after 10 seconds. This application connects a notification for the lost focus event. When the edit control loses focus, the ballon tip is hidden by the program.
... ::method defineDialog ... self~addText(10, 125, 150, 10, "Enter product ID:", "", 200) self~addEntryLine(IDC_ENTRYLINE, "cEntry", 10, 135, 150, 10, "AUTOSCROLLH") ... ::method initDialog expose editControl hwndEditControl editControl = self~getEditControl(IDC_ENTRYLINE) hwndEditControl = self~getItem(IDC_ENTRYLINE) self~connectEditNotify(IDC_ENTRYLINE, GOTFOCUS, "onFocus") self~connectEditNotify(IDC_ENTRYLINE, LOSTFOCUS, "onLostFocus") ret = editControl~setCue("Click here for extended product information") if ret <> 0 then ErrorDialog( "Set cue error return:" ret ) -- Capture the mouse activate messages: WM_MOUSEACTIVATE message == 0x0021 self~addUserMsg(onMouseActivate, "0x0021", "0xFFFFFFFF", 0, 0, 0, 0) ... ::method onMouseActivate expose editControl hwndEditControl if self~getFocus == hwndEditControl then do title = "Extended Product Information" text = "Product ID:" || "9"x || "4538-D32" || .endOfLine || - "In stock:" || "9"x || "789" || .endOfLine || - "Back ordered:" || "9"x || "No" || .endOfLine || - "EOL:" || "0909"x || "January 2008" || .endOfLine || - "Client:" || "0909"x || "AT&T" || .endOfLine || .endOfLine - "Notes: This product has served a limited number of customers" - "and should be considered archic. It will be replaced by a" - "superior product line." ret = editControl~showBalloon(title, text, "e"); if ret <> 0 then ErrorDialog("Show balloon error return:" ret) end ::method onLostFocus expose editControl -- When the edit control loses the focus, dismiss the alloon. ret = editControl~hideBalloon if ret <> 0 then ErrorDialog("Hide balloon error return:" ret)