Visual Basic Text API Routines
SendMessage: Use Cue Banners to Prompt Users
     
Posted:   Monday March 10, 2003
Updated:   Monday December 26, 2011
     
Applies to:   VB5, VB6
Developed with:   VB4-32, Windows XP
OS restrictions:   Windows XP (Does not work in Vista)
Author:   VBnet - Randy Birch
     

Related:  

Pure VB: Cue Banners for the XP Impaired
SendMessage: Use Cue Banners to Prompt Users
SendMessage: Add Balloon Tips to a Combo Edit Box
SendMessage: Add Balloon Tips to a Text Box
     
 Prerequisites
Windows XP. This method does not appear to function on Vista.

Two users have reported problems in getting EM_SETCUEBANNER to function correctly, and each was able to resolve the solution, but differently. For one, the method performed correctly once OS support for East Asian users was removed. For the other, OS support for complex scripts was uninstalled.


If you've used Office XP applications under Windows XP, you'll have seen combos in the toolbars that  contain greyed-out text prompting to "Type a question for help". Here's the VB code to apply that feature to a VB text box, rich text box or to the edit portion of a Style 0 or 1 combo box ... in a one line call to SendMessage. Where form real estate may be at a premium, this is a novel and useful way to indicate the data expected in a control without taking space for labels.

SendMessage with EM_SETCUEBANNER is called passing a Unicode string containing the 'cue banner' to the control. Under XP, the control knows how to handle this text, displaying it greyed out. The text is not selectable - in fact, on gaining focus the text box or combo removes the cue banner, readying the control for data entry. If the user leaves the control without entering any text the banner is automatically restored to remind input is still required. Even if the user enters text, navigates away, then returns to delete the text the cue banner text is automatically redisplayed. Thus, once you call the method for a control the cue banner persists for the life of the control.

When the control contains the cue banner, testing for Len(Text1.Text) returns 0 as it should when the control is void of user entry, thus validating or determining entry can be performed using normal VB methods. If the control contains any text - including text set at load (or perhaps because the default 'Text1' was left by mistake), the call treats that as valid control data and does not replace it with the cue text. However, should that text be deleted the assigned cue banner will be displayed. In combination with the Windows XP-enabled balloon tips for combos or text boxes, your VB interface will behave and appear as a true XP application.

Like the balloon tips for combos or text/rich text controls, cue banners are only available under Windows XP or later. In order to develop, see and test the cue banners the IDE must also have a manifest as outline at Manifests: Make the VB IDE use Windows XP Styles . Furthermore, in order for the cue banner to appear in a distributed application, the end user must be running XP and the application must be distributed with a manifest file to enable the XP styles in the VB application (also detailed on the same page).

 BAS Module Code
None.

 Form Code
Add two text boxes (Text1, Text), a combo (Combo1) and command button (Command1) to the form, along with the following code. There is no code in the command button event - it is provided only to gain focus in order to display the cue text in the three controls.

Option Explicit
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright 1996-2011 VBnet/Randy Birch, All Rights Reserved.
' Some pages may also contain other copyrights by the author.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Distribution: You can freely use this code in your own
'               applications, but you may not reproduce 
'               or publish this code on any web site,
'               online service, or distribute as source 
'               on any media without express permission.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Private Const ECM_FIRST As Long = &H1500
Private Const EM_SETCUEBANNER As Long = (ECM_FIRST + 1)

Private Type EDITBALLOONTIP
   cbStruct As Long
   pszTitle As String
   pszText As String
   ttiIcon As Long
End Type

Private Type RECT
   Left As Long
   Top As Long
   Right As Long
   Bottom As Long
End Type

Private Type COMBOBOXINFO
   cbSize As Long
   rcItem As RECT
   rcButton As RECT
   stateButton  As Long
   hwndCombo  As Long
   hwndEdit  As Long
   hwndList As Long
End Type

Private Declare Function GetComboBoxInfo Lib "user32" _
  (ByVal hwndCombo As Long, _
   CBInfo As COMBOBOXINFO) As Long
   
Private Declare Function SendMessage Lib "user32" _
   Alias "SendMessageA" _
  (ByVal hwnd As Long, _
   ByVal wMsg As Long, _
   ByVal wParam As Long, _
   lParam As Any) As Long
   
Private Declare Function InitCommonControls Lib "comctl32" () As Long


Private Sub Form_Initialize()

  'InitCommonControls must be called
  'before the interface is created,
  'so calling in the Load event is
  'often too late. Placing the call in
  'either the application's Sub Main
  'entry point, or in the Initialize
  'allows the XP styles to be applied.
   InitCommonControls

End Sub


Private Sub Form_Load()

   Call InitCommonControls()

   Dim sCue As String
   Dim CBI As COMBOBOXINFO
   
  'get the combo's edit hwnd
   CBI.cbSize = Len(CBI)
   Call GetComboBoxInfo(Combo1.hwnd, CBI)
   
  'for demo - ensures all three
  'controls show the cue banners
   Command1.Caption = "Not used"
   Command1.TabIndex = 0
   
  'have to clear the controls
   Text1.Text = vbNullString
   Text2.Text = vbNullString
   Combo1.Text = vbNullString
   
   sCue = StrConv("Enter the regional sales office", vbUnicode)
   Call SendMessage(Text1.hwnd, EM_SETCUEBANNER, 0&, ByVal sCue)
   
   sCue = StrConv("Enter the sales group", vbUnicode)
   Call SendMessage(Text2.hwnd, EM_SETCUEBANNER, 0&, ByVal sCue)
   
   sCue = StrConv("Sales group leader", vbUnicode)
   Call SendMessage(CBI.hwndEdit, EM_SETCUEBANNER, 0&, ByVal sCue)
   
End Sub
 Comments
This is a sample manifest file to provide XP styles in VB applications:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<assembly 
   xmlns="urn:schemas-microsoft-com:asm.v1" 
   manifestVersion="1.0">
   <assemblyIdentity 
      type="win32" 
      processorArchitecture="*" 
      version="6.0.0.0"
      name="test"
   /> 
   <description>Enter your Description Here</description>
   <dependency> 
      <dependentAssembly> 
         <assemblyIdentity 
            type="win32"
            name="Microsoft.Windows.Common-Controls" 
            version="6.0.0.0" 
            language="*"
            processorArchitecture="*" 
            publicKeyToken="6595b64144ccf1df"
         />
      </dependentAssembly> 
   </dependency> 
</assembly>

 
 

PayPal Link
Make payments with PayPal - it's fast, free and secure!

 
 
 
 

Copyright 1996-2011 VBnet and Randy Birch. All Rights Reserved.
Terms of Use  |  Your Privacy

 

Hit Counter