# 3 Tabular Listbox and Display Items

## 3.1 tixTList -- The Tix Tabular Listbox Widget

TixTList is the Tabular Listbox Widget. It displays a list of items in a tabular format. For example the TixTList widget in figure 3-1 displays files in a directory in rows and columns.

> ### (Figure 3-1) Files Displayed in a TixTList Widget in a Tabular Format

> ### (Figure 3-2) Employee Names Displayed in a TixTList Widget

TixTList does all what the standard Tk listbox widget can do, i.e, it displays a list of items. However, TixTList is superior to the listbox widget is many respects. First, TixTList allows you to display the items in a two dimensional format. This way, you can display more items at a time. Usually, the user can locate the desired items much faster in a two dimensional list than the one dimensional list displayed by the Tk listbox widget.

In addition, while the Tk listbox widget can only display text items, the TixTList widget can display a multitude of types of items: text, images and widgets. Also, while you can use only one font and one color in a listbox widget, you can use many different fonts and colors in a TixTList widget. In figure 3-1 , we use graphical images inside a tixTList widget to represent file objects. In figure 3-2 , we display the names of all employees of a hypothetical company. Notice the use of a bold font to highlight all employees whose first name is Joe.

## 3.2 Display Items

Before we rush to discuss how to create the items inside a TixTList widget, let's first spend some time on a very important topic about the Tix library: the repationship between the display items and their host widgets.

We can better define the terms by taking a quick preview of the TixHList widget, which will be covered in details in the next chapter. Let's compare the items displayed on the two widgets in figure 3-3 . If we take a close look at the item that shows the `usr` directory in the TixTList widget on the left versus the TixHList widget on the right, we can see that this item appears exactly the same on both widgets.

If fact, all the items in these two widgets are of the same type: they all display an image next to a textual name. The only difference between these two widgets is how these items are arranged. The TixTList widget arranges the items in rows and columns, while the TixHList widget arranges the items in a hierachical format.

With this observation in mind, we can see a separation of tasks berween the widgets and the items they display. We call the TixHList and TixTList widgets in figure 3-3 host widgets: their task is to arrange the items according to their particular rules. However, they don't really care what these items display; they just treat the items as rectangle boxes. In contrast, these items, which are called display items in Tix terminology, controls the visual information they display, such as the images, text strings, colors, fonts, etc. However, they don't really care where on the host widget they will appear.

> ### (Figure 3-3) The Same Type of Items Displayed in a TixTList (left) and a TixHList(right)

### 3.2.1 Advantages of Display Items

It is easy to see the advantages of seperating the display items from their host widgets. First, the display items are easy to learn. Since they are the same across different types of widgets. Once you learn about a type of display items, you will know how to use them in all Tix widgets that support display items (currently these include TixHList, TixTList and the spreadsheet widget TixGrid, but the number is growing). In contrast, if you want to create a text item for the Tk widgets, you will find out that the listbox, text, canvas and entry widget each have a different method of creating and manipulating text items, and it is quite annoying to learn each of them individually.

Second, the hosts widgets that use display items are extensible. Because of the separation of task, the host widgets are not involved in the implementation details of the display items. Therefore, if you add a new type of display items, such as a `animation` type that displays live video, the host widgets will gladly take them in and display them. You don't need to modify the existing host widgets at all. In contrast, if you want to display graphical images in the existing Tk listbox widgets, you'd better set aside 100 hours to rewrite it completely!

Third, display items are good for writers of host widgets. Because now they just need to implement the arrangement policy of the host widgets. They don't need to worry about drawing at all because it is all handled by the display items. This is a significant saving in code because a widget that does not use display items has to spend 30% of its C code to do the drawing.

### 3.2.2 Display Items and Display Styles

The appearance of a display item is controlled by a set of attributes. For example, the `text` attribute controls the text string displayed on the item and the `font` attribute specifies what font should be used.

Usually, each of the attributes falls into one of two categroies: `` individual'' or `` collective''. For example, each of the items inside a TixTList widget may display a different text string; therefore we call the text string an individual attribute. However, in most cases, the items share the same color, font and spacing and we call these collective attributes.

One question concerns where we keep the collective attribute for the display items. Certainly, we can keep a `font` attribute for each item, but this is not really an efficient solution. In fact, if all the items have the same font, we would be keeping a duplicated copy of the same font for each of the items we create. Since a host widget may have many thousands of items, keeping thousands of dupilcated copys of the same font, or any other collective attributes, would be very wasteful.

> ### (Figure 3-4) Relationship Between Display Items and Display Styles

To advoid the unnecessary duplication of resources, Tix stores the collective attributes in special objects called display styles. The relationship between display items and their styles is depicted in figure 3-4 . Each item holds its own copy of the individual attributes, such as `text`. However, the collective attributes are stored in the style objects. Each item has a special `style` attribute that tells it which style it should use. In figure 3-4 , since items a and b are assigned the same style, therefore, they share the same font and color. Item c is assigned a different style, thus, it uses a different font than a and b.

## 3.3 Creating Display Items in the TixTList Widget

### 3.3.1 Creating Display Items

Now it's time to put our knowledge about host widgets, display items and display styles into practice. The following example code creates two items in a TixTList widget using the `insert` method:

{0.0cm}

>     tixTList .t
>     pack .t

>     .t insert end -itemtype text -text "First Item"  -underline 0
>     .t insert end -itemtype text -text "Second Item" -underline 0

>     set picture [image create bitmap -file picture.xbm]
>     .t insert end -itemtype image -image $picture

{0.2cm}

As we can see, the `insert` method of TixTList is very similar to the `insert` method of the standard Tk listbox widget: it inserts a new item into the TixTList widget. The first argument it takes is the location of the new item. For example `0` indicates the first location in the list, `1` indicates the second location, and so on. Also the special keyword `end` indicates the end of the list.

Then, we can use the `-itemtype` switch to specify the type of display item we want to create. There are currently four types of items to choose from: `text`, `image`, `imagetext` and `window`. In the above example, we create two items of the type `text` and one item of the type `image`. The subsequent arguments to the `insert` method set the configuration options of the individual attributes of the new item. The available options for these items are listed in figures ??? through ???.

### 3.3.2 Setting the Styles of the Display Items

Note that in the above example, if we want to control the foreground color of the text items, we cannot issue commands such as:

>     .t insert end -itemtype text -text "First Item" -foreground black

because `-foreground` is not an individual attribute of the text item. Instead, it is a collective attribute and must be accessed using a display style object. To do that we can use the command `tixItemStyle` to create display styles, as shown in the following example:

>     set style1 [tixDisplayStyle text -font 8x13]
>     set style2 [tixDisplayStyle text -font 8x13bold]

>     tixTList .t; pack .t

>     .t insert end -itemtype text -text "First Item"  -underline 0
>         -style $style1
>     .t insert end -itemtype text -text "Second Item" -underline 0
>         -style $style2
>     .t insert end -itemtype text -text "Third Item"  -underline 0
>         -style $style1

The first argument of `tixDisplayStyle` specify the type of style we want to create. Each type of display item needs its own type of display styles. Therefore, for example, we cannot create a style of type `text` and assign it to an item of type `image`. The subsequent arguments to `tixDisplayStyle` set the configuration options of the collective attributes defined by this style. A complete list of the configuration options of each type of the display style is in figures ??? through ???.

The `tixDisplayStyle` command returns the names of the newly created styles to us and we use the variables `style1` and `style2` to store these names. We can then assign the styles to the display items by using the names of the styles. As shown in figure 3-5 , by assing these two styles to the `-style` option of the display items, we assigned a medium-weight font to the first and third item and a bold font to the second item.

> ####
> Three `text` items in a TixTList

> ####
> The `text` items with fonts switched

> ### (Figure 3-5) Two Display Styles With Different Fonts

The name of the style returned by `tixDisplayStyle` is also the name of a command which we can use to control the style. For example, we can use the following commands to switch the fonts in the two styles we created in the above example:

>     $style1 configure -font 8x13bold
>     $style2 configure -font 8x13

After the execution of the above command, the font in the second item in the TixTList widget becomes medium-weight and the font in the first and third items becomes bold, as shown in figure 3-5 .

### 3.3.3 Configuring and Deleting the Items

You can configure the individual attributes of the items using the `entryconfigure` method. There is also the entrycget method for querying the attributes of the items. To `delete` the items, you can use the delete method. In the following example, we use these two methods to change the first and third items to display the text strings `One` and `Two` and change the third item to use the style `$style2`. Then we delete the second item using the `delete` command.

>     .t entryconfigure 0 -text One
>     .t entryconfigure 2 -text Two
>     .t delete 1

### 3.3.4 Choosing the Orientation and Number of Rows or Columns

There are three options that controls the layout of the items in the TixTList widget. The `-orientation` option can be set to either vertical or horizontal. When `-orientation` is set to `vertical`, the items are laid out vertically from top down and wrapped to the next column when the bottom is reached (see figure 3-6 ). The opposite layout policy is chosen if `-orientation` is set to `horizontal` (see figure 3-6 ).

When the `-orientation` option is set to `vertical`, normally the number of columns displayed depends on the number of items in the TixTList widget: the more items there are, the more columns will there be. However, we can use the `-columns` option to control the number of columns: the items will be wrapped in a way so that the number of columns produced will be exactly as dicated by the `-columns` option.

One use of the `-columns` option is to specify the same layout policy as that of the standard Tk listbox widget. We can do this by setting `-orientation` to vertical and `-columns` to `1`. This way we can get a replacement listbox widget that can display multiple fonts and colors and graphics!

The counterpart of the `-columns` option is the `-rows` option, which is used for the same purpose when the `-orientation` option is set to `horizontal`.

> ####
> Vertical Orientation

> ####
> Horizontal Orientation

> ### (Figure 3-6) The `-orientation` option of the TixSelect Widget

### 3.3.5 Event Handling

You can handle the events in a TList widget using the `-browsecmd` and `-command` options. The meanings of these two options are silimar to their meanings in other Tix widgets such as the ComboBox. Usually, the command specified by `-browsecmd` is called when the user clicks or drags the mouse over the items or presses the arrow keys. The command specified by `-command` is called when the user double-clicks or presses the Return key. These commands are called with one extra argument --- the index of the currently ``active'' item, which is usually the item under the mouse cursor.

### 3.3.6 Selection

The `-selectmode` option controls how many items the user can select at one time. In the `single` and `browse` mode, the user can select only one item at a time. In the `multiple` and `extended` mode, the user can select multiple items; the `extended` mode allows disjoint selections while the `multiple` mode does not.

Normally, the user selects the items using the mouse or the keyboard. You can find out which items the user has selected with the `info selection` method, which returns a list of the currently selected items. You can also set the selection using the `selection set` method. For example, the command `.tlist selection set 3` selects the item whose index is `3`. The command `.tlist selection set 2 10` selects all the items at index `2` through `10`. The method `selection clear` empties the selection.