The TList Widget

The TList widget is very similar to a Listbox, because it displays a list of things. The Listbox is limited to displaying lists of text strings. The TList widget can display any item type, and each item can be a different color and/or font. One of the most common questions asked about a Listbox is whether it can display different color items. The answer to that is no, but a TList can. The TList can also handle displaying multiple columns of items.

When you create a TList, you specify options just as you would when creating any other widget. These options are completely standard and behave as expected: -background, -borderwidth, -class, -command, -cursor, -foreground, -font, -height, -highlightcolor, -highlightthickness, -padx, -pady, -relief, -selectbackground, -selectborderwidth, -selectforeground, -selectmode, -state, -xscrollcommand, -yscrollcommand, and -width.

The following options are specific to a TList widget:

  • -browsecmd => callback
  • The callback is called when the user browses through the entries in the TList. Use -command if you want to invoke a callback when a user selects an item in the TList.
  • -itemtype => 'text' | 'imagetext' | 'image' | 'window'
  • The default item type to use for the TList. This allows you to call insert without specifying an item type, as it will use the one specified here.
  • -orient => 'vertical' | 'horizontal'
  • A TList will create columns if it can't fit everything in the first column. This option specifies if the items are displayed from top to bottom, go to the next column ('vertical'), or if items are displayed right to left, move down ('horizontal').
  • -sizecmd => callback
  • This callback will be invoked whenever the TList size changes.

To see how the TList looks different from a Listbox, take a look at Figure 18-4. Figure 18-4

Figure 18-4. A TList showing the 'vertical' orientation

Scrollbars don't work quite as expected with a TList because of the automatic column feature. When using a vertical orientation on a TList, a horizontal scrollbar will work just fine, but a vertical one will never do anything because the TList wraps to the next column based on the current height of the window, regardless of whether there is a vertical scrollbar.

TList Indexes and Methods

Index specification works exactly the same way in a TList as it does in a Listbox. Please refer to "The Listbox Widget" for information on index specification.

All of the methods listed as part of a Listbox work with the TList as well. The insert method for a TList is slightly different from a Listbox widget. It accepts the following additional option/value pairs related to item styles and creating display items:

  • -itemtype => 'text' | 'imagetext' | 'image' | 'window'
  • Specifies the type of item to create. If not used, the default value for the TList will be used.
  • -data => $scalar
  • You can store some data with the item by using this option. The information in $scalar is stored and can be retrieved using entrycget later.
  • -state => 'disabled' | 'normal'
  • Each individual item in the TList can be disabled if you so choose.
  • -style => $style
  • Causes the item to use the style's settings instead of the defaults for the TList.