December 1998

Horizontal scrollbars for list boxes

C++Builder programming
version markers: 1.0, 3.0

by Kent Reisdorph

It isn't uncommon to have text that's too long to fit the width of a list box. In such a case, you need a horizontal scrollbar so your users can see the rest of the text. The vertical scrollbar appears automatically in a list box when the number of items in a list box exceeds the height of the list box. However, you have to do some work to display a horizontal scrollbar.

Adding a horizontal scrollbar to a list box requires two steps: determining the width of the text (in pixels) of the widest item in the list box and sending a Windows message to the list box to add the horizontal scrollbar. In this article, we'll show you how to add a horizontal scrollbar to a list box. In the process, you'll learn about the TextWidth method of the TCanvas class and Windows' LB_SETHORIZONTALEXTENT message.

How wide is wide?

When you create a horizontal scrollbar, you tell Windows how far to scroll. Before you can do that, you need to determine the width of the widest item in the list box. VCL makes this part easy by providing the TextWidth method of the TCanvas class. This method will give you the width, in pixels, of a string of text; the value is calculated using the current font for the canvas. Here's an example:

int x = ListBox1->Canvas->
  TextWidth("Hello!");
Now, it's a simple matter of checking all of the items in the list box to see which is the longest. Depending on how you fill your list box, you could check the length as you add items or later, after all the items have been added. To check the length of the items after the items have been added, you can use code like this:

int length = 0;
for (int i=0;i<ListBox1->Items->Count;i++) 
  {
  String text = ListBox1->Items->
    Strings[i];
  int l = ListBox1->Canvas->
    TextWidth(text);
  if (l > length) length = l;
}
Now, you have the width, in pixels, of the longest item in the list box. Note that if your list box has a large number of items, this may not be the most efficient method of determining the longest item's length--it should be good enough for most cases, though.

Adding the scrollbar

Now that you have the length of the longest item in the list box, you can tell Windows to add a horizontal scrollbar. You do so with the Windows message LB_SETHORIZONTALEXTENT. It's as simple as this:

SendMessage(ListBox1->Handle,
  LB_SETHORIZONTALEXTENT, length, 0);
That's all there is to it! When this message is sent, Windows will add a horizontal scrollbar to the list box. As you can see, the scrollbar's horizontal extent is passed in the wParam of the LB_SETHORIZONTALEXTENT message. If the list box's width is already wider than the value of wParam, then the scrollbar won't be added. However, if the list box's width is reduced after sending the LB_SETHORIZONTALEXTENT message, then the scrollbar will appear.

To test this theory, start a new project in C++Builder and drop a ListBox component on the form. Double-click on the form's background to generate an event handler for the OnCreate event. Now, enter the code from Listing A in the event handler you just created. When you run the program, the list box will display a horizontal scrollbar, as shown in Figure A.

Figure A: This list box displays a horizontal scrollbar.
[ Figure A ]

Listing A: Adding a Horizontal Scrollbar

void __fastcall 
TForm1::FormCreate(TObject *Sender)
{
  // Put some items in the list box.
  ListBox1->Items->Add("This is a very long "
    "line that is too wide for the list box.");
  ListBox1->Items->Add("This is another very long line "
    "that is too wide for the listbox.");
  ListBox1->Items->Add("A shorter line.");

  // Find the length of the longest item.
  int length = 0;
  for (int i=0;i<ListBox1->Items->Count;i++) {
    String text = ListBox1->Items->Strings[i];
    int l = ListBox1->Canvas->TextWidth(text);
    if (l > length) length = l;
  }

  // Add a little for a good visual effect.
  length += 10;

  // Tell Windows to create the scrollbar.
  SendMessage(ListBox1->Handle,
    LB_SETHORIZONTALEXTENT, length, 0);
}