next up previous contents index
Next: Odds and Ends Up: Glish/Tk Previous: Button

Listbox and Scrollbar

The listbox widget presents a number of options to allow the user to select one or more of the options. In some respects, a listbox is like an encapsulated group of check buttons. Their function is essentially identical, but as we shall see, listboxes are more convenient when many options are involved. In this case, the scrollbar widget and the listbox can work together to allow the user to easily select from many options.


  First, lets look at the basic listbox operations. Like buttons, listboxes have a parent, and widget is returned by a constructor function call. Here is an example of how a listbox can be created:

    lbf := frame(f)
    lb := listbox(lbf)
    lb->insert("one two three four five six seven eight nine")
In this case, only the parent was specified to create the listbox. Table 10.6 lists all of the options for creation of listboxes. Creating a listbox, however, only generates an empty listbox with no options for the user to choose. An insert event must be sent to the listbox to place strings in the listbox. These strings represent the choices which the listbox presents the user.


Parameter Default Values Description
parent widget parent of the listbox
width 20 integer listbox width in character units
height 6 integer listbox height in lines
mode 'browse' 'browse' 'single' 'extended' 'multiple' listbox mode
font '' X font text font
relief 'sunken' 'flat' 'ridge' 'raised' 'sunken' 'groove' edge relief
borderwidth 2 dimension border width
foreground 'black' X color text color
background 'lightgrey' X color background color
exportselection F boolean export selection to X clipboard?
fill 'x' 'x' 'y' 'both' 'none' how to expand when resized
Table 10.6: Listbox Construction Parameters


A listbox has a mode which specifies how the user can select items. By default, the listbox is in 'browse' mode. In this mode, the user can only select one item from the listbox, but the selection can be dragged. The user can select the item, drag the mouse, and the selection will follow the mouse. If there are more items in the listbox then are displayed, the listbox will scroll to display the selected items as the user drags the mouse. In the example above, nine items were put into the listbox, but by default, only six are displayed. By dragging the selection, the user can access the items that are outside of the displayed range. A listbox in 'single' mode is like the 'browse' mode list box except that the user can no longer drag the selection.

A listbox in 'extended' mode allows the user to select multiple items from the listbox. Selections can be made by selecting individual items or by selecting and dragging over several items. The control key can be used to augment the selected items, and the shift key can be used to specify the beginning and end of a range of items to select. This mode is analogous to the 'browse' single selection mode, and 'multiple' mode is analogous to 'single'. In 'multiple' mode, the user can only add and remove items from the group of selected items by single selections of individual items.

It is important to be able to retrieve the selection the user has indicated. There are two ways of doing this. Each time a selection is made, a select event is generated. So continuing the example above:

    whenever lb->select do
        print "Items selected:",lb->get($value)
this whenever will cause the interpreter to print a message each time the selection in the listbox changes. The entire selection is returned as indexes in $value. The get request can be used to map the selection offsets to the strings they represent. The selection request can also be used to retrieve the current selection indexes:
    print lb->selection()
i.e. the $value in the above example. Table 10.7 lists all of the listbox events.

A final common listbox operation is deleting all of the elements in the listbox. This is easy to accomplish:



Event I/O Values Description
backgroundtex2html_wrap_inline15708 X color change background color
bind tex2html_wrap_inline15708<X> <G> associate Xevent <X> with Glish event <G>
borderwidthtex2html_wrap_inline15708 dimension change border width
clear tex2html_wrap_inline15708string clear indicated items, use 2 strings to clear range
delete tex2html_wrap_inline15708string delete indicated items, use 2 strings to delete range
exportselection tex2html_wrap_inline15708boolean export selection to X clipboard?
font tex2html_wrap_inline15708 X font change text font
foregroundtex2html_wrap_inline15708 X color change foreground color
get tex2html_wrap_inline15712integer request items, i.e. map indexes to items
height tex2html_wrap_inline15708integer listbox height in lines
insert tex2html_wrap_inline15708string insert items, optional 2nd param insert index
mode tex2html_wrap_inline15708'browse' 'single' 'multiple' 'extended' change listbox mode
relief tex2html_wrap_inline15708 'flat' 'ridge' 'raised' 'sunken' 'groove' change border relief
see tex2html_wrap_inline15708string scroll listbox so specified index is visible
select tex2html_wrap_inline15714string generated when user makes selection, can also be used to select items
selection tex2html_wrap_inline15712integer get indexes of the current selection
view tex2html_wrap_inline15708record scrollbar update event
width tex2html_wrap_inline15708integer listbox width in character units
xscroll tex2html_wrap_inline15710double information for horizontal scrollbar update
yscroll tex2html_wrap_inline15710double information for vertical scrollbar update
Table 10.7: Listbox Events





With a plain listbox, some items may be out of view as we saw above. By connecting scrollbars to the listbox, however, the user can scroll the box to look at the items, and the user gets feedback about how many items are in the box and which portion of the items are currently being displayed. Indeed, this is the type of feedback users expect. A scrollbar can be added to the example above as follows:

    lbf := frame(f,side='left')
    lb := listbox(lbf)
    sb := scrollbar(lbf)
    whenever sb->scroll do
    whenever lb->yscroll do
    lb->insert("one two three four five six seven eight nine")
In this case, we had to create a new frame widget, lbf, because we want the listbox and the scrollbar to be side by side. Figure 10.6 shows what this would look like.

Figure 10.6: Listbox

Two whenever statements are required so that the listbox and the scrollbar update each other. The scrollbar only generates one event, scroll. The value of this event must be relayed to the widget that the scrollbar is controlling, here a listbox. These scroll events are generated by the user moving the scrollbar thumb, i.e. the raised part in the middle of the scrollbar.

The listbox generates two scroll related events, xscroll and yscroll. These allow for both vertical and horizontal scrollbars to be attached to the listbox. The yscroll events are generated either by the user dragging the selection or in response to view events. The xscroll events are generated in response to view events.

This interaction is pretty interesting. The scrollbar generates the scroll event but does not update its appearance. Its apperance is updated by the resulting view event generated by the widget the scrollbar is controlling. Without these whenevers, no scrolling.  

next up previous contents index
Next: Odds and Ends Up: Glish/Tk Previous: Button

Thu Nov 13 16:44:05 EST 1997