Toggle widget

The Toggle widget is an area, often rectangular, containing a text label or bitmap image. This widget maintains a Boolean state (e.g. True/False or On/Off) and changes state whenever it is selected. When the pointer is on the button, the button may become highlighted by drawing a rectangle around its perimeter. This highlighting indicates that the button is ready for selection. When pointer button 1 is pressed and released, the Toggle widget indicates that it has changed state by reversing its foreground and background colors, and its notify action is invoked, calling all functions on its callback list. If the pointer is moved out of the widget before the button is released, the widget reverts to its normal foreground and background colors, and releasing the button has no effect. This behavior allows the user to cancel an action.

Toggle buttons may also be part of a radio group. A radio group is a list of at least two Toggle buttons in which no more than one Toggle may be set at any time. A radio group is identified by the widget ID of any one of its members. The convenience routine XawToggleGetCurrent will return information about the Toggle button in the radio group.

Toggle widget state is preserved across changes in sensitivity.

New Resources

Name	Class	Type	Notes	Default Value
radioData	RadioData	Pointer		Name of widget
radioGroup	Widget	Widget		No radio group
state	State	Boolean		Off

radioData	Specifies the data that will be returned by XawToggleGetCurrent when this is the currently set widget in the radio group. This value is also used to identify the Toggle that will be set by a call to XawToggleSetCurrent. The value NULL will be returned by XawToggleGetCurrent if no widget in a radio group is currently set. Programmers must not specify NULL (or Zero) as radioData.
radioGroup	Specifies another Toggle widget that is in the radio group to which this Toggle widget should be added. A radio group is a group of at least two Toggle widgets, only one of which may be set at a time. If this value is NULL (the default) then the Toggle will not be part of any radio group and can change state without affecting any other Toggle widgets. If the widget specified in this resource is not already in a radio group then a new radio group will be created containing these two Toggle widgets. No Toggle widget can be in multiple radio groups. The behavior of a radio group of one toggle is undefined. A converter is registered which will convert widget names to widgets without caching.
state	Specifies whether the Toggle widget is set (True) or unset (False).

Toggle Actions

• Switching the button between the foreground and background colors with set and unset and toggle
• Processing application callbacks with notify
• Switching the internal border between highlighted and unhighlighted states with highlight and unhighlight

The following are the default translation bindings used by the Toggle widget:

        <Btn1Down>,:toggle() notify()

	<EnterWindow>:	highlight(Always)
	<LeaveWindow>:	unhighlight()
	<Btn1Down>,:	toggle() notify()

When a bitmap of depth greater that one (1) is specified the set(), unset(), and reset() actions have no effect, since there are no foreground and background colors used in a multi-plane pixmap.

Radio Groups

There are typically two types of radio groups desired by applications. The default translations for the Toggle widget implement a "zero or one of many" radio group. This means that there may be no more than one button active, but there need not be any buttons active.

The other type of radio group is "one of many" and has the more strict policy that there will always be exactly one radio button active. Toggle widgets can be used to provide this interface with a slight modification to the translation table of each Toggle in the group.

	<EnterWindow>:	highlight(Always)
	<LeaveWindow>:	unhighlight()
	<Btn1Down>,:	set() notify()

Convenience routines

Changing the Toggle's Radio Group.

void XawToggleChangeRadioGroup(w, radio_group)
	Widget w, radio_group;

If a Toggle is already set in the new radio group, and the Toggle to be added is also set then the previously set Toggle in the radio group is unset and its callback procedures are invoked. Finding the Currently selected Toggle in a radio group of Toggles

To find the currently selected Toggle in a radio group of Toggle widgets use XawToggleGetCurrent.

XtPointer XawToggleGetCurrent(radio_group);
	Widget radio_group;

The value returned by this function is the radioData of the Toggle in this radio group that is currently set. The default value for radioData is the name of that Toggle widget. If no Toggle is set in the radio group specified then NULL is returned. Changing the Toggle that is set in a radio group.

To change the Toggle that is currently set in a radio group use XawToggleSetCurrent.

void XawToggleSetCurrent(radio_group, radio_data);
	Widget radio_group;
	XtPointer radio_data;

XawToggleSetCurrent locates the Toggle widget to be set by matching radio_data against the radioData for each Toggle in the radio group. If none match, XawToggleSetCurrent returns without making any changes. If more than one Toggle matches, XawToggleSetCurrent will choose a Toggle to set arbitrarily. If this causes any Toggle widgets to change state, all routines in their callback lists will be invoked. The callback routines for a Toggle that is to be unset will be called before the one that is to be set. Unsetting all Toggles in a radio group.

To unset all Toggle widgets in a radio group use XawToggleUnsetCurrent.

void XawToggleUnsetCurrent(radio_group);
	Widget radio_group;

If this causes a Toggle widget to change state, all routines on its callback list will be invoked.