specs/Toggle.xml

   1 <sect1 id="Toggle_Widget">
   2 <title>Toggle Widget</title>
   3 <literallayout class="monospaced">
   4 Application Header file     &lt;Xaw/Toggle.h&gt;
   5 Class Header file     &lt;Xaw/ToggleP.h&gt;
   6 Class          toggleWidgetClass
   7 Class Name     Toggle
   8 Superclass      Command
   9 </literallayout>
  10
  11 <para>
  12 The Toggle widget is an area, often rectangular,
  13 that displays a graphic.  The graphic may be a text
  14 string containing multiple lines of characters in an 8
  15 bit or 16 bit character set (to be displayed with a
  16 <emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with
  17 a <emphasis remap='I'>fontset</emphasis>).  The graphic may also be a bitmap or
  18 pixmap.
  19 </para>
  20
  21 <para>
  22 This widget maintains a Boolean state (e.g.
  23 True/False or On/Off) and changes state whenever it is selected.  When
  24 the pointer is on the Toggle widget, the Toggle widget may become highlighted by
  25 drawing a rectangle around its perimeter.  This highlighting indicates
  26 that the Toggle widget is ready for selection.  When pointer button 1 is
  27 pressed and released, the Toggle widget indicates that it has changed
  28 state by reversing its foreground and background colors, and its
  29 <function>notify</function> action is invoked, calling all functions on its callback
  30 list.  If the pointer is moved off of the widget before the pointer button is
  31 released, the Toggle widget reverts to its previous foreground and background
  32 colors, and releasing the pointer button has no effect.  This behavior allows
  33 the user to cancel the operation.
  34 </para>
  35
  36 <para>
  37 Toggle widgets may also be part of a ``radio group.''  A radio group is a
  38 list of at least two Toggle widgets in which no more than one Toggle may
  39 be set at
  40 any time.  A radio group is identified by the widget ID of any one of
  41 its members.  The convenience routine <function>XawToggleGetCurrent</function> will
  42 return information about the Toggle widget in the radio group.
  43 </para>
  44
  45 <para>
  46 Toggle widget state is preserved across changes in sensitivity.
  47 </para>
  48
  49 <sect2 id="toggle_resources">
  50 <title>Resources</title>
  51 <para>
  52 When creating a Toggle widget instance, the following resources are
  53 retrieved from the argument list or from the resource database:
  54 </para>
  55
  56 <informaltable>
  57   <tgroup cols='5' align='center'>
  58   <colspec colname='c1'/>
  59   <colspec colname='c2'/>
  60   <colspec colname='c3'/>
  61   <colspec colname='c4'/>
  62   <colspec colname='c5'/>
  63   <thead>
  64     <row>
  65       <entry>Name</entry>
  66       <entry>Class</entry>
  67       <entry>Type</entry>
  68       <entry>Notes</entry>
  69       <entry>Default Value</entry>
  70     </row>
  71   </thead>
  72   <tbody>
  73     <row>
  74       <entry>accelerators</entry>
  75       <entry>Accelerators</entry>
  76       <entry>AcceleratorTable</entry>
  77       <entry></entry>
  78       <entry>NULL</entry>
  79     </row>
  80     <row>
  81       <entry>ancestorSensitive</entry>
  82       <entry>AncestorSensitive</entry>
  83       <entry>Boolean</entry>
  84       <entry>D</entry>
  85       <entry>True</entry>
  86     </row>
  87     <row>
  88       <entry>background</entry>
  89       <entry>Background</entry>
  90       <entry>Pixel</entry>
  91       <entry></entry>
  92       <entry>XtDefaultBackground</entry>
  93     </row>
  94     <row>
  95       <entry>backgroundPixmap</entry>
  96       <entry>Pixmap</entry>
  97       <entry>Pixmap</entry>
  98       <entry></entry>
  99       <entry>XtUnspecifiedPixmap</entry>
 100     </row>
 101     <row>
 102       <entry>bitmap</entry>
 103       <entry>Bitmap</entry>
 104       <entry>Pixmap</entry>
 105       <entry></entry>
 106       <entry>None</entry>
 107     </row>
 108     <row>
 109       <entry>borderColor</entry>
 110       <entry>BorderColor</entry>
 111       <entry>Pixel</entry>
 112       <entry></entry>
 113       <entry>XtDefaultForeground</entry>
 114     </row>
 115     <row>
 116       <entry>borderPixmap</entry>
 117       <entry>Pixmap</entry>
 118       <entry>Pixmap</entry>
 119       <entry></entry>
 120       <entry>XtUnspecifiedPixmap</entry>
 121     </row>
 122     <row>
 123       <entry>borderWidth</entry>
 124       <entry>BorderWidth</entry>
 125       <entry>Dimension</entry>
 126       <entry></entry>
 127       <entry>1</entry>
 128     </row>
 129     <row>
 130       <entry>callback</entry>
 131       <entry>Callback</entry>
 132       <entry>XtCallbackList</entry>
 133       <entry></entry>
 134       <entry>NULL</entry>
 135     </row>
 136     <row>
 137       <entry>colormap</entry>
 138       <entry>Colormap</entry>
 139       <entry>Colormap</entry>
 140       <entry></entry>
 141       <entry>Parent's Colormap</entry>
 142     </row>
 143     <row>
 144       <entry>cornerRoundPercent</entry>
 145       <entry>CornerRoundPercent</entry>
 146       <entry>Dimension</entry>
 147       <entry></entry>
 148       <entry>25</entry>
 149     </row>
 150     <row>
 151       <entry>cursor</entry>
 152       <entry>Cursor</entry>
 153       <entry>Cursor</entry>
 154       <entry></entry>
 155       <entry>None</entry>
 156     </row>
 157     <row>
 158       <entry>cursorName</entry>
 159       <entry>Cursor</entry>
 160       <entry>String</entry>
 161       <entry></entry>
 162       <entry>NULL</entry>
 163     </row>
 164     <row>
 165       <entry>depth</entry>
 166       <entry>Depth</entry>
 167       <entry>int</entry>
 168       <entry>C</entry>
 169       <entry>Parent's Depth</entry>
 170     </row>
 171     <row>
 172       <entry>destroyCallback</entry>
 173       <entry>Callback</entry>
 174       <entry>XtCallbackList</entry>
 175       <entry></entry>
 176       <entry>NULL</entry>
 177     </row>
 178     <row>
 179       <entry>encoding</entry>
 180       <entry>Encoding</entry>
 181       <entry>UnsignedChar</entry>
 182       <entry></entry>
 183       <entry>XawTextEncoding8bit</entry>
 184     </row>
 185     <row>
 186       <entry>font</entry>
 187       <entry>Font</entry>
 188       <entry>XFontStruct</entry>
 189       <entry></entry>
 190       <entry>XtDefaultFont</entry>
 191     </row>
 192     <row>
 193       <entry>fontSet</entry>
 194       <entry>FontSet</entry>
 195       <entry>XFontSet</entry>
 196       <entry></entry>
 197       <entry>XtDefaultFontSet</entry>
 198     </row>
 199     <row>
 200       <entry>foreground</entry>
 201       <entry>Foreground</entry>
 202       <entry>Pixel</entry>
 203       <entry></entry>
 204       <entry>XtDefaultForeground</entry>
 205     </row>
 206     <row>
 207       <entry>height</entry>
 208       <entry>Height</entry>
 209       <entry>Dimension</entry>
 210       <entry>A</entry>
 211       <entry>graphic height + 2 * <function>internalHeight</function></entry>
 212     </row>
 213     <row>
 214       <entry>highlightThickness</entry>
 215       <entry>Thickness</entry>
 216       <entry>Dimension</entry>
 217       <entry>A</entry>
 218       <entry>2 (0 if Shaped)</entry>
 219     </row>
 220     <row>
 221       <entry>insensitiveBorder</entry>
 222       <entry>Insensitive</entry>
 223       <entry>Pixmap</entry>
 224       <entry></entry>
 225       <entry>GreyPixmap</entry>
 226     </row>
 227     <row>
 228       <entry>internalHeight</entry>
 229       <entry>Height</entry>
 230       <entry>Dimension</entry>
 231       <entry></entry>
 232       <entry>2</entry>
 233     </row>
 234     <row>
 235       <entry>internalWidth</entry>
 236       <entry>Width</entry>
 237       <entry>Dimension</entry>
 238       <entry></entry>
 239       <entry>4</entry>
 240     </row>
 241     <row>
 242       <entry>international</entry>
 243       <entry>International</entry>
 244       <entry>Boolean</entry>
 245       <entry>C</entry>
 246       <entry>False</entry>
 247     </row>
 248     <row>
 249       <entry>justify</entry>
 250       <entry>Justify</entry>
 251       <entry>Justify</entry>
 252       <entry></entry>
 253       <entry>XtJustifyCenter (center)</entry>
 254     </row>
 255     <row>
 256       <entry>label</entry>
 257       <entry>Label</entry>
 258       <entry>String</entry>
 259       <entry></entry>
 260       <entry>name of widget</entry>
 261     </row>
 262     <row>
 263       <entry>leftBitmap</entry>
 264       <entry>LeftBitmap</entry>
 265       <entry>Bitmap</entry>
 266       <entry></entry>
 267       <entry>None</entry>
 268     </row>
 269     <row>
 270       <entry>mappedWhenManaged</entry>
 271       <entry>MappedWhenManaged</entry>
 272       <entry>Boolean</entry>
 273       <entry></entry>
 274       <entry>True</entry>
 275     </row>
 276     <row>
 277       <entry>pointerColor</entry>
 278       <entry>Foreground</entry>
 279       <entry>Pixel</entry>
 280       <entry></entry>
 281       <entry>XtDefaultForeground</entry>
 282     </row>
 283     <row>
 284       <entry>pointerColorBackground</entry>
 285       <entry>Background</entry>
 286       <entry>Pixel</entry>
 287       <entry></entry>
 288       <entry>XtDefaultBackground</entry>
 289     </row>
 290     <row>
 291       <entry>radioData</entry>
 292       <entry>RadioData</entry>
 293       <entry>Pointer</entry>
 294       <entry></entry>
 295       <entry>Name of widget</entry>
 296     </row>
 297     <row>
 298       <entry>radioGroup</entry>
 299       <entry>Widget</entry>
 300       <entry>Widget</entry>
 301       <entry></entry>
 302       <entry>No radio group</entry>
 303     </row>
 304     <row>
 305       <entry>resize</entry>
 306       <entry>Resize</entry>
 307       <entry>Boolean</entry>
 308       <entry></entry>
 309       <entry>True</entry>
 310     </row>
 311     <row>
 312       <entry>screen</entry>
 313       <entry>Screen</entry>
 314       <entry>Screen</entry>
 315       <entry>R</entry>
 316       <entry>Parent's Screen</entry>
 317     </row>
 318     <row>
 319       <entry>sensitive</entry>
 320       <entry>Sensitive</entry>
 321       <entry>Boolean</entry>
 322       <entry></entry>
 323       <entry>True</entry>
 324     </row>
 325     <row>
 326       <entry>shapeStype</entry>
 327       <entry>ShapeStyle</entry>
 328       <entry>ShapeStyle</entry>
 329       <entry></entry>
 330       <entry>Rectangle</entry>
 331     </row>
 332     <row>
 333       <entry>state</entry>
 334       <entry>State</entry>
 335       <entry>Boolean</entry>
 336       <entry></entry>
 337       <entry>Off</entry>
 338     </row>
 339     <row>
 340       <entry>translations</entry>
 341       <entry>Translations</entry>
 342       <entry>TranslationTable</entry>
 343       <entry></entry>
 344       <entry>See below</entry>
 345     </row>
 346     <row>
 347       <entry>width</entry>
 348       <entry>Width</entry>
 349       <entry>Dimension</entry>
 350       <entry>A</entry>
 351       <entry>graphic width + 2 * <function>internalWidth</function></entry>
 352     </row>
 353     <row>
 354       <entry>x</entry>
 355       <entry>Position</entry>
 356       <entry>Position</entry>
 357       <entry></entry>
 358       <entry>0</entry>
 359     </row>
 360     <row>
 361       <entry>y</entry>
 362       <entry>Position</entry>
 363       <entry>Position</entry>
 364       <entry></entry>
 365       <entry>0</entry>
 366     </row>
 367   </tbody>
 368   </tgroup>
 369 </informaltable>
 370
 371 <variablelist>
 372   <varlistentry>
 373     <term>
 374       <function>radioData</function>
 375     </term>
 376     <listitem>
 377       <para>
 378 Specifies the data that will be returned by <function>XawToggleGetCurrent</function>
 379 when this is the currently <emphasis remap='I'>set</emphasis> widget in the radio group.  This
 380 value is also used to identify the Toggle that will be set by a call to
 381 <function>XawToggleSetCurrent</function>.  The value NULL will be returned by
 382 <function>XawToggleGetCurrent</function> if no widget in a radio group is currently
 383 set.  Programmers must not specify NULL (or Zero) as <function>radioData</function>.
 384       </para>
 385     </listitem>
 386   </varlistentry>
 387   <varlistentry>
 388     <term>
 389       <function>radioGroup</function>
 390     </term>
 391     <listitem>
 392       <para>
 393 Specifies another Toggle widget that is in the radio group to which this
 394 Toggle widget should be added.  A radio group is a group of at least two Toggle
 395 widgets, only one of which may be <emphasis remap='I'>set</emphasis> at a time.  If this value is
 396 NULL (the default) then the Toggle will not be part of any radio group
 397 and can change state without affecting any other Toggle widgets.  If the
 398 widget specified in this resource is not already in a radio group then a
 399 new radio group will be created containing these two Toggle widgets.  No
 400 Toggle widget can be in multiple radio groups.  The behavior of a radio
 401 group of one toggle is undefined.  A converter is registered which will
 402 convert widget names to widgets without caching.
 403       </para>
 404     </listitem>
 405   </varlistentry>
 406   <varlistentry>
 407     <term>
 408       <function>state</function>
 409     </term>
 410     <listitem>
 411       <para>
 412 Specifies whether the Toggle widget is set (<function>True</function>) or unset
 413 (<function>False</function>).
 414     </para>
 415   </listitem>
 416   </varlistentry>
 417 </variablelist>
 418 </sect2>
 419
 420 <sect2 id="Toggle_Actions">
 421 <title>Toggle Actions</title>
 422 <para>
 423 The Toggle widget supports the following actions:
 424 </para>
 425
 426 <itemizedlist>
 427   <listitem>
 428     <para>
 429 Switching the Toggle widget between the foreground and background
 430 colors with <function>set</function> and <function>unset</function> and <function>toggle</function>
 431     </para>
 432   </listitem>
 433   <listitem>
 434     <para>
 435 Processing application callbacks with <function>notify</function>
 436     </para>
 437   </listitem>
 438   <listitem>
 439     <para>
 440 Switching the internal border between highlighted
 441 and unhighlighted states with <function>highlight</function> and <function>unhighlight</function>
 442     </para>
 443   </listitem>
 444 </itemizedlist>
 445
 446 <para>
 447 The following are the default translation bindings used by the
 448 Toggle widget:
 449 </para>
 450
 451 <literallayout class="monospaced">
 452      &lt;EnterWindow&gt;:     highlight(Always)
 453      &lt;LeaveWindow&gt;:     unhighlight()
 454      &lt;Btn1Down&gt;,&lt;Btn1Up&gt;:     toggle() notify()
 455 </literallayout>
 456 </sect2>
 457
 458 <sect2 id="Toggle_Actions_b">
 459 <title>Toggle Actions_b</title>
 460 <para>
 461 The full list of actions supported by Toggle is:
 462 </para>
 463 <variablelist>
 464   <varlistentry>
 465     <term>
 466       <function>highlight</function>(<emphasis remap='I'>condition</emphasis>)
 467     </term>
 468     <listitem>
 469       <para>
 470 Displays the internal highlight border in the color (<function>foreground</function>
 471 or <function>background</function> ) that contrasts with the interior color of the
 472 Toggle widget.  The conditions <function>WhenUnset</function> and <function>Always</function> are
 473 understood by this action procedure.  If no argument is passed then
 474 <function>WhenUnset</function> is assumed.
 475       </para>
 476     </listitem>
 477   </varlistentry>
 478   <varlistentry>
 479     <term>
 480       <function>unhighlight</function>()
 481     </term>
 482     <listitem>
 483       <para>
 484 Displays the internal highlight border in the color (<function>foreground</function>
 485 or <function>background</function> ) that matches the interior color of the
 486 Toggle widget.
 487       </para>
 488     </listitem>
 489   </varlistentry>
 490   <varlistentry>
 491     <term>
 492       <function>set</function>()
 493     </term>
 494     <listitem>
 495       <para>
 496 Enters the <emphasis remap='I'>set</emphasis> state, in which <function>notify</function> is possible.  This
 497 action causes the Toggle widget to display its interior in the
 498 <function>foreground</function> color.  The label or bitmap is displayed in the
 499 <function>background</function> color.
 500       </para>
 501     </listitem>
 502   </varlistentry>
 503   <varlistentry>
 504     <term>
 505       <function>unset</function>()
 506     </term>
 507     <listitem>
 508       <para>
 509 Cancels the <emphasis remap='I'>set</emphasis> state and displays the interior of the Toggle widget in the
 510 <function>background</function> color.  The label or bitmap is displayed in the
 511 <function>foreground</function> color.
 512       </para>
 513     </listitem>
 514   </varlistentry>
 515   <varlistentry>
 516     <term>
 517       <function>toggle</function>()
 518     </term>
 519     <listitem>
 520       <para>
 521 Changes the current state of the Toggle widget, causing to be set
 522 if it was previously unset, and unset if it was previously set.
 523 If the widget is to be set, and is in a radio group then this procedure may
 524 unset another Toggle widget causing all routines on its callback list
 525 to be invoked.  The callback routines for the Toggle that
 526 is to be unset will be called before the one that is to be set.
 527       </para>
 528     </listitem>
 529   </varlistentry>
 530   <varlistentry>
 531     <term>
 532       <function>reset</function>()
 533     </term>
 534     <listitem>
 535       <para>
 536 Cancels any <function>set</function> or <function>highlight</function> and displays the interior of the
 537 Toggle widget in the <function>background</function> color, with the label displayed in the
 538 <function>foreground</function> color.
 539       </para>
 540     </listitem>
 541   </varlistentry>
 542   <varlistentry>
 543     <term>
 544       <function>notify</function>()
 545     </term>
 546     <listitem>
 547       <para>
 548 When the Toggle widget is in the <function>set</function> state this action calls all functions in
 549 the callback list named by the <function>callback</function> resource.  The value of
 550 the call_data argument in these callback functions is undefined.
 551     </para>
 552   </listitem>
 553   </varlistentry>
 554 </variablelist>
 555
 556 <para>
 557 When a bitmap of depth greater that one (1) is specified the
 558 <emphasis remap='I'>set</emphasis>(), <emphasis remap='I'>unset</emphasis>(), and <emphasis remap='I'>reset</emphasis>() actions have no effect,
 559 since there are no foreground and background colors used in a
 560 multi-plane pixmap.
 561 </para>
 562 </sect2>
 563
 564 <sect2 id="Radio_Groups">
 565 <title>Radio Groups</title>
 566 <para>
 567 There are typically two types of radio groups desired by applications.
 568 The default translations for the Toggle widget implement a "zero or one
 569 <!-- .IN "Radio groups" "zero or one of many" -->
 570 of many" radio group.  This means that there may be no more than one
 571 Toggle widget active, but there need not be any Toggle widgets active.
 572 </para>
 573
 574 <para>
 575 The other type of radio group is "one of many" and has the more strict
 576 policy that there will always be exactly one radio button active.
 577 Toggle widgets can be used to provide this interface with a slight
 578 modification to the translation table of each Toggle in the group.
 579 </para>
 580
 581 <literallayout class="monospaced">
 582      &lt;EnterWindow&gt;:     highlight(Always)
 583      &lt;LeaveWindow&gt;:     unhighlight()
 584      &lt;Btn1Down&gt;,&lt;Btn1Up&gt;:     set() notify()
 585 </literallayout>
 586
 587 <para>
 588 This translation table will not allow any Toggle to be <emphasis remap='I'>unset</emphasis>
 589 except as a result of another Toggle becoming <emphasis remap='I'>set</emphasis>.  It is
 590 the application programmer's responsibility to choose an initial
 591 state for the radio group by setting the <function>state</function> resource of one of
 592 its member widgets to <function>True</function>.
 593 </para>
 594 </sect2>
 595
 596 <sect2 id="toggle_convenience_routines">
 597 <title>Convenience Routines</title>
 598 <para>
 599 The following functions allow easy access to the Toggle widget's radio
 600 group functionality.
 601 </para>
 602
 603 <sect3 id="Changing_the_Toggle_s_Radio_Group_">
 604 <title>Changing the Toggle's Radio Group.</title>
 605 <para>
 606 To enable an application to change the Toggle's radio group, add
 607 the Toggle to a radio group, or remove the Toggle from a radio group, use
 608 <function>XawToggleChangeRadioGroup</function>.
 609 </para>
 610
 611 <funcsynopsis>
 612 <funcprototype>
 613   <funcdef>void<function> XawToggleChangeRadioGroup</function></funcdef>
 614   <paramdef>Widgetw,<parameter> radio_group</parameter></paramdef>
 615 </funcprototype>
 616 </funcsynopsis>
 617
 618 <para>
 619 <variablelist>
 620   <varlistentry>
 621     <term>
 622       <emphasis remap='I'>w</emphasis>
 623     </term>
 624     <listitem>
 625       <para>
 626 Specifies the Toggle widget.
 627       </para>
 628     </listitem>
 629   </varlistentry>
 630   <varlistentry>
 631     <term>
 632       <emphasis remap='I'>radio_group</emphasis>
 633     </term>
 634     <listitem>
 635       <para>
 636 Specifies any Toggle in the new radio group.  If NULL then the Toggle
 637 will be removed from any radio group of which it is a member.
 638     </para>
 639   </listitem>
 640   </varlistentry>
 641 </variablelist>
 642 </para>
 643
 644 <para>
 645 If a Toggle is already <emphasis remap='I'>set</emphasis> in the new radio group,
 646 and the Toggle to be added is also <emphasis remap='I'>set</emphasis> then the previously
 647 <emphasis remap='I'>set</emphasis> Toggle in the radio group is <emphasis remap='I'>unset</emphasis> and its callback
 648 procedures are invoked.
 649 Finding the Currently selected Toggle in a radio group of Toggles
 650 </para>
 651
 652 <para>
 653 To find the currently selected Toggle in a radio group of Toggle widgets
 654 use <function>XawToggleGetCurrent</function>.
 655 </para>
 656
 657 <funcsynopsis>
 658 <funcprototype>
 659   <funcdef>XtPointer<function> XawToggleGetCurrent</function></funcdef>
 660   <paramdef>XtPointer<parameter> XawToggleGetCurrent(radio_group)</parameter></paramdef>
 661   <paramdef>Widget<parameter> radio_group</parameter></paramdef>
 662 </funcprototype>
 663 </funcsynopsis>
 664
 665 <variablelist>
 666   <varlistentry>
 667     <term>
 668       <emphasis remap='I'>radio_group</emphasis>
 669     </term>
 670     <listitem>
 671       <para>
 672 Specifies any Toggle widget in the radio group.
 673     </para>
 674   </listitem>
 675   </varlistentry>
 676 </variablelist>
 677
 678 <para>
 679 The value returned by this function is the
 680 <function>radioData</function>
 681 of the Toggle in this radio group that is currently set.  The default
 682 value for <function>radioData</function>
 683 is the name of that Toggle widget.  If no Toggle is set in the radio
 684 group specified then NULL is returned.
 685 Changing the Toggle that is set in a radio group.
 686 </para>
 687
 688 <para>
 689 To change the Toggle that is currently set in a radio group use
 690 <function>XawToggleSetCurrent</function>.
 691 </para>
 692
 693 <funcsynopsis>
 694 <funcprototype>
 695   <funcdef>void<function> XawToggleSetCurrent</function></funcdef>
 696   <paramdef>voidXawToggleSetCurrent(radio_group,<parameter> radio_data)</parameter></paramdef>
 697   <paramdef>Widget<parameter> radio_group</parameter></paramdef>
 698   <paramdef>XtPointer<parameter> radio_data</parameter></paramdef>
 699 </funcprototype>
 700 </funcsynopsis>
 701
 702 <variablelist>
 703   <varlistentry>
 704     <term>
 705       <emphasis remap='I'>radio_group</emphasis>
 706     </term>
 707     <listitem>
 708       <para>
 709 Specifies any Toggle widget in the radio group.
 710       </para>
 711     </listitem>
 712   </varlistentry>
 713   <varlistentry>
 714     <term>
 715       <emphasis remap='I'>radio_data</emphasis>
 716     </term>
 717     <listitem>
 718       <para>
 719 Specifies the
 720 <function>radioData</function>
 721 identifying the Toggle that should be set in the radio group specified
 722 by the <emphasis remap='I'>radio_group</emphasis> argument.
 723     </para>
 724   </listitem>
 725   </varlistentry>
 726 </variablelist>
 727
 728
 729 <para>
 730 <function>XawToggleSetCurrent</function> locates the Toggle widget to be set by
 731 matching <emphasis remap='I'>radio_data</emphasis> against the <function>radioData</function> for each Toggle in
 732 the radio group.  If none match, <function>XawToggleSetCurrent</function> returns
 733 without making any changes.  If more than one Toggle matches,
 734 <function>XawToggleSetCurrent</function> will choose a Toggle to set arbitrarily.  If
 735 this causes any Toggle widgets to change state, all routines in their
 736 callback lists will be invoked.  The callback routines for a Toggle that
 737 is to be unset will be called before the one that is to be set.
 738 Unsetting all Toggles in a radio group.
 739 </para>
 740
 741 <para>
 742 To unset all Toggle widgets in a radio group use
 743 <function>XawToggleUnsetCurrent</function>.
 744 </para>
 745
 746 <funcsynopsis>
 747 <funcprototype>
 748   <funcdef>void<function> XawToggleUnsetCurrent</function></funcdef>
 749   <paramdef>void<parameter> XawToggleUnsetCurrent(radio_group)</parameter></paramdef>
 750   <paramdef>Widget<parameter> radio_group</parameter></paramdef>
 751 </funcprototype>
 752 </funcsynopsis>
 753
 754 <variablelist>
 755   <varlistentry>
 756     <term>
 757       <emphasis remap='I'>radio_group</emphasis>
 758     </term>
 759     <listitem>
 760       <para>
 761 Specifies any Toggle widget in the radio group.
 762     </para>
 763   </listitem>
 764   </varlistentry>
 765 </variablelist>
 766
 767 <para>
 768 If this causes a Toggle widget to change state, all routines on its
 769 callback list will be invoked.
 770 </para>
 771 </sect3>
 772 </sect2>
 773 </sect1>