How to Set Tab Stops in a Visual Basic List Box

• Professional Edition of Microsoft Visual Basic for Windows, versions 2.0 and 3.0

SUMMARY

Visual Basic version 3.0 has intrinsic multiple-column list boxes. You create the multiple columns by dividing the linear list of items into columns, based on the size of the list box. However, this can lead to overlapped columns if the length of the items in the list exceed the area allocated automatically by the list box.

NOTE: This is different than setting the Columns property of the list box, which merely determines whether a list box scrolls vertically or horizontally.

This article contains information on using the Windows API to create a multiple-column list box by setting the tab stops of the list box, thus creating the multiple-column effect. The related topics of dialog box units, dialog box base units, and providing a horizontal scroll bar on a list box are also covered.

MORE INFORMATION

For a complete example of this method used in a more generic manner, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q115712
   TITLE     : How to Fill a List Box from a Snapshot Generically

   SendMessage (hWnd%, LB_SETTABSTOPS, wParam%, lparam&)

   wParam%   is an integer that specifies the number of tab stops.

   lParam&   is a long pointer to the first member of an array
             of integers containing the tab-stop position in
             dialog box units.

Dialog Box Units and Dialog Box Base Units

Tab stops in a list box are specified in dialog box units, not pixels or character position. Essentially, a dialog box unit is used by Windows to size a control based on the average character width of the current system font. This average character width is called the dialog box base unit, and 1 dialog box base unit equals 4 dialog box units (1:4 ratio).

When setting tab stops in the list box, however, dialog box units are based on the average character width, in pixels, of the currently selected font for the list box. Thus, you have to calculate the average character width of the current font in the list box before you can set its tab stops. The average character width is based on the average width of the upper- and lower-case characters of the alphabet; therefore, it can be calculated in the sample code as follows:

     ' First set the form's font properties to match the list box.
     Me.FontName = list1.FontName
     Me.FontSize = list1.FontSize
     Me.FontBold = list1.FontBold
     Me.FontItalic = list1.FontItalic
     Me.FontStrikethru = list1.FontStrikethru
     Me.FontUnderline = list1.FontUnderline

     ' Make use of the form's TextWidth function to calculate the average
     ' character width of the alphabet. Visual Basic uses Twips and the
     ' SendMessage API needs pixels, so use "screen.TwipsPerPixelX" to
     ' convert.
     ' The following code is used to return the dialog box unit
     ' equivalent to one character:
     alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
     AvgCharWidth = (Me.TextWidth(alphabet) / 52) / screen.TwipsPerPixelX

     ' Calculate the dialog box unit for the list box.
     ListBoxDialogBoxUnit =  AvgCharWidth \ 4

   TabStop1 = (Me.TextWidth("Hello")/screen.TwipsPerPixelX \
   AvgCharWidth)*4

Providing a Horizontal Scroll Bar

When you use SendMessage to set tab stops, the Visual Basic list box does not automatically provide the horizontal scroll bar. To set the horizontal extent of the list box, use the API SendMessage with the LB_SETHORIZONTALEXTENT message. First, calculate the size, in pixels, of the scrolling region (based on the largest row entered into the list box). If you specify the horizontal extent to be larger than the width of the list box, a horizontal scroll bar is displayed.

The message LB_SETHORIZONTALEXTENT expects the extent to be specified in pixels. Because the tab-stop array holds dialog box units, which represent 4 times the number of average character spaces, to get that value converted back into pixels, perform the inverse operation.

  ' For simplicity, assume container scale mode of pixels.
  num_chars = Me.TextWidth("Total Character String") \ AvgCharWidth
  ListBoxDialogBoxUnits = num_chars * 4

  num_pixels = (ListBoxDialogBoxUnits \ 4) * AvgCharWidth

Step-by-Step Instructions for Creating the Program

1. Start a new project in Visual Basic. This creates Form1 by default.

2. On the form, create the following controls, and set the design-time properties shown:

      Control          Name        Property
      -------------------------------------------------------
      Command Button   Command1    Caption="Fill the ListBox"
      ListBox          List1       Fontname="MS Sans Serif" *
   
      * Any TrueType font will test the code.
   
   

3. Add the following code to the form's general declarations level (NOTE: All declare statements should be complete on one line):

       Option Explicit
       Const WM_USER = &H400
       '----------------------------------------------------------------------
       ' Win16 API constants and API declarations.
       '----------------------------------------------------------------------
       Const LB_SETTABSTOPS = WM_USER + 19
       Const LB_SETHORIZONTALEXTENT = WM_USER + 21
       Declare Function SendMessage Lib "user" (ByVal hWnd As Integer,
                   ByVal wMsg As Integer, ByVal wParam As Integer,
                   lParam As Any) As Long
       Declare Function SetParent Lib "user" (ByVal hWndChild As Integer,
                   ByVal hWndNew As Integer) As Integer
       Declare Sub ShellAbout Lib "shell.dll" (ByVal hWndOwner As Integer,
                   ByVal lpszAppName As String, ByVal lpszMoreInfo As String,
                   ByVal hIcon As Integer)
   
   

4. Add the following code to Command1_Click event:

       Sub Command1_Click ()
          Const numchars = 20             ' White space between columns
          Dim AvgCharWidth As Single
                                     ' Variables to store the font properties
          Dim hold_fontname As String, hold_fontsize As Integer
          Dim hold_fontbold As Integer, hold_fontitalic As Integer
          Dim hold_fontstrikethru As Integer, hold_fontunderline As Integer
   
          Dim retL As Long               ' Return value of SendMessage
          Dim WhiteSpace As Integer      ' Blank pixels between columns
          Dim i As Integer               ' Counter
          Dim t$                         ' Temp variable
          Dim alphabet As String   Holds upper- and lower-case alphabet chars.
   
          ReDim tabstops(1 To 3) As Integer   ' Tab-stop array for API call
          ReDim s(1 To 3) As String           ' String array to hold test data
   
          ' Save the form's original properties.
          hold_fontname = Me.FontName
          hold_fontsize = Me.FontSize
          hold_fontbold = Me.FontBold
          hold_fontitalic = Me.FontItalic
          hold_fontstrikethru = Me.FontStrikethru
          hold_fontunderline = Me.FontUnderline
   
          ' Set the list box's container's properties
          ' so that the TextWidth method of the form
          ' gives accurate results.
          Me.FontName = list1.FontName
          Me.FontSize = list1.FontSize
          Me.FontBold = list1.FontBold
          Me.FontItalic = list1.FontItalic
          Me.FontStrikethru = list1.FontStrikethru
          Me.FontUnderline = list1.FontUnderline
   
          ' Clear the list box and set up column headers.
          list1.Clear
          list1.AddItem "Column1" & Chr(9) & "Column2" & Chr(9) & "Column3"
   
          ' Add test data to the list box.
          s(1) = "This is a test of the"
          s(2) = "Emergency Broadcast System."
          s(3) = "This is only a test!"
   
          ' Add the test data with tabs into list box.
          For i = LBound(s) To UBound(s)
                t$ = t$ & s(i) & Chr(9)
          Next i
          list1.AddItem t$
   
          ' Get the average character width of the current list-box font
          ' now reflected in the container form's properties;
          ' this needs to be on one line of code.
          alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
          AvgCharWidth = (Me.TextWidth(alphabet) / screen.TwipsPerPixelX) / 52
   
          ' Set a variable for the white space you want between columns.
          WhiteSpace = AvgCharWidth * numchars
   
          ' Accumulate tab stops in list box's dialog box units;
          ' NOTE: these tabstop statements should each be on one line.
          tabstops(1) = ((Me.TextWidth(s(1)) / screen.TwipsPerPixelX +
   

       tabstops(2) = tabstops(1) + ((Me.TextWidth(s(2)) /

       ' This third value isn't necessary for the tab stops, but it is used
       ' to set the extent of the horizontal scrolling area.
       tabstops(3) = tabstops(2) + ((Me.TextWidth(s(3)) /

       ' Set the tab stops for the list box in dialog box units.
       retL = SendMessage(list1.hWnd, LB_SETTABSTOPS, 3, tabstops(1))

       ' Set the horizontal extent to the last tab stop.
       ' Because the tab-stop array holds dialog box units (which represent
       ' 4 times the number of characters), to get that value converted
       ' into pixels, perform the inverse operation.
       retL = SendMessage(list1.hWnd, LB_SETHORIZONTALEXTENT, (tabstops(3)

       ' Tell the list box to refresh its display.
       list1.Refresh

       ' Restore form's property values.
       Me.FontName = hold_fontname
       Me.FontSize = hold_fontsize
       Me.FontBold = hold_fontbold
       Me.FontItalic = hold_fontitalic
       Me.FontStrikethru = hold_fontstrikethru
       Me.FontUnderline = hold_fontunderline
End Sub