cluster

Arguments: windows-button

Returns the value of the cluster property of windows-button. This property groups picture-button or radio-button controls into clusters (and also menu-items, see below). If a user clicks one button in the cluster, that button will be turned on and all other buttons in the cluster turned off.

Clusters are logical associations independent of physical placement on the dialog, but controls must be on the same dialog to be in the same cluster. All of the buttons in a single cluster will have an identical Lisp symbol (such as :cluster-1 or :send-form-button-panel) in their cluster property. The controls are also often arranged visually as a group, perhaps in a group-box.

The cluster property can also be used with menu-items. A set of contiguous menu-items can act like a set of radio-buttons, where calling (setf selected) to mark one of the menu-items as selected automatically deselects all of the other menu-items in the group. The group is set up by setting the cluster property of each menu-item in the group to the same arbitrary symbol, just as with radio-button widgets. In addition, a menu-item whose cluster property is non-nil will be marked by a small round dot when selected rather than with a check mark. It is a good idea to place a menu-separator between the menu-items in a cluster and any other menu-items on the same menu to clarify to the end user which items are in the group.

In the following example, each time (pop-up-menu my-menu) is called and a menu-item is selected, the menu's on-click function toggles whether that item is selected, which is apparent only when the menu is shown a further time. The "Independent" item is not in a cluster, while the other two items are in a cluster named :a. Selecting one of the items in the cluster will unselect the other item in the cluster if it was selected, but will not unselect the "Independent" item if it was selected.

(defparameter my-menu nil)

(setq my-menu
  (open-menu (list (make-instance 'menu-item
                     :title "Independent")
                   menu-separator
                   (make-instance 'menu-item
                     :title "One"
                     :cluster :a)
                   (make-instance 'menu-item
                     :title "The Other"
                     :cluster :a))
             'pop-up-menu
             (screen *system*)
             :on-click #'(lambda (menu menu-item stream)
                           (declare (ignore menu stream))
                           (setf (selected menu-item)
                             (not (selected menu-item)))
                           (title menu-item))))

(pop-up-menu my-menu) ;; call this multiple times

cluster is a property of the picture-button, radio-button, and menu-item classes.

GTK Note

GTK requires that one radio-button in a cluster always be on. If you set the value of the radio-button that's "on" to nil, then GTK will automatically turn on the first radio-button in the cluster.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.