<title> Toggle </title>

<ul>
 <li> <a href="#toggle"> Toggle Widget </a>
 <li> <a href="#radio"> Radio Groups </a>
 <li> <a href="toggle.html#fMT"> MakeToggle </a>
 <li> <a href="toggle.html#fSTS"> SetToggleState </a>
 <li> <a href="toggle.html#fGTS"> GetToggleState </a>
</ul>
<hr>
<p>
<h2> <a name="toggle"> Toggle Widget </a> </h2>
<p>
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.
<p>
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).  
<hr>
<p>
<a name="fMT"> <b>
Widget MakeToggle(char *txt, int state, Widget w, ToggleCB func, void *data);
</b> </a>
<p>
This function makes a widget that will toggle between a highlighted
`on' state and an unhighlighted `off' state.
<p>
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).
<p>
If you plan to display a bitmap for the toggle button, you may specify
a NULL for the txt argument (and then call SetWidgetBitmap()).
<p>
The func argument is a standard callback function, that should be
declared as follows:
<p>
<pre>
     void func(Widget w, void *data)
     {
     }
</pre>
<p>
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.
<p>
Each time the widget changes state, your callback function is called.
That is, each time the user clicks the toggle, your function is
called. 
<hr>
<p>
<h3> <a name="radio"> Radio Groups </a> </h3>
<p>
  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.  
<p>
To build a radio group, you use the Widget argument of the
<a href="toggle.html#fMT">        MakeToggle() </a> 
function.  If you specify another valid toggle widget in
the call to 
<a href="toggle.html#fMT">        MakeToggle() </a>, 
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.
<p>
EXAMPLE:
<p>
<pre>
   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);
</pre>
<p>
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. 
<p>
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.
<p>
SEE ALSO: 
<a href="toggle.html#fSTS">       SetToggleState() </a>, 
<a href="toggle.html#fGTS">       GetToggleState() </a>, 
<a href="misc.html#fSWB">         SetWidgetBitmap() </a>,
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSBC2">        SetBorderColor() </a>, 
<a href="font.html#fSWF">         SetWidgetFont() </a> 
<hr>
<p>
<a name="fSTS"> <b>
void   SetToggleState(Widget w, int state);
</b> </a>
<p>
<a href="toggle.html#fSTS">       SetToggleState() </a> explicitly sets the state of a widget.
<p>
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.
<p>
SEE ALSO: 
<a href="toggle.html#fGTS">       GetToggleState() </a>, 
<a href="toggle.html#fMT">        MakeToggle() </a>
<hr>
<p>
<a name="fGTS"> <b>
int   GetToggleState(Widget w);
</b> </a>
<p>
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).
<p>
SEE ALSO: 
<a href="toggle.html#fMT">        MakeToggle() </a>, 
<a href="toggle.html#fSTS">       SetToggleState() </a>