A toggle widget is similar to a button widget except that it maintains state. That is, when a user clicks a toggle widget, it remains highlighted until it is clicked again. This is similar to an on/off switch.
Toggle widgets can also be used to create a group of "radio buttons". A radio button group is a set of toggle widgets in which at most one of them can be selected at any one time (it is possible for none of them to be selected).
Widget MakeToggle(char *txt, int state, Widget w, ToggleCB func, void *data);
This function makes a widget that will toggle between a highlighted `on' state and an unhighlighted `off' state.
The first argument is the text that will be displayed inside the widget. The `state' argument is a boolean value of the initial state of the toggle button (TRUE == on/highlighted, FALSE == off). The next argument, a Widget, is NULL if this widget is a simple toggle button by itself and not part of a radio group (described below).
If you plan to display a bitmap for the toggle button, you may specify a NULL for the txt argument (and then call SetWidgetBitmap()).
The func argument is a standard callback function, that should be declared as follows:
void func(Widget w, void *data)
{
}
The last argument, data, is an arbitrary pointer you would like passed to your callback function (it becomes the second argument to the callback function.
Each time the widget changes state, your callback function is called. That is, each time the user clicks the toggle, your function is called.
It is possible to connect toggle widgets together to form a group of widgets that are mutually exclusive. That is to say, with a radio group, you can have a set of widgets in which at most one of them will be highlighted at any given time. Therefore, if you had 3 widgets, A, B, and C, only one could be highlighted at any one time, and clicking on another unhighlights the current one and highlights the toggle clicked on. This is useful for selecting one choice of several (such as a size, which is either small, medium or large, but not two at the same time). Keep in mind that it is possible for none of them to be selected.
To build a radio group, you use the Widget argument of the MakeToggle() function. If you specify another valid toggle widget in the call to MakeToggle() , the new widget becomes connected to the widget you specified. All the widgets you connect together form a radio group. Any single widget can _only_ be in one radio group.
EXAMPLE:
Widget widg1, widg2, widg3;
widg1 = MakeToggleWidget("Thing 1", TRUE, NULL, func1, NULL);
widg2 = MakeToggleWidget("Thing 2", FALSE, widg1, func2, NULL);
widg3 = MakeToggleWidget("Thing 3", FALSE, widg1, func3, NULL);
Notice how widg2 and widg3 specify widg1 as their Widget argument. This connects all three into a radio group in which only one can be set at a time. We initialize widg1 to be initially set and the others off. If you specify more than one widget as `on', the results are undefined.
The callback functions are called whenever a widget is highlighted or unhighlighted. The callbacks to the widget being unhighlighted happen before the callbacks to widgets being highlighted.
SEE ALSO: SetToggleState() , GetToggleState() , SetWidgetBitmap() , SetFgColor() , SetBgColor() , SetBorderColor() , SetWidgetFont()
void SetToggleState(Widget w, int state);
SetToggleState() explicitly sets the state of a widget.
The `state' argument is either TRUE (set the toggle to its highlighted state), or FALSE (unhighlight the widget). The callback routine for the widget is only called if there is a change in state.
SEE ALSO: GetToggleState() , MakeToggle()
This function returns the current state of the toggle widget w. The return values are either TRUE (the widget is selected) or FALSE (the widget is not highlighted).
SEE ALSO: MakeToggle() , SetToggleState()