7.2.3 Collection gadgets

7.2.3.2 Button boxes

Groups of functionally related buttons are placed in button boxes. The superclass for button boxes is the <button-box> class. The two most common types of button box are <check-box> (groups of check buttons) and <radio-box> (groups of radio buttons). In addition, <push-box> (groups of push buttons) can be used.

Figure 7.5 A push box

Note: You should be aware of the distinction between the use of the term "box" in DUIM, and the use of the term "box" in some other development documentation (such as Microsoft's interface guidelines). In the context of DUIM, a box always refers to a group containing several gadgets (usually buttons). In other documentation, a box may just be a GUI element that looks like a box. For example, a check button may sometimes be called a check box.

A <radio-box> is a button box that contains one or more radio buttons, only one of which may be selected at any time.

define variable *my-radio-box* 
   := make(<radio-box>, items: #[1, 2, 3],
           value: 2);

Note the use of value: to choose the item initially selected when the box is created.

Figure 7.6 A radio box

For all boxes, the gadget-value is the selected button. In Figure 7.6 the gadget-value is 2.

gadget-value(*my-radio-box*);
=> 2

You can set the gadget-value to 3 and the selected button changes to 3:

gadget-value(*my-radio-box*) := 3;

As with all collection gadgets, use gadget-items to set or return the collection that defines the contents of a radio box.

gadget-items(*my-radio-box*); => #[1, 2, 3]

If you reset the gadget-items in a collection gadget, the gadget resizes accordingly:

gadget-items(*my-radio-box*) := range(from: 5, to: 20, by: 5);


Figure 7.7   The same radio box, resized to hold new items
 
A check box, on the other hand, can have any number of buttons selected. The following code creates a check box. After creating it, select the buttons labelled 4 and 6, as shown in Figure 7.8.
define variable *my-check-box* 
   := make(<check-box>, items: #(4, 5, 6));


Figure 7.8   A check box
 
You can return the current selection, or set the selection, using gadget-value.
gadget-value(*my-check-box*); => #[4, 6] 
gadget-value(*my-check-box*) := #[5, 6];


Remember that for a multiple-selection collection gadget, the gadget value is a sequence consisting of the values of all the selected items. The value of any given item is calculated using the value key.