radio-button

Class

The class of a radio-button control.

Control

An instance of the radio-button class. This is a standard radio button control. The title field of the dialog item is used as the name of the radio button, and is displayed immediately to the right of the radio button itself. The value field of the dialog item is set to t if the radio button is on and is set to nil if it is off.

The behavior of radio buttons is to select one item in the cluster to the exclusion of all others. You are not required to place a group box around the set. Radio buttons are defined as being in a particular group via the :cluster property.

The displayed name of the button is the value of the title property. If the wrapping property is true, the title will wrap text to a second line if necessary. If wrapping is nil, text that does not fit will not be displayed.

Adding a radio-button control to your form

Click the radio-button tool on the Component toolbar. Move the mouse cursor to the part of the form where you want to place the control, and click again. The control will appear with colored resizing handles.

Resizing and moving the control

Controls can only be resized and moved on forms during the design stage; the size and location of everything is fixed on a running form.

Resize the control by clicking the mouse cursor and dragging one of the handles to the new size-point. Release the mouse key when you are satisfied with the new size. Note: resizing the radio-button control changes the size of the bounding-box, but not the size of the actual radio button inside.

Move the control by clicking anywhere on it except a resizing handle and dragging it to a new location on the form. Release the mouse key when you are ready to place the control.

Grouping radio-buttons together

The :cluster entry on the dialog item plist is used to group radio button dialog items into clusters. If the user clicks on one button in the cluster, that button will be turned on, and all other buttons in the cluster turned off. For example, consider the following:

(make-instance 'radio-button ... :cluster 'cluster1) 
(make-instance 'radio-button ... :cluster 'cluster1) 
(make-instance 'radio-button ... :cluster 'cluster2) 
(make-instance 'radio-button ... :cluster 'cluster2)

It creates two radio button clusters with two radio buttons each. :cluster entries are compared using eql.

Using click-off with radio-button controls

Radio-button supports the click-off property. This property can have the following values:

• nil: users can only deselect the button by clicking on another button in the same cluster (or by setting the value programmatically).
• t: Users will be able to deselect the button by clicking on it when currently selected.

Note: this option affects only what happens when clicking on a radio-button widget while it is in focus; the state of the radio-button can always be changed programmatically with value.

radio buttons and tabstop

Windows only allows you to tab to a radio-button when it is on. (Common Graphics supports tabbing to controls that have their tabstop property on.) The usual approach is to set the tab order of your dialog so that all of the radio-buttons that are in the same cluster will be adjacent in the tab order, and then make sure that the initial value of one of the radio-buttons in the cluster is non-nil. Then the user will be able to tab to the currently "on" radio-button in that cluster and then use the keyboard's arrow keys to move to the other radio-buttons in that cluster.

See About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

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.