7.2.4 Display controls

7.2.4.2 List controls

The <list-control> class is used to display a collection of items, each item consisting of an icon and a label. In Microsoft documentation, this control corresponds to the List View control in its "icon", "small icon", and "list" views. Like other collection gadgets, the contents of a list control is determined using the gadget-items slot.

Figure 7.13 A list control

Like tree controls, list controls support the icon-function: init-keyword. Note, however, that unlike tree controls, you can also use the list-control-icon-function generic function to retrieve and set the value of this slot after the control has been created.

A number of different views are available, allowing you to view the items in different ways. These views let you choose whether each item should be accompanied by a large or a small icon. You can specify the view for a list control when it is first created, using the view: init-keyword. After creation, the list-control-view slot can be used to read or set the view for the list control.

The list control in the example below contains a number of items, each of which consists of a two element vector.

The first element (a string) represents the label for each item in the list control.
The second element (beginning with reply-) represents the value of each item in the list control--in this case the callback function that is invoked when that item is double-clicked.

The example assumes that you have already defined these callback functions elsewhere.

make(<list-control>,
     items: vector(vector("Yes or No?", reply-yes-or-no),
                   vector("Black or White?", 
                          reply-black-or-white),
                   vector("Left or Right?", reply-left-or-right),
                   vector("Top or Bottom?", reply-top-or-bottom),
                   vector("North or South?", 
                          reply-north-or-south)),
     label-key: first,
     value-key: second,
     scroll-bars: #"none",
     activate-callback: method (sheet :: <sheet>)
                          gadget-value(sheet)(sheet-frame(sheet))
                        end);

In the example above, first is used to calculate the label that is used for each item in the list, and second specifies what the value for each item is. The activate callback examines this gadget value, so that the callback specified in the items: init-keyword can be used. Note that the scroll-bars: init-keyword can be used to specify which, if any, scroll bars are added to the control.

Like list boxes, and tree controls, list controls support the borders: and scroll-bars: init-keywords.