doc/Xmu.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   4 [
   5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
   6 ]>
   7 <!-- lifted from troff+ms+XMan by doclifter -->
   8
   9 <article id='xmu'>
  10   <articleinfo>
  11     <title>Xmu and Xmuu Library API Reference</title>
  12     <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  13     <copyright><year>1989</year><holder>X Consortium</holder>
  14     </copyright>
  15     <abstract><para>&ldquo;Don't ask.&rdquo;</para></abstract>
  16
  17     <legalnotice>
  18
  19       <para>
  20 Permission is hereby granted, free of charge, to any person obtaining a copy
  21 of this software and associated documentation files (the &ldquo;Software&rdquo;), to deal
  22 in the Software without restriction, including without limitation the rights
  23 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  24 copies of the Software, and to permit persons to whom the Software is
  25 furnished to do so, subject to the following conditions:
  26       </para>
  27       <para>
  28 The above copyright notice and this permission notice shall be included in
  29 all copies or substantial portions of the Software.
  30       </para>
  31       <para>
  32 THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  33 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  34 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  35 X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  36 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  37 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  38       </para>
  39       <para>
  40 Except as contained in this notice, the name of the X Consortium shall not be
  41 used in advertising or otherwise to promote the sale, use or other dealings
  42 in this Software without prior written authorization from the X Consortium.
  43       </para>
  44       <para>
  45 <trademark><emphasis>X Window System</emphasis></trademark>
  46 is a trademark of The Open Group.
  47       </para>
  48
  49     </legalnotice>
  50   </articleinfo>
  51
  52   <sect1 id='Introduction'>
  53 <title>Introduction</title>
  54
  55     <para>
  56 The Xmu Library is a collection of miscellaneous (some might say random)
  57 utility functions that have been useful in building various applications
  58 and widgets.  This library is required by the Athena Widgets.
  59     </para>
  60
  61     <para>
  62 Starting in XFree86 4.1.0, and incorporated into X11R6.7 and later releases,
  63 a subset of the functions that do not rely on the Athena Widgets (libXaw)
  64 or X Toolkit Instrinsics (libXt) are provided in a second library, libXmuu.
  65     </para>
  66
  67     <para>
  68 Programs using either of these libraries are encouraged to determine the
  69 correct compiler and linker options via the <userinput>xmu</userinput> or
  70 <userinput>xmuu</userinput> module names for <command>pkg-config</command>,
  71 <indexterm>
  72 <primary><command>pkg-config</command></primary>
  73 </indexterm>
  74 such as:
  75
  76       <screen>
  77 cc -c xapplication.c `pkg-config --cflags xmu`
  78 cc -o xapplication xapplication.o `pkg-config --libs xmu`
  79       </screen>
  80     </para>
  81
  82   </sect1>
  83
  84   <sect1 id='Atom_Functions'>
  85 <title>Atom Functions</title>
  86
  87     <para>
  88 To use the functions and macros defined in this section, you should include
  89 the header file
  90 &lt;<filename class='headerfile'>X11/Xmu/Atoms.h</filename>&gt;
  91 <indexterm>
  92 <primary><filename class='headerfile'>X11/Xmu/Atoms.h</filename></primary>
  93 </indexterm>
  94 and link against the libXmu library.
  95     </para>
  96
  97     <funcsynopsis>
  98       <funcprototype>
  99         <funcdef><function>XA_ATOM_PAIR</function></funcdef>
 100         <paramdef><parameter>d</parameter></paramdef>
 101       </funcprototype>
 102       <funcprototype>
 103         <funcdef><function>XA_CHARACTER_POSITION</function></funcdef>
 104         <paramdef><parameter>d</parameter></paramdef>
 105       </funcprototype>
 106       <funcprototype>
 107         <funcdef><function>XA_CLASS</function></funcdef>
 108         <paramdef><parameter>d</parameter></paramdef>
 109       </funcprototype>
 110       <funcprototype>
 111         <funcdef><function>XA_CLIENT_WINDOW</function></funcdef>
 112         <paramdef><parameter>d</parameter></paramdef>
 113       </funcprototype>
 114       <funcprototype>
 115         <funcdef><function>XA_CLIPBOARD</function></funcdef>
 116         <paramdef><parameter>d</parameter></paramdef>
 117       </funcprototype>
 118       <funcprototype>
 119         <funcdef><function>XA_COMPOUND_TEXT</function></funcdef>
 120         <paramdef><parameter>d</parameter></paramdef>
 121       </funcprototype>
 122       <funcprototype>
 123         <funcdef><function>XA_DECNET_ADDRESS</function></funcdef>
 124         <paramdef><parameter>d</parameter></paramdef>
 125       </funcprototype>
 126       <funcprototype>
 127         <funcdef><function>XA_DELETE</function></funcdef>
 128         <paramdef><parameter>d</parameter></paramdef>
 129       </funcprototype>
 130       <funcprototype>
 131         <funcdef><function>XA_FILENAME</function></funcdef>
 132         <paramdef><parameter>d</parameter></paramdef>
 133       </funcprototype>
 134       <funcprototype>
 135         <funcdef><function>XA_HOSTNAME</function></funcdef>
 136         <paramdef><parameter>d</parameter></paramdef>
 137       </funcprototype>
 138       <funcprototype>
 139         <funcdef><function>XA_IP_ADDRESS</function></funcdef>
 140         <paramdef><parameter>d</parameter></paramdef>
 141       </funcprototype>
 142       <funcprototype>
 143         <funcdef><function>XA_LENGTH</function></funcdef>
 144         <paramdef><parameter>d</parameter></paramdef>
 145       </funcprototype>
 146       <funcprototype>
 147         <funcdef><function>XA_LIST_LENGTH</function></funcdef>
 148         <paramdef><parameter>d</parameter></paramdef>
 149       </funcprototype>
 150       <funcprototype>
 151         <funcdef><function>XA_NAME</function></funcdef>
 152         <paramdef><parameter>d</parameter></paramdef>
 153       </funcprototype>
 154       <funcprototype>
 155         <funcdef><function>XA_NET_ADDRESS</function></funcdef>
 156         <paramdef><parameter>d</parameter></paramdef>
 157       </funcprototype>
 158       <funcprototype>
 159         <funcdef><function>XA_NULL</function></funcdef>
 160         <paramdef><parameter>d</parameter></paramdef>
 161       </funcprototype>
 162       <funcprototype>
 163         <funcdef><function>XA_OWNER_OS</function></funcdef>
 164         <paramdef><parameter>d</parameter></paramdef>
 165       </funcprototype>
 166       <funcprototype>
 167         <funcdef><function>XA_SPAN</function></funcdef>
 168         <paramdef><parameter>d</parameter></paramdef>
 169       </funcprototype>
 170       <funcprototype>
 171         <funcdef><function>XA_TARGETS</function></funcdef>
 172         <paramdef><parameter>d</parameter></paramdef>
 173       </funcprototype>
 174       <funcprototype>
 175         <funcdef><function>XA_TEXT</function></funcdef>
 176         <paramdef><parameter>d</parameter></paramdef>
 177       </funcprototype>
 178       <funcprototype>
 179         <funcdef><function>XA_TIMESTAMP</function></funcdef>
 180         <paramdef><parameter>d</parameter></paramdef>
 181       </funcprototype>
 182       <funcprototype>
 183         <funcdef><function>XA_USER</function></funcdef>
 184         <paramdef><parameter>d</parameter></paramdef>
 185       </funcprototype>
 186       <funcprototype>
 187         <funcdef><function>XA_UTF8_STRING</function></funcdef>
 188         <paramdef><parameter>d</parameter></paramdef>
 189       </funcprototype>
 190     </funcsynopsis>
 191
 192     <para>
 193       <indexterm>
 194         <primary><type>Atom</type></primary>
 195       </indexterm>
 196 These macros take a display as argument and return an
 197 <type>Atom</type>.
 198 The name of the
 199 atom is obtained from the macro name by removing the leading characters
 200 &ldquo;<code>XA_</code>&rdquo;.  The
 201 <type>Atom</type>
 202 value is cached, such that subsequent requests do not cause
 203 another round-trip to the server.
 204     </para>
 205
 206     <para>
 207       <indexterm zone="XmuMakeAtom">
 208         <primary><xref linkend='XmuMakeAtom' xrefstyle='select: title'/></primary>
 209       </indexterm>
 210       <funcsynopsis id='XmuMakeAtom'>
 211         <funcprototype>
 212           <funcdef>AtomPtr <function>XmuMakeAtom</function></funcdef>
 213           <paramdef>const char *<parameter>name</parameter></paramdef>
 214         </funcprototype>
 215       </funcsynopsis>
 216       <variablelist>
 217         <varlistentry>
 218           <term><parameter>name</parameter></term>
 219           <listitem><para>
 220 specifies the atom name
 221             </para></listitem>
 222         </varlistentry>
 223       </variablelist>
 224
 225 This function creates and initializes an opaque object, an
 226 <type>AtomPtr</type>,
 227 for an
 228 <type>Atom</type>
 229 with the
 230 given name.
 231 <xref linkend='XmuInternAtom' xrefstyle='select: title'/>
 232 can be used to cache the Atom value for one or more displays.
 233     </para>
 234
 235     <para>
 236       <indexterm zone="XmuNameOfAtom">
 237         <primary><xref linkend='XmuNameOfAtom' xrefstyle='select: title'/></primary>
 238       </indexterm>
 239       <funcsynopsis id='XmuNameOfAtom'>
 240         <funcprototype>
 241           <funcdef>char *<function>XmuNameOfAtom</function></funcdef>
 242           <paramdef>AtomPtr <parameter>atom_ptr</parameter></paramdef>
 243         </funcprototype>
 244       </funcsynopsis>
 245       <variablelist>
 246         <varlistentry>
 247           <term><parameter>atom_ptr</parameter></term>
 248           <listitem><para>
 249 specifies the AtomPtr
 250             </para></listitem>
 251         </varlistentry>
 252       </variablelist>
 253
 254 The function returns the name of an AtomPtr.
 255     </para>
 256
 257     <para>
 258       <indexterm zone="XmuInternAtom">
 259         <primary><xref linkend='XmuInternAtom' xrefstyle='select: title'/></primary>
 260       </indexterm>
 261       <funcsynopsis id='XmuInternAtom'>
 262         <funcprototype>
 263           <funcdef>Atom <function>XmuInternAtom</function></funcdef>
 264           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 265           <paramdef>AtomPtr <parameter>atom_ptr</parameter></paramdef>
 266         </funcprototype>
 267       </funcsynopsis>
 268       <variablelist>
 269         <varlistentry>
 270           <term><parameter>dpy</parameter></term>
 271           <listitem><para>
 272 specifies the connection to the X server
 273             </para></listitem>
 274         </varlistentry>
 275         <varlistentry>
 276           <term><parameter>atom_ptr</parameter></term>
 277           <listitem><para>
 278 specifies the AtomPtr
 279             </para></listitem>
 280         </varlistentry>
 281       </variablelist>
 282
 283 This function returns the
 284 <type>Atom</type>
 285 for an
 286 <type>AtomPtr</type>.
 287 The
 288 <type>Atom</type>
 289 is cached,
 290 such that subsequent requests do not cause another round-trip to the server.
 291     </para>
 292
 293     <para>
 294       <indexterm zone="XmuGetAtomName">
 295         <primary><xref linkend='XmuGetAtomName' xrefstyle='select: title'/></primary>
 296       </indexterm>
 297       <funcsynopsis id='XmuGetAtomName'>
 298         <funcprototype>
 299           <funcdef>char *<function>XmuGetAtomName</function></funcdef>
 300           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 301           <paramdef>Atom <parameter>atom</parameter></paramdef>
 302         </funcprototype>
 303       </funcsynopsis>
 304       <variablelist>
 305         <varlistentry>
 306           <term><parameter>dpy</parameter></term>
 307           <listitem><para>
 308 specifies the connection to the X server
 309            </para></listitem>
 310         </varlistentry>
 311         <varlistentry>
 312           <term><parameter>atom</parameter></term>
 313           <listitem><para>
 314 specifies the atom whose name is desired
 315             </para></listitem>
 316         </varlistentry>
 317       </variablelist>
 318
 319 This function returns the name of an
 320 <type>Atom</type>.
 321 The result is cached, such that subsequent
 322 requests do not cause another round-trip to the server.
 323     </para>
 324
 325     <para>
 326       <indexterm zone="XmuInternStrings">
 327         <primary><xref linkend='XmuInternStrings' xrefstyle='select: title'/></primary>
 328       </indexterm>
 329       <funcsynopsis id='XmuInternStrings'>
 330         <funcprototype>
 331           <funcdef>void <function>XmuInternStrings</function></funcdef>
 332           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 333           <paramdef>String *<parameter>names</parameter></paramdef>
 334           <paramdef>Cardinal <parameter>count</parameter></paramdef>
 335           <paramdef>Atom *<parameter>atoms</parameter></paramdef>
 336         </funcprototype>
 337       </funcsynopsis>
 338       <variablelist>
 339         <varlistentry>
 340           <term><parameter>dpy</parameter></term>
 341           <listitem><para>
 342 specifies the connection to the X server
 343            </para></listitem>
 344         </varlistentry>
 345         <varlistentry>
 346           <term><parameter>names</parameter></term>
 347           <listitem><para>
 348 specifies the strings to intern
 349             </para></listitem>
 350         </varlistentry>
 351         <varlistentry>
 352           <term><parameter>count</parameter></term>
 353           <listitem><para>
 354 specifies the number of strings
 355             </para></listitem>
 356         </varlistentry>
 357         <varlistentry>
 358           <term><parameter>atoms</parameter></term>
 359           <listitem><para>
 360 returns the list of Atom values
 361             </para></listitem>
 362         </varlistentry>
 363       </variablelist>
 364
 365 This function converts a list of atom names into
 366 <type>Atom</type>
 367 values.  The results are cached, such
 368 that subsequent requests do not cause further round-trips to the server.
 369 The caller is responsible for preallocating the array pointed at by atoms.
 370     </para>
 371
 372   </sect1>
 373
 374   <sect1 id='Error_Handler_Functions'>
 375 <title>Error Handler Functions</title>
 376
 377     <para>
 378 To use the functions defined in this section, you should include the header
 379 file
 380 &lt;<filename class='headerfile'>X11/Xmu/Error.h</filename>&gt;
 381 <indexterm>
 382 <primary><filename class='headerfile'>X11/Xmu/Error.h</filename></primary>
 383 </indexterm>
 384 and link against the libXmu or libXmuu library.
 385     </para>
 386
 387     <para>
 388       <indexterm zone="XmuPrintDefaultErrorMessage">
 389         <primary><xref linkend='XmuPrintDefaultErrorMessage' xrefstyle='select: title'/></primary>
 390       </indexterm>
 391       <funcsynopsis id='XmuPrintDefaultErrorMessage'>
 392         <funcprototype>
 393           <funcdef>int <function>XmuPrintDefaultErrorMessage</function></funcdef>
 394           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 395           <paramdef>XErrorEvent *<parameter>event</parameter></paramdef>
 396           <paramdef>FILE *<parameter>fp</parameter></paramdef>
 397         </funcprototype>
 398       </funcsynopsis>
 399       <variablelist>
 400         <varlistentry>
 401           <term><parameter>dpy</parameter></term>
 402           <listitem><para>
 403 specifies the connection to the X server
 404             </para></listitem>
 405         </varlistentry>
 406         <varlistentry>
 407           <term><parameter>event</parameter></term>
 408           <listitem><para>
 409 specifies the error
 410             </para></listitem>
 411         </varlistentry>
 412         <varlistentry>
 413           <term><parameter>fp</parameter></term>
 414           <listitem><para>
 415               specifies where to print the error message
 416             </para></listitem>
 417         </varlistentry>
 418       </variablelist>
 419
 420 This function prints an error message, equivalent to Xlib's default error
 421 message for protocol errors.  It returns a non-zero value
 422 if the caller should consider exiting, otherwise it returns 0.
 423 This function can be used when you need to
 424 write your own error handler, but need to print out an error from within
 425 that handler.
 426     </para>
 427
 428     <para id="XmuSimpleErrorHandler">
 429       <indexterm zone="XmuSimpleErrorHandler">
 430         <primary><function>XmuSimpleErrorHandler</function></primary>
 431       </indexterm>
 432       <funcsynopsis>
 433         <funcprototype>
 434           <funcdef>int <function>XmuSimpleErrorHandler</function></funcdef>
 435           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 436           <paramdef>XErrorEvent *<parameter>errorp</parameter></paramdef>
 437         </funcprototype>
 438       </funcsynopsis>
 439       <variablelist>
 440         <varlistentry>
 441           <term><parameter>dpy</parameter></term>
 442           <listitem><para>
 443 specifies the connection to the X server
 444             </para></listitem>
 445         </varlistentry>
 446         <varlistentry>
 447           <term><parameter>errorp</parameter></term>
 448           <listitem><para>
 449 specifies the error
 450             </para></listitem>
 451         </varlistentry>
 452       </variablelist>
 453
 454 This function ignores errors for
 455 <errorname>BadWindow</errorname>
 456 errors for
 457 <olink targetdoc='libX11' targetptr='XQueryTree'><function>XQueryTree</function></olink>
 458 and
 459 <olink targetdoc='libX11' targetptr='XGetWindowAttributes'><function>XGetWindowAttributes</function></olink>,
 460 and ignores
 461 <errorname>BadDrawable</errorname>
 462 errors for
 463 <olink targetdoc='libX11' targetptr='XGetGeometry'><function>XGetGeometry</function></olink>;
 464 it returns 0 in those cases.  Otherwise, it prints the default error message,
 465 and returns a non-zero value if the caller should consider exiting,
 466 and 0 if the caller should not exit.
 467     </para>
 468   </sect1>
 469
 470   <sect1 id='System_Utility_Functions'>
 471 <title>System Utility Functions</title>
 472
 473     <para>
 474 To use the functions defined in this section, you should include the header
 475 file
 476 &lt;<filename class='headerfile'>X11/Xmu/SysUtil.h</filename>&gt;
 477 <indexterm>
 478 <primary><filename class='headerfile'>X11/Xmu/SysUtil.h</filename></primary>
 479 </indexterm>
 480 and link against the libXmu or libXmuu library.
 481     </para>
 482
 483     <para id="XmuGetHostname">
 484       <indexterm zone="XmuGetHostname">
 485         <primary><function>XmuGetHostname</function></primary>
 486       </indexterm>
 487       <funcsynopsis>
 488         <funcprototype>
 489           <funcdef>int <function>XmuGetHostname</function></funcdef>
 490           <paramdef>char *<parameter>buf</parameter></paramdef>
 491           <paramdef>int <parameter>maxlen</parameter></paramdef>
 492         </funcprototype>
 493       </funcsynopsis>
 494      <variablelist>
 495         <varlistentry>
 496           <term><parameter>buf</parameter></term>
 497           <listitem><para>
 498 returns the host name
 499             </para></listitem>
 500         </varlistentry>
 501         <varlistentry>
 502           <term><parameter>maxlen</parameter></term>
 503           <listitem><para>
 504 specifies the length of <parameter>buf</parameter>
 505             </para></listitem>
 506         </varlistentry>
 507       </variablelist>
 508
 509 This function stores the null terminated name of the local host in
 510 <parameter>buf</parameter>, and
 511 returns length of the name.  This function hides operating system differences,
 512 such as whether to call <function>gethostname</function> or
 513 <function>uname</function>.
 514     </para>
 515
 516     <para id="XmuSnprintf">
 517       <indexterm zone="XmuSnprintf">
 518         <primary><function>XmuSnprintf</function></primary>
 519       </indexterm>
 520       <funcsynopsis>
 521         <funcprototype>
 522           <funcdef>int <function>XmuSnprintf</function></funcdef>
 523           <paramdef>char *<parameter>str</parameter></paramdef>
 524           <paramdef>int <parameter>size</parameter></paramdef>
 525           <paramdef><parameter>...</parameter></paramdef>
 526         </funcprototype>
 527       </funcsynopsis>
 528      <variablelist>
 529         <varlistentry>
 530           <term><parameter>str</parameter></term>
 531           <listitem><para>
 532 string to write output to
 533             </para></listitem>
 534         </varlistentry>
 535         <varlistentry>
 536           <term><parameter>size</parameter></term>
 537           <listitem><para>
 538 specifies the size of <parameter>str</parameter>
 539             </para></listitem>
 540         </varlistentry>
 541       </variablelist>
 542
 543 This function was provided as a portable implementation of
 544 <function>snprintf</function> before all platforms could be
 545 relied on to provide their own.   It is now deprecated in favor of
 546 calling <function>snprintf</function> directly and should only be used
 547 in software that needs to continue to support non-Unix98 compliant platforms.
 548     </para>
 549
 550
 551   </sect1>
 552
 553   <sect1 id='Window_Utility_Functions'>
 554 <title>Window Utility Functions</title>
 555
 556     <para>
 557 To use the functions defined in this section, you should include the header
 558 file
 559 &lt;<filename class='headerfile'>X11/Xmu/WinUtil.h</filename>&gt;
 560 <indexterm>
 561 <primary><filename class='headerfile'>X11/Xmu/WinUtil.h</filename></primary>
 562 </indexterm>.
 563 To use <function>XmuClientWindow</function>, you may link against either the
 564 libXmu or libXmuu libraries.   The other functions in this section require
 565 linking against the libXmu library.
 566     </para>
 567
 568     <para id="XmuScreenOfWindow">
 569       <indexterm zone="XmuScreenOfWindow">
 570         <primary><function>XmuScreenOfWindow</function></primary>
 571       </indexterm>
 572       <funcsynopsis>
 573         <funcprototype>
 574           <funcdef>Screen *<function>XmuScreenOfWindow</function></funcdef>
 575           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 576           <paramdef>Window <parameter>w</parameter></paramdef>
 577         </funcprototype>
 578       </funcsynopsis>
 579       <variablelist>
 580         <varlistentry>
 581           <term><parameter>dpy</parameter></term>
 582           <listitem><para>
 583 specifies the connection to the X server
 584             </para></listitem>
 585         </varlistentry>
 586         <varlistentry>
 587           <term><parameter>w</parameter></term>
 588           <listitem><para>
 589 specifies the window
 590             </para></listitem>
 591         </varlistentry>
 592       </variablelist>
 593
 594 This function returns the
 595 <type>Screen</type>
 596 on which the specified window was created.
 597     </para>
 598
 599     <para id="XmuClientWindow">
 600       <indexterm zone="XmuClientWindow">
 601         <primary><function>XmuClientWindow</function></primary>
 602       </indexterm>
 603       <funcsynopsis>
 604         <funcprototype>
 605           <funcdef>Window <function>XmuClientWindow</function></funcdef>
 606           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 607           <paramdef>Window <parameter>win</parameter></paramdef>
 608         </funcprototype>
 609       </funcsynopsis>
 610       <variablelist>
 611         <varlistentry>
 612           <term><parameter>dpy</parameter></term>
 613           <listitem><para>
 614 specifies the connection to the X server
 615             </para></listitem>
 616         </varlistentry>
 617         <varlistentry>
 618           <term><parameter>win</parameter></term>
 619           <listitem><para>
 620 specifies the window
 621             </para></listitem>
 622         </varlistentry>
 623       </variablelist>
 624
 625       <indexterm zone="XmuClientWindow">
 626         <primary><property>WM_STATE</property></primary>
 627       </indexterm>
 628 This function finds a window, at or below the specified window, which has a
 629 <property>WM_STATE</property> property.  If such a window is found, it is
 630 returned, otherwise the
 631 argument window is returned.
 632     </para>
 633
 634     <para id="XmuUpdateMapHints">
 635       <indexterm zone="XmuUpdateMapHints">
 636         <primary><function>XmuUpdateMapHints</function></primary>
 637       </indexterm>
 638       <funcsynopsis>
 639         <funcprototype>
 640           <funcdef>Bool <function>XmuUpdateMapHints</function></funcdef>
 641           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 642           <paramdef>Window <parameter>w</parameter></paramdef>
 643           <paramdef>XSizeHints *<parameter>hints</parameter></paramdef>
 644         </funcprototype>
 645       </funcsynopsis>
 646       <variablelist>
 647         <varlistentry>
 648           <term><parameter>dpy</parameter></term>
 649           <listitem><para>
 650 specifies the connection to the X server
 651             </para></listitem>
 652         </varlistentry>
 653         <varlistentry>
 654           <term><parameter>win</parameter></term>
 655           <listitem><para>
 656 specifies the window
 657             </para></listitem>
 658         </varlistentry>
 659         <varlistentry>
 660           <term><parameter>hints</parameter></term>
 661           <listitem><para>
 662 specifies the new hints, or <symbol>NULL</symbol>
 663             </para></listitem>
 664         </varlistentry>
 665       </variablelist>
 666
 667 This function clears the
 668 <symbol>PPosition</symbol>
 669 and
 670 <symbol>PSize</symbol>
 671 flags and sets the
 672 <symbol>USPosition</symbol>
 673 and
 674 <symbol>USSize</symbol>
 675 flags in the hints structure, and then stores the hints for the
 676 window using
 677       <indexterm zone="XmuUpdateMapHints">
 678         <primary><olink targetdoc='libX11' targetptr='XSetWMNormalHints'><function>XSetWMNormalHints</function></olink></primary>
 679       </indexterm>
 680 <olink targetdoc='libX11' targetptr='XSetWMNormalHints'><function>XSetWMNormalHints</function></olink>
 681 and returns
 682 <symbol>True</symbol>.
 683 If <symbol>NULL</symbol> is passed for the
 684 hints structure, then the current hints are read back from the window using
 685       <indexterm zone="XmuUpdateMapHints">
 686         <primary><olink targetdoc='libX11' targetptr='XGetWMNormalHints'><function>XGetWMNormalHints</function></olink></primary>
 687       </indexterm>
 688 <olink targetdoc='libX11' targetptr='XGetWMNormalHints'><function>XGetWMNormalHints</function></olink>
 689 and are used instead, and
 690 <symbol>True</symbol>
 691 is returned; otherwise
 692 <symbol>False</symbol>
 693 is returned.
 694     </para>
 695
 696   </sect1>
 697
 698   <sect1 id='Cursor_Utility_Functions'>
 699 <title>Cursor Utility Functions</title>
 700
 701     <para>
 702 To use the functions defined in this section, you should include the header
 703 file
 704 &lt;<filename class='headerfile'>X11/Xmu/CurUtil.h</filename>&gt;
 705 <indexterm>
 706 <primary><filename class='headerfile'>X11/Xmu/CurUtil.h</filename></primary>
 707 </indexterm>
 708 and link against the libXmu or libXmuu library.
 709     </para>
 710
 711     <para id="XmuCursorNameToIndex">
 712       <indexterm zone="XmuCursorNameToIndex">
 713         <primary><function>XmuCursorNameToIndex</function></primary>
 714       </indexterm>
 715       <funcsynopsis>
 716         <funcprototype>
 717           <funcdef>int <function>XmuCursorNameToIndex</function></funcdef>
 718           <paramdef>const char *<parameter>name</parameter></paramdef>
 719         </funcprototype>
 720       </funcsynopsis>
 721       <variablelist>
 722         <varlistentry>
 723           <term><parameter>name</parameter></term>
 724           <listitem><para>
 725 specifies the name of the cursor
 726             </para></listitem>
 727         </varlistentry>
 728       </variablelist>
 729
 730 This function takes the name of a standard cursor and returns its index
 731 in the standard cursor font.  The cursor names are formed by removing the
 732 &ldquo;<code>XC_</code>&rdquo; prefix from the cursor defines listed in
 733 Appendix B of the Xlib
 734 manual.
 735     </para>
 736
 737   </sect1>
 738
 739   <sect1 id='Graphics_Functions'>
 740 <title>Graphics Functions</title>
 741
 742     <para>
 743 To use the functions defined in this section, you should include the header
 744 file
 745 &lt;<filename class='headerfile'>X11/Xmu/Drawing.h</filename>&gt;
 746 <indexterm>
 747 <primary><filename class='headerfile'>X11/Xmu/Drawing.h</filename></primary>
 748 </indexterm>
 749 and link against the libXmu library.
 750     </para>
 751
 752     <para id="XmuDrawRoundedRectangle">
 753       <indexterm zone="XmuDrawRoundedRectangle">
 754         <primary><function>XmuDrawRoundedRectangle</function></primary>
 755       </indexterm>
 756       <funcsynopsis>
 757         <funcprototype>
 758           <funcdef>void <function>XmuDrawRoundedRectangle</function></funcdef>
 759           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 760           <paramdef>Drawable <parameter>draw</parameter></paramdef>
 761           <paramdef>GC <parameter>gc</parameter></paramdef>
 762           <paramdef>int <parameter>x</parameter></paramdef>
 763           <paramdef>int <parameter>y</parameter></paramdef>
 764           <paramdef>int <parameter>w</parameter></paramdef>
 765           <paramdef>int <parameter>h</parameter></paramdef>
 766           <paramdef>int <parameter>ew</parameter></paramdef>
 767           <paramdef>int <parameter>eh</parameter></paramdef>
 768         </funcprototype>
 769       </funcsynopsis>
 770       <variablelist>
 771         <varlistentry>
 772           <term><parameter>dpy</parameter></term>
 773           <listitem><para>
 774 specifies the connection to the X server
 775             </para></listitem>
 776         </varlistentry>
 777         <varlistentry>
 778           <term><parameter>draw</parameter></term>
 779           <listitem><para>
 780 specifies the drawable
 781             </para></listitem>
 782         </varlistentry>
 783         <varlistentry>
 784           <term><parameter>gc</parameter></term>
 785           <listitem><para>
 786 specifies the GC
 787             </para></listitem>
 788         </varlistentry>
 789         <varlistentry>
 790           <term><parameter>x</parameter></term>
 791           <listitem><para>
 792 specifies the upper left x coordinate
 793             </para></listitem>
 794         </varlistentry>
 795         <varlistentry>
 796           <term><parameter>y</parameter></term>
 797           <listitem><para>
 798 specifies the upper left y coordinate
 799             </para></listitem>
 800         </varlistentry>
 801         <varlistentry>
 802           <term><parameter>w</parameter></term>
 803           <listitem><para>
 804 specifies the rectangle width
 805             </para></listitem>
 806         </varlistentry>
 807         <varlistentry>
 808           <term><parameter>h</parameter></term>
 809           <listitem><para>
 810 specifies the rectangle height
 811             </para></listitem>
 812         </varlistentry>
 813         <varlistentry>
 814           <term><parameter>ew</parameter></term>
 815           <listitem><para>
 816 specifies the corner width
 817             </para></listitem>
 818         </varlistentry>
 819         <varlistentry>
 820           <term><parameter>eh</parameter></term>
 821           <listitem><para>
 822 specifies the corner height
 823             </para></listitem>
 824         </varlistentry>
 825       </variablelist>
 826
 827 This function draws a rounded rectangle, where x, y, w, h are the dimensions
 828 of the overall rectangle, and ew and eh are the sizes of a bounding box that
 829 the corners are drawn inside of; ew should be no more than half of w, and eh
 830 should be no more than half of h.  The current GC line attributes control
 831 all attributes of the line.
 832     </para>
 833
 834     <para id="XmuFillRoundedRectangle">
 835       <indexterm zone="XmuFillRoundedRectangle">
 836         <primary><function>XmuFillRoundedRectangle</function></primary>
 837       </indexterm>
 838       <funcsynopsis>
 839         <funcprototype>
 840           <funcdef>void <function>XmuFillRoundedRectangle</function></funcdef>
 841           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 842           <paramdef>Drawable <parameter>draw</parameter></paramdef>
 843           <paramdef>GC <parameter>gc</parameter></paramdef>
 844           <paramdef>int <parameter>x</parameter></paramdef>
 845           <paramdef>int <parameter>y</parameter></paramdef>
 846           <paramdef>int <parameter>w</parameter></paramdef>
 847           <paramdef>int <parameter>h</parameter></paramdef>
 848           <paramdef>int <parameter>ew</parameter></paramdef>
 849           <paramdef>int <parameter>eh</parameter></paramdef>
 850         </funcprototype>
 851       </funcsynopsis>
 852       <variablelist>
 853         <varlistentry>
 854           <term><parameter>dpy</parameter></term>
 855           <listitem><para>
 856 specifies the connection to the X server
 857             </para></listitem>
 858         </varlistentry>
 859         <varlistentry>
 860           <term><parameter>draw</parameter></term>
 861           <listitem><para>
 862 specifies the drawable
 863             </para></listitem>
 864         </varlistentry>
 865         <varlistentry>
 866           <term><parameter>gc</parameter></term>
 867           <listitem><para>
 868 specifies the GC
 869             </para></listitem>
 870         </varlistentry>
 871         <varlistentry>
 872           <term><parameter>x</parameter></term>
 873           <listitem><para>
 874 specifies the upper left x coordinate
 875             </para></listitem>
 876         </varlistentry>
 877         <varlistentry>
 878           <term><parameter>y</parameter></term>
 879           <listitem><para>
 880 specifies the upper left y coordinate
 881             </para></listitem>
 882         </varlistentry>
 883         <varlistentry>
 884           <term><parameter>w</parameter></term>
 885           <listitem><para>
 886 specifies the rectangle width
 887             </para></listitem>
 888         </varlistentry>
 889         <varlistentry>
 890           <term><parameter>h</parameter></term>
 891           <listitem><para>
 892 specifies the rectangle height
 893             </para></listitem>
 894         </varlistentry>
 895         <varlistentry>
 896           <term><parameter>ew</parameter></term>
 897           <listitem><para>
 898 specifies the corner width
 899             </para></listitem>
 900         </varlistentry>
 901         <varlistentry>
 902           <term><parameter>eh</parameter></term>
 903           <listitem><para>
 904 specifies the corner height
 905             </para></listitem>
 906         </varlistentry>
 907       </variablelist>
 908
 909 This function draws a filled rounded rectangle, where x, y, w, h are the
 910 dimensions of the overall rectangle, and ew and eh are the sizes of a
 911 bounding box that the corners are drawn inside of; ew should be no more than
 912 half of w, and eh should be no more than half of h.  The current GC fill
 913 settings control all attributes of the fill contents.
 914       </para>
 915
 916     <para id="XmuDrawLogo">
 917       <indexterm zone="XmuDrawLogo">
 918         <primary><function>XmuDrawLogo</function></primary>
 919       </indexterm>
 920       <funcsynopsis>
 921         <funcprototype>
 922           <funcdef><function>XmuDrawLogo</function></funcdef>
 923           <paramdef>Display *<parameter>dpy</parameter></paramdef>
 924           <paramdef>Drawable <parameter>drawable</parameter></paramdef>
 925           <paramdef>GC <parameter>gcFore</parameter></paramdef>
 926           <paramdef>GC <parameter>gcBack</parameter></paramdef>
 927           <paramdef>int <parameter>x</parameter></paramdef>
 928           <paramdef>int <parameter>y</parameter></paramdef>
 929           <paramdef>unsigned int <parameter>width</parameter></paramdef>
 930           <paramdef>unsigned int <parameter>height</parameter></paramdef>
 931         </funcprototype>
 932       </funcsynopsis>
 933       <variablelist>
 934         <varlistentry>
 935           <term><parameter>dpy</parameter></term>
 936           <listitem><para>
 937 specifies the connection to the X server
 938             </para></listitem>
 939         </varlistentry>
 940         <varlistentry>
 941           <term><parameter>drawable</parameter></term>
 942           <listitem><para>
 943 specifies the drawable
 944             </para></listitem>
 945         </varlistentry>
 946         <varlistentry>
 947           <term><parameter>gcFore</parameter></term>
 948           <listitem><para>
 949 specifies the foreground GC
 950             </para></listitem>
 951         </varlistentry>
 952         <varlistentry>
 953           <term><parameter>gcBack</parameter></term>
 954           <listitem><para>
 955 specifies the background GC
 956             </para></listitem>
 957         </varlistentry>
 958         <varlistentry>
 959           <term><parameter>x</parameter></term>
 960           <listitem><para>
 961 specifies the upper left x coordinate
 962             </para></listitem>
 963         </varlistentry>
 964         <varlistentry>
 965           <term><parameter>y</parameter></term>
 966           <listitem><para>
 967 specifies the upper left y coordinate
 968             </para></listitem>
 969         </varlistentry>
 970         <varlistentry>
 971           <term><parameter>width</parameter></term>
 972           <listitem><para>
 973 specifies the logo width
 974             </para></listitem>
 975         </varlistentry>
 976         <varlistentry>
 977           <term><parameter>height</parameter></term>
 978           <listitem><para>
 979 specifies the logo height
 980             </para></listitem>
 981         </varlistentry>
 982       </variablelist>
 983
 984 This function draws the &ldquo;official&rdquo; X Window System logo
 985 (<xref linkend="xlogo"/>).  The bounding box
 986 of the logo in the drawable is given by x, y, width, and height.  The logo
 987 itself is filled using gcFore, and the rest of the rectangle is filled using
 988 gcBack.
 989     </para>
 990       <figure id="xlogo" pgwide="0">
 991         <title>The X Logo</title>
 992         <mediaobject>
 993           <imageobject>
 994             <imagedata id="xlogo-svg" format="SVG" fileref="xlogo.svg"/>
 995           </imageobject>
 996         </mediaobject>
 997       </figure>
 998     <para id="XmuCreateStippledPixmap">
 999       <indexterm zone="XmuCreateStippledPixmap">
1000         <primary><function>XmuCreateStippledPixmap</function></primary>
1001       </indexterm>
1002       <funcsynopsis>
1003         <funcprototype>
1004           <funcdef>Pixmap <function>XmuCreateStippledPixmap</function></funcdef>
1005           <paramdef>Screen *<parameter>screen</parameter></paramdef>
1006           <paramdef>Pixel <parameter>fore</parameter></paramdef>
1007           <paramdef>Pixel <parameter>back</parameter></paramdef>
1008           <paramdef>unsigned int <parameter>depth</parameter></paramdef>
1009         </funcprototype>
1010       </funcsynopsis>
1011       <variablelist>
1012         <varlistentry>
1013           <term><parameter>screen</parameter></term>
1014           <listitem><para>
1015 specifies the screen the pixmap is created on
1016             </para></listitem>
1017         </varlistentry>
1018         <varlistentry>
1019           <term><parameter>fore</parameter></term>
1020           <listitem><para>
1021 specifies the foreground pixel value
1022             </para></listitem>
1023         </varlistentry>
1024         <varlistentry>
1025           <term><parameter>back</parameter></term>
1026           <listitem><para>
1027 specifies the background pixel value
1028             </para></listitem>
1029         </varlistentry>
1030         <varlistentry>
1031           <term><parameter>depth</parameter></term>
1032           <listitem><para>
1033 specifies the depth of the pixmap
1034             </para></listitem>
1035         </varlistentry>
1036       </variablelist>
1037
1038 This function creates a two pixel by one pixel stippled pixmap of specified
1039 depth on the specified screen.  The pixmap is cached so that multiple
1040 requests share the same pixmap.  The pixmap should be freed with
1041 <function>XmuReleaseStippledPixmap</function>
1042 to maintain correct reference counts.
1043     </para>
1044
1045     <para id="XmuReleaseStippledPixmap">
1046       <indexterm zone="XmuReleaseStippledPixmap">
1047         <primary><function>XmuReleaseStippledPixmap</function></primary>
1048       </indexterm>
1049       <funcsynopsis>
1050         <funcprototype>
1051           <funcdef>void <function>XmuReleaseStippledPixmap</function></funcdef>
1052           <paramdef>Screen *<parameter>screen</parameter></paramdef>
1053           <paramdef>Pixmap <parameter>pixmap</parameter></paramdef>
1054         </funcprototype>
1055       </funcsynopsis>
1056       <variablelist>
1057         <varlistentry>
1058           <term><parameter>screen</parameter></term>
1059           <listitem><para>
1060 specifies the screen the pixmap was created on
1061             </para></listitem>
1062         </varlistentry>
1063         <varlistentry>
1064           <term><parameter>pixmap</parameter></term>
1065           <listitem><para>
1066 specifies the pixmap to free
1067             </para></listitem>
1068         </varlistentry>
1069       </variablelist>
1070
1071 This function frees a pixmap created with
1072 <function>XmuCreateStippledPixmap</function>.
1073     </para>
1074
1075     <para id="XmuReadBitmapData">
1076       <indexterm zone="XmuReadBitmapData">
1077         <primary><function>XmuReadBitmapData</function></primary>
1078       </indexterm>
1079       <funcsynopsis>
1080         <funcprototype>
1081           <funcdef>int <function>XmuReadBitmapData</function></funcdef>
1082           <paramdef>FILE *<parameter>fstream</parameter></paramdef>
1083           <paramdef>unsigned int *<parameter>width</parameter></paramdef>
1084           <paramdef>unsigned int *<parameter>height</parameter></paramdef>
1085           <paramdef>unsigned char **<parameter>datap</parameter></paramdef>
1086           <paramdef>int *<parameter>x_hot</parameter></paramdef>
1087           <paramdef>int *<parameter>y_hot</parameter></paramdef>
1088         </funcprototype>
1089       </funcsynopsis>
1090       <variablelist>
1091         <varlistentry>
1092           <term><parameter>fstream</parameter></term>
1093           <listitem><para>
1094 specifies the stream to read from
1095             </para></listitem>
1096         </varlistentry>
1097         <varlistentry>
1098           <term><parameter>width</parameter></term>
1099           <listitem><para>
1100 returns the width of the bitmap
1101             </para></listitem>
1102         </varlistentry>
1103         <varlistentry>
1104           <term><parameter>height</parameter></term>
1105           <listitem><para>
1106 returns the height of the bitmap
1107             </para></listitem>
1108         </varlistentry>
1109         <varlistentry>
1110           <term><parameter>datap</parameter></term>
1111           <listitem><para>
1112 returns the parsed bitmap data
1113             </para></listitem>
1114         </varlistentry>
1115         <varlistentry>
1116           <term><parameter>x_hot</parameter></term>
1117           <listitem><para>
1118 returns the x coordinate of the hotspot
1119             </para></listitem>
1120         </varlistentry>
1121         <varlistentry>
1122           <term><parameter>y_hot</parameter></term>
1123           <listitem><para>
1124 returns the y coordinate of the hotspot
1125             </para></listitem>
1126         </varlistentry>
1127       </variablelist>
1128
1129 This function reads a standard bitmap file description from the specified
1130 stream, and returns the parsed data in a format suitable for passing to
1131 <olink targetdoc='libX11' targetptr='XCreateBitmapFromData'><function>XCreateBitmapFromData</function></olink>.
1132 The return value of the function has the same
1133 interpretation as the return value for
1134 <olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>.
1135     </para>
1136
1137     <para id="XmuReadBitmapDataFromFile">
1138       <indexterm zone="XmuReadBitmapDataFromFile">
1139         <primary><function>XmuReadBitmapDataFromFile</function></primary>
1140       </indexterm>
1141       <funcsynopsis>
1142         <funcprototype>
1143           <funcdef>int <function>XmuReadBitmapDataFromFile</function></funcdef>
1144           <paramdef>const char *<parameter>filename</parameter></paramdef>
1145           <paramdef>unsigned int *<parameter>width</parameter></paramdef>
1146           <paramdef>unsigned int *<parameter>height</parameter></paramdef>
1147           <paramdef>unsigned char **<parameter>datap</parameter></paramdef>
1148           <paramdef>int *<parameter>x_hot</parameter></paramdef>
1149           <paramdef>int *<parameter>y_hot</parameter></paramdef>
1150         </funcprototype>
1151       </funcsynopsis>
1152       <variablelist>
1153         <varlistentry>
1154           <term><parameter>fstream</parameter></term>
1155           <listitem><para>
1156 specifies the file to read from
1157             </para></listitem>
1158         </varlistentry>
1159         <varlistentry>
1160           <term><parameter>width</parameter></term>
1161           <listitem><para>
1162 returns the width of the bitmap
1163             </para></listitem>
1164         </varlistentry>
1165         <varlistentry>
1166           <term><parameter>height</parameter></term>
1167           <listitem><para>
1168 returns the height of the bitmap
1169             </para></listitem>
1170         </varlistentry>
1171         <varlistentry>
1172           <term><parameter>datap</parameter></term>
1173           <listitem><para>
1174 returns the parsed bitmap data
1175             </para></listitem>
1176         </varlistentry>
1177         <varlistentry>
1178           <term><parameter>x_hot</parameter></term>
1179           <listitem><para>
1180 returns the x coordinate of the hotspot
1181             </para></listitem>
1182         </varlistentry>
1183         <varlistentry>
1184           <term><parameter>y_hot</parameter></term>
1185           <listitem><para>
1186 returns the y coordinate of the hotspot
1187             </para></listitem>
1188         </varlistentry>
1189       </variablelist>
1190
1191 This function reads a standard bitmap file description from the specified
1192 file, and returns the parsed data in a format suitable for passing to
1193 <olink targetdoc='libX11' targetptr='XCreateBitmapFromData'><function>XCreateBitmapFromData</function></olink>.
1194 The return value of the function has the same
1195 interpretation as the return value for
1196 <olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>.
1197     </para>
1198
1199     <para id="XmuLocateBitmapFile">
1200       <indexterm zone="XmuLocateBitmapFile">
1201         <primary><function>XmuLocateBitmapFile</function></primary>
1202       </indexterm>
1203       <funcsynopsis>
1204         <funcprototype>
1205           <funcdef>Pixmap <function>XmuLocateBitmapFile</function></funcdef>
1206           <paramdef>Screen *<parameter>screen</parameter></paramdef>
1207           <paramdef>const char *<parameter>name</parameter></paramdef>
1208           <paramdef>char *<parameter>srcname</parameter></paramdef>
1209           <paramdef>int <parameter>srcnamelen</parameter></paramdef>
1210           <paramdef>int *<parameter>widthp</parameter></paramdef>
1211           <paramdef>int *<parameter>heightp</parameter></paramdef>
1212           <paramdef>int *<parameter>xhotp</parameter></paramdef>
1213           <paramdef>int *<parameter>yhotp</parameter></paramdef>
1214         </funcprototype>
1215       </funcsynopsis>
1216       <variablelist>
1217         <varlistentry>
1218           <term><parameter>screen</parameter></term>
1219           <listitem><para>
1220 specifies the screen the pixmap is created on
1221             </para></listitem>
1222         </varlistentry>
1223         <varlistentry>
1224           <term><parameter>name</parameter></term>
1225           <listitem><para>
1226 specifies the file to read from
1227             </para></listitem>
1228         </varlistentry>
1229         <varlistentry>
1230           <term><parameter>srcname</parameter></term>
1231           <listitem><para>
1232 returns the full filename of the bitmap
1233             </para></listitem>
1234         </varlistentry>
1235         <varlistentry>
1236           <term><parameter>srcnamelen</parameter></term>
1237           <listitem><para>
1238 specifies the length of the srcname buffer
1239             </para></listitem>
1240         </varlistentry>
1241         <varlistentry>
1242           <term><parameter>width</parameter></term>
1243           <listitem><para>
1244 returns the width of the bitmap
1245             </para></listitem>
1246         </varlistentry>
1247         <varlistentry>
1248           <term><parameter>height</parameter></term>
1249           <listitem><para>
1250 returns the height of the bitmap
1251             </para></listitem>
1252         </varlistentry>
1253         <varlistentry>
1254           <term><parameter>xhotp</parameter></term>
1255           <listitem><para>
1256 returns the x coordinate of the hotspot
1257             </para></listitem>
1258         </varlistentry>
1259         <varlistentry>
1260           <term><parameter>yhotp</parameter></term>
1261           <listitem><para>
1262 returns the y coordinate of the hotspot
1263             </para></listitem>
1264         </varlistentry>
1265       </variablelist>
1266
1267 This function reads a file in standard bitmap file format, using
1268 <olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>,
1269 and returns the created bitmap.  The filename may be
1270 absolute, or relative to the global resource named
1271       <indexterm zone="XmuLocateBitmapFile">
1272         <primary><systemitem class="resource">bitmapFilePath</systemitem></primary>
1273       </indexterm>
1274 <systemitem class="resource">bitmapFilePath</systemitem> with class
1275 BitmapFilePath.  If the resource is not defined, the default value is the
1276 build symbol BITMAPDIR, which is typically
1277 "<filename class="directory">/usr/include/X11/bitmaps</filename>".
1278 If <parameter>srcnamelen</parameter> is greater than zero and
1279 <parameter>srcname</parameter> is not <symbol>NULL</symbol>,
1280 the null terminated filename will be copied into
1281 <parameter>srcname</parameter>.  The size and hotspot of the bitmap are
1282 also returned.
1283     </para>
1284
1285     <para id="XmuCreatePixmapFromBitmap">
1286       <indexterm zone="XmuCreatePixmapFromBitmap">
1287         <primary><function>XmuCreatePixmapFromBitmap</function></primary>
1288       </indexterm>
1289       <funcsynopsis>
1290         <funcprototype>
1291           <funcdef>Pixmap <function>XmuCreatePixmapFromBitmap</function></funcdef>
1292           <paramdef>Display *<parameter>dpy</parameter></paramdef>
1293           <paramdef>Drawable <parameter>d</parameter></paramdef>
1294           <paramdef>Pixmap <parameter>bitmap</parameter></paramdef>
1295           <paramdef>unsigned int <parameter>width</parameter></paramdef>
1296           <paramdef>unsigned int <parameter>height</parameter></paramdef>
1297           <paramdef>unsigned int <parameter>depth</parameter></paramdef>
1298           <paramdef>unsigned long <parameter>fore</parameter></paramdef>
1299           <paramdef>unsigned long <parameter>back</parameter></paramdef>
1300         </funcprototype>
1301       </funcsynopsis>
1302       <variablelist>
1303         <varlistentry>
1304           <term><parameter>dpy</parameter></term>
1305           <listitem><para>
1306 specifies the connection to the X server
1307             </para></listitem>
1308         </varlistentry>
1309         <varlistentry>
1310           <term><parameter>screen</parameter></term>
1311           <listitem><para>
1312 specifies the screen the pixmap is created on
1313             </para></listitem>
1314         </varlistentry>
1315         <varlistentry>
1316           <term><parameter>bitmap</parameter></term>
1317           <listitem><para>
1318 specifies the bitmap source
1319             </para></listitem>
1320         </varlistentry>
1321         <varlistentry>
1322           <term><parameter>width</parameter></term>
1323           <listitem><para>
1324 specifies the width of the pixmap
1325             </para></listitem>
1326         </varlistentry>
1327         <varlistentry>
1328           <term><parameter>height</parameter></term>
1329           <listitem><para>
1330 specifies the height of the pixmap
1331             </para></listitem>
1332         </varlistentry>
1333         <varlistentry>
1334           <term><parameter>depth</parameter></term>
1335           <listitem><para>
1336 specifies the depth of the pixmap
1337             </para></listitem>
1338         </varlistentry>
1339         <varlistentry>
1340           <term><parameter>fore</parameter></term>
1341           <listitem><para>
1342 specifies the foreground pixel value
1343             </para></listitem>
1344         </varlistentry>
1345         <varlistentry>
1346           <term><parameter>back</parameter></term>
1347           <listitem><para>
1348 specifies the background pixel value
1349             </para></listitem>
1350         </varlistentry>
1351       </variablelist>
1352
1353 This function creates a pixmap of the specified width, height, and depth, on
1354 the same screen as the specified drawable, and then performs an
1355 <olink targetdoc='libX11' targetptr='XCopyPlane'><function>XCopyPlane</function></olink>
1356 from the specified bitmap to the pixmap,
1357 using the specified foreground and background pixel values.
1358 The created pixmap is returned.
1359     </para>
1360
1361   </sect1>
1362
1363   <sect1 id='Selection_Functions'>
1364 <title>Selection Functions</title>
1365
1366     <para>
1367 To use the functions defined in this section, you should include the header
1368 file
1369 &lt;<filename class='headerfile'>X11/Xmu/StdSel.h</filename>&gt;
1370 <indexterm>
1371 <primary><filename class='headerfile'>X11/Xmu/StdSel.h</filename></primary>
1372 </indexterm>
1373 and link against the libXmu library.
1374     </para>
1375
1376     <para id="XmuConvertStandardSelection">
1377       <indexterm zone="XmuConvertStandardSelection">
1378         <primary><function>XmuConvertStandardSelection</function></primary>
1379       </indexterm>
1380       <funcsynopsis>
1381         <funcprototype>
1382           <funcdef>Boolean <function>XmuConvertStandardSelection</function></funcdef>
1383           <paramdef>Widget <parameter>w</parameter></paramdef>
1384           <paramdef>Time <parameter>time</parameter></paramdef>
1385           <paramdef>Atom *<parameter>selection</parameter></paramdef>
1386           <paramdef>Atom *<parameter>target</parameter></paramdef>
1387           <paramdef>Atom *<parameter>type</parameter></paramdef>
1388           <paramdef>XPointer <parameter>value</parameter></paramdef>
1389           <paramdef>unsigned long *<parameter>length</parameter></paramdef>
1390           <paramdef>int *<parameter>format</parameter></paramdef>
1391         </funcprototype>
1392       </funcsynopsis>
1393       <variablelist>
1394         <varlistentry>
1395           <term><parameter>w</parameter></term>
1396           <listitem><para>
1397 specifies the widget which currently owns the selection
1398             </para></listitem>
1399         </varlistentry>
1400         <varlistentry>
1401           <term><parameter>time</parameter></term>
1402           <listitem><para>
1403 specifies the time at which the selection was established
1404             </para></listitem>
1405         </varlistentry>
1406         <varlistentry>
1407           <term><parameter>selection</parameter></term>
1408           <listitem><para>
1409 this argument is ignored
1410             </para></listitem>
1411         </varlistentry>
1412         <varlistentry>
1413           <term><parameter>target</parameter></term>
1414           <listitem><para>
1415 specifies the target type of the selection
1416             </para></listitem>
1417         </varlistentry>
1418         <varlistentry>
1419           <term><parameter>type</parameter></term>
1420           <listitem><para>
1421 returns the property type of the converted value
1422             </para></listitem>
1423         </varlistentry>
1424         <varlistentry>
1425           <term><parameter>value</parameter></term>
1426           <listitem><para>
1427 returns the converted value
1428             </para></listitem>
1429         </varlistentry>
1430         <varlistentry>
1431           <term><parameter>length</parameter></term>
1432           <listitem><para>
1433 returns the number of elements in the converted value
1434             </para></listitem>
1435         </varlistentry>
1436         <varlistentry>
1437           <term><parameter>format</parameter></term>
1438           <listitem><para>
1439 returns the size in bits of the elements</para>
1440           </listitem>
1441         </varlistentry>
1442       </variablelist>
1443
1444 This function converts the following standard selections: CLASS,
1445 CLIENT_WINDOW, DECNET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS,
1446 TARGETS, TIMESTAMP, and USER.  It returns
1447 <symbol>True</symbol>
1448 if the conversion was successful, else it returns
1449 <symbol>False</symbol>.
1450     </para>
1451   </sect1>
1452
1453   <sect1 id='Type_Converter_Functions'>
1454 <title>Type Converter Functions</title>
1455
1456     <para>
1457 To use the functions defined in this section, you should include the header
1458 file
1459 &lt;<filename class='headerfile'>X11/Xmu/Converters.h</filename>&gt;
1460 <indexterm>
1461 <primary><filename class='headerfile'>X11/Xmu/Converters.h</filename></primary>
1462 </indexterm>
1463 and link against the libXmu library.
1464     </para>
1465
1466     <para id="XmuCvtFunctionToCallback">
1467       <indexterm zone="XmuCvtFunctionToCallback">
1468         <primary><function>XmuCvtFunctionToCallback</function></primary>
1469       </indexterm>
1470       <funcsynopsis>
1471         <funcprototype>
1472           <funcdef>void <function>XmuCvtFunctionToCallback</function></funcdef>
1473           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1474           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1475           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1476           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1477         </funcprototype>
1478       </funcsynopsis>
1479       <variablelist>
1480         <varlistentry>
1481           <term><parameter>args</parameter></term>
1482           <listitem><para>
1483 this argument is ignored
1484             </para></listitem>
1485         </varlistentry>
1486         <varlistentry>
1487           <term><parameter>num_args</parameter></term>
1488           <listitem><para>
1489 this argument is ignored
1490             </para></listitem>
1491         </varlistentry>
1492         <varlistentry>
1493           <term><parameter>fromVal</parameter></term>
1494           <listitem><para>
1495 the function to convert
1496             </para></listitem>
1497         </varlistentry>
1498         <varlistentry>
1499           <term><parameter>toVal</parameter></term>
1500           <listitem><para>
1501 the place to store the converted value
1502             </para></listitem>
1503         </varlistentry>
1504       </variablelist>
1505
1506 This function converts a callback procedure to a callback list containing
1507 that procedure, with <symbol>NULL</symbol> closure data.  To use this converter, include the
1508 following in your widget's ClassInitialize procedure:
1509
1510       <programlisting>
1511 XtAddConverter(XtRCallProc, XtRCallback, XmuCvtFunctionToCallback, NULL, 0);
1512       </programlisting>
1513     </para>
1514
1515     <para id="XmuCvtStringToBackingStore">
1516       <indexterm zone="XmuCvtStringToBackingStore">
1517         <primary><function>XmuCvtStringToBackingStore</function></primary>
1518       </indexterm>
1519       <funcsynopsis>
1520         <funcprototype>
1521           <funcdef>void <function>XmuCvtStringToBackingStore</function></funcdef>
1522           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1523           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1524           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1525           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1526         </funcprototype>
1527       </funcsynopsis>
1528       <variablelist>
1529         <varlistentry>
1530           <term><parameter>args</parameter></term>
1531           <listitem><para>
1532 this argument is ignored
1533             </para></listitem>
1534         </varlistentry>
1535         <varlistentry>
1536           <term><parameter>num_args</parameter></term>
1537           <listitem><para>
1538 this argument must be a pointer to a Cardinal containing the value 0
1539             </para></listitem>
1540         </varlistentry>
1541         <varlistentry>
1542           <term><parameter>fromVal</parameter></term>
1543           <listitem><para>
1544 specifies the string to convert
1545             </para></listitem>
1546         </varlistentry>
1547         <varlistentry>
1548           <term><parameter>toVal</parameter></term>
1549           <listitem><para>
1550 returns the converted value
1551             </para></listitem>
1552         </varlistentry>
1553       </variablelist>
1554
1555       <indexterm zone="XmuCvtStringToBackingStore">
1556         <primary>backing-store</primary>
1557       </indexterm>
1558 This function converts a string to a backing-store integer as defined in
1559 &lt;<filename class='headerfile'>X11/X.h</filename>&gt;.
1560 The string "notUseful" converts to
1561 <symbol>NotUseful</symbol>,
1562 "whenMapped" converts to
1563 <symbol>WhenMapped</symbol>,
1564 and "always" converts to
1565 <symbol>Always</symbol>.
1566 The string "default" converts to the value
1567 <symbol>Always</symbol> +
1568 <symbol>WhenMapped</symbol> +
1569 <symbol>NotUseful</symbol>.
1570 The case of the string does not matter.
1571 To use this converter, include the following
1572 in your widget's ClassInitialize procedure:
1573
1574       <programlisting>
1575 XtAddConverter(XtRString, XtRBackingStore, XmuCvtStringToBackingStore, NULL, 0);
1576       </programlisting>
1577     </para>
1578
1579     <para id="XmuCvtStringToBitmap">
1580       <indexterm zone="XmuCvtStringToBitmap">
1581         <primary><function>XmuCvtStringToBitmap</function></primary>
1582       </indexterm>
1583       <funcsynopsis>
1584         <funcprototype>
1585           <funcdef>void <function>XmuCvtStringToBitmap</function></funcdef>
1586           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1587           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1588           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1589           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1590         </funcprototype>
1591       </funcsynopsis>
1592       <variablelist>
1593         <varlistentry>
1594           <term><parameter>args</parameter></term>
1595           <listitem><para>
1596 the sole argument specifies the Screen on which to create the bitmap
1597             </para></listitem>
1598         </varlistentry>
1599         <varlistentry>
1600           <term><parameter>num_args</parameter></term>
1601           <listitem><para>
1602 must be the value 1
1603             </para></listitem>
1604         </varlistentry>
1605         <varlistentry>
1606           <term><parameter>fromVal</parameter></term>
1607           <listitem><para>
1608 specifies the string to convert
1609             </para></listitem>
1610         </varlistentry>
1611         <varlistentry>
1612           <term><parameter>toVal</parameter></term>
1613           <listitem><para>
1614 returns the converted value
1615             </para></listitem>
1616         </varlistentry>
1617       </variablelist>
1618
1619       <indexterm zone="XmuCvtStringToBitmap">
1620         <primary>window manager icons</primary>
1621       </indexterm>
1622 This function creates a bitmap (a Pixmap of depth one) suitable for window
1623 manager icons.  The string argument is the name of a file in standard bitmap
1624 file format.  For the possible filename specifications, see
1625 <link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>.
1626 To use this converter, include the following in your widget's
1627 ClassInitialize procedure:
1628
1629       <programlisting>
1630 static XtConvertArgRec screenConvertArg[] = {
1631   {XtBaseOffset, (XtPointer)XtOffset(Widget, core.screen), sizeof(Screen *)}
1632 };
1633
1634 XtAddConverter(XtRString, XtRBitmap, XmuCvtStringToBitmap,
1635                  screenConvertArg, XtNumber(screenConvertArg));
1636       </programlisting>
1637     </para>
1638
1639     <para id="XmuCvtStringToColorCursor">
1640       <indexterm zone="XmuCvtStringToColorCursor">
1641         <primary><function>XmuCvtStringToColorCursor</function></primary>
1642       </indexterm>
1643       <funcsynopsis>
1644         <funcprototype>
1645           <funcdef>Boolean <function>XmuCvtStringToColorCursor</function></funcdef>
1646           <paramdef>Display *<parameter>dpy</parameter></paramdef>
1647           <paramdef>XrmValuePtr <parameter>args</parameter></paramdef>
1648           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1649           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1650           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1651           <paramdef>XtPointer *<parameter>data</parameter></paramdef>
1652         </funcprototype>
1653       </funcsynopsis>
1654       <variablelist>
1655         <varlistentry>
1656           <term><parameter>dpy</parameter></term>
1657           <listitem><para>
1658 specifies the display to use for conversion warnings
1659             </para></listitem>
1660         </varlistentry>
1661         <varlistentry>
1662           <term><parameter>args</parameter></term>
1663           <listitem><para>
1664 specifies the required conversion arguments
1665             </para></listitem>
1666         </varlistentry>
1667         <varlistentry>
1668           <term><parameter>num_args</parameter></term>
1669           <listitem><para>
1670 specifies the number of required conversion arguments, which is 4
1671             </para></listitem>
1672         </varlistentry>
1673         <varlistentry>
1674           <term><parameter>fromVal</parameter></term>
1675           <listitem><para>
1676 specifies the string to convert
1677             </para></listitem>
1678         </varlistentry>
1679         <varlistentry>
1680           <term><parameter>toVal</parameter></term>
1681           <listitem><para>
1682 returns the converted value
1683             </para></listitem>
1684         </varlistentry>
1685         <varlistentry>
1686           <term><parameter>data</parameter></term>
1687           <listitem><para>
1688 this argument is ignored
1689             </para></listitem>
1690         </varlistentry>
1691       </variablelist>
1692
1693       <indexterm zone="XmuCvtStringToColorCursor">
1694         <primary><type>Cursor</type></primary>
1695       </indexterm>
1696 This function converts a string to a
1697 <type>Cursor</type>
1698 with the foreground and background pixels specified by the conversion
1699 arguments.  The string can either be a
1700 standard cursor name formed by removing the <code>&ldquo;XC_&rdquo;</code>
1701 prefix from any of the
1702 cursor defines listed in Appendix B of the Xlib Manual, a font name and
1703 glyph index in decimal of the form "FONT fontname index [[font] index]",
1704 or a bitmap filename acceptable to
1705 <link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>.
1706 To use this converter, include
1707 the following in the widget ClassInitialize procedure:
1708
1709       <programlisting>
1710 static XtConvertArgRec colorCursorConvertArgs[] = {
1711   {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.screen),
1712    sizeof(Screen *)},
1713   {XtResourceString, (XtPointer) XtNpointerColor, sizeof(Pixel)},
1714   {XtResourceString, (XtPointer) XtNpointerColorBackground, sizeof(Pixel)},
1715   {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.colormap),
1716    sizeof(Colormap)}
1717 };
1718
1719
1720 XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor,
1721                  colorCursorConvertArgs, XtNumber(colorCursorConvertArgs),
1722                  XtCacheByDisplay, NULL);
1723       </programlisting>
1724
1725 The widget must recognize XtNpointerColor and XtNpointerColorBackground as
1726 resources, or specify other appropriate foreground and background resources.
1727 The widget's Realize and SetValues methods must cause the converter to be
1728 invoked with the appropriate arguments when one of the foreground,
1729 background, or cursor resources has changed, or when the window is created,
1730 and must assign the cursor to the window of the widget.
1731     </para>
1732
1733     <para id="XmuCvtStringToCursor">
1734       <indexterm zone="XmuCvtStringToCursor">
1735         <primary><function>XmuCvtStringToCursor</function></primary>
1736       </indexterm>
1737       <funcsynopsis>
1738         <funcprototype>
1739           <funcdef>void <function>XmuCvtStringToCursor</function></funcdef>
1740           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1741           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1742           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1743           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1744         </funcprototype>
1745       </funcsynopsis>
1746       <variablelist>
1747         <varlistentry>
1748           <term><parameter>args</parameter></term>
1749           <listitem><para>
1750 specifies the required conversion argument, the screen
1751             </para></listitem>
1752         </varlistentry>
1753         <varlistentry>
1754           <term><parameter>num_args</parameter></term>
1755           <listitem><para>
1756 specifies the number of required conversion arguments, which is 1
1757             </para></listitem>
1758         </varlistentry>
1759         <varlistentry>
1760           <term><parameter>fromVal</parameter></term>
1761           <listitem><para>
1762 specifies the string to convert
1763             </para></listitem>
1764         </varlistentry>
1765         <varlistentry>
1766           <term><parameter>toVal</parameter></term>
1767           <listitem><para>
1768 returns the converted value
1769             </para></listitem>
1770         </varlistentry>
1771       </variablelist>
1772
1773       <indexterm zone="XmuCvtStringToCursor">
1774         <primary><type>Cursor</type></primary>
1775       </indexterm>
1776 This function converts a string to a
1777 <type>Cursor</type>.
1778 The string can either be a
1779 standard cursor name formed by removing the <code>&ldquo;XC_&rdquo;</code>
1780 prefix from any of the
1781 cursor defines listed in Appendix B of the Xlib Manual, a font name and
1782 glyph index in decimal of the form "FONT fontname index [[font] index]", or
1783 a bitmap filename acceptable to
1784 <link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>.
1785 To use this converter, include
1786 the following in your widget's ClassInitialize procedure:
1787
1788       <programlisting>
1789 static XtConvertArgRec screenConvertArg[] = {
1790   {XtBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.screen), sizeof(Screen *)}
1791 };
1792
1793 XtAddConverter(XtRString, XtRCursor, XmuCvtStringToCursor,
1794                  screenConvertArg, XtNumber(screenConvertArg));
1795       </programlisting>
1796     </para>
1797
1798     <para id="XmuCvtStringToGravity">
1799       <indexterm zone="XmuCvtStringToGravity">
1800         <primary><function>XmuCvtStringToGravity</function></primary>
1801       </indexterm>
1802       <funcsynopsis>
1803         <funcprototype>
1804           <funcdef>void <function>XmuCvtStringToGravity</function></funcdef>
1805           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1806           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1807           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1808           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1809         </funcprototype>
1810       </funcsynopsis>
1811       <variablelist>
1812         <varlistentry>
1813           <term><parameter>args</parameter></term>
1814           <listitem><para>
1815 this argument is ignored
1816             </para></listitem>
1817         </varlistentry>
1818         <varlistentry>
1819           <term><parameter>num_args</parameter></term>
1820           <listitem><para>
1821 this argument must be a pointer to a Cardinal containing the value 0
1822             </para></listitem>
1823         </varlistentry>
1824         <varlistentry>
1825           <term><parameter>fromVal</parameter></term>
1826           <listitem><para>
1827 specifies the string to convert
1828             </para></listitem>
1829         </varlistentry>
1830         <varlistentry>
1831           <term><parameter>toVal</parameter></term>
1832           <listitem><para>
1833 returns the converted value
1834             </para></listitem>
1835         </varlistentry>
1836       </variablelist>
1837
1838       <indexterm zone="XmuCvtStringToGravity">
1839         <primary><type>XtGravity</type></primary>
1840       </indexterm>
1841 This function converts a string to an
1842 <type>XtGravity</type>
1843 enumeration value.  The string "forget" and a <symbol>NULL</symbol> value convert to
1844 <symbol>ForgetGravity</symbol>,
1845 "NorthWestGravity" converts to
1846 <symbol>NorthWestGravity</symbol>,
1847 the strings "NorthGravity" and "top" convert to
1848 <symbol>NorthGravity</symbol>,
1849 "NorthEastGravity" converts to
1850 <symbol>NorthEastGravity</symbol>,
1851 the strings "West" and "left" convert to
1852 <symbol>WestGravity</symbol>,
1853 "CenterGravity" converts to
1854 <symbol>CenterGravity</symbol>,
1855 "EastGravity" and "right" convert to
1856 <symbol>EastGravity</symbol>,
1857 "SouthWestGravity" converts to
1858 <symbol>SouthWestGravity</symbol>,
1859 "SouthGravity" and "bottom" convert to
1860 <symbol>SouthGravity</symbol>,
1861 "SouthEastGravity" converts to
1862 <symbol>SouthEastGravity</symbol>,
1863 "StaticGravity" converts to
1864 <symbol>StaticGravity</symbol>,
1865 and "UnmapGravity" converts to
1866 <symbol>UnmapGravity</symbol>.
1867 The case of the string does not matter.  To use this converter, include
1868 the following in your widget's class initialize procedure:
1869
1870       <programlisting>
1871 XtAddConverter(XtRString, XtRGravity, XmuCvtStringToGravity, NULL, 0);
1872       </programlisting>
1873     </para>
1874
1875     <para id="XmuCvtStringToJustify">
1876       <indexterm zone="XmuCvtStringToJustify">
1877         <primary><function>XmuCvtStringToJustify</function></primary>
1878       </indexterm>
1879       <funcsynopsis>
1880         <funcprototype>
1881           <funcdef>void <function>XmuCvtStringToJustify</function></funcdef>
1882           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1883           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1884           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1885           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1886         </funcprototype>
1887       </funcsynopsis>
1888       <variablelist>
1889         <varlistentry>
1890           <term><parameter>args</parameter></term>
1891           <listitem><para>
1892 this argument is ignored
1893             </para></listitem>
1894         </varlistentry>
1895         <varlistentry>
1896           <term><parameter>num_args</parameter></term>
1897           <listitem><para>
1898 this argument is ignored
1899             </para></listitem>
1900         </varlistentry>
1901         <varlistentry>
1902           <term><parameter>fromVal</parameter></term>
1903           <listitem><para>
1904 specifies the string to convert
1905             </para></listitem>
1906         </varlistentry>
1907         <varlistentry>
1908           <term><parameter>toVal</parameter></term>
1909           <listitem><para>
1910 returns the converted value
1911             </para></listitem>
1912         </varlistentry>
1913       </variablelist>
1914
1915       <indexterm zone="XmuCvtStringToJustify">
1916         <primary><type>XtJustify</type></primary>
1917       </indexterm>
1918 This function converts a string to an
1919 <type>XtJustify</type>
1920 enumeration value.  The string "left" converts to
1921 <symbol>XtJustifyLeft</symbol>,
1922 "center" converts to
1923 <symbol>XtJustifyCenter</symbol>,
1924 and "right" converts to
1925 <symbol>XtJustifyRight</symbol>.
1926 The case of the string does not matter.  To use this converter,
1927 include the following in your widget's ClassInitialize procedure:
1928
1929       <programlisting>
1930 XtAddConverter(XtRString, XtRJustify, XmuCvtStringToJustify, NULL, 0);
1931       </programlisting>
1932     </para>
1933
1934     <para id="XmuCvtStringToLong">
1935       <indexterm zone="XmuCvtStringToLong">
1936         <primary><function>XmuCvtStringToLong</function></primary>
1937       </indexterm>
1938       <funcsynopsis>
1939         <funcprototype>
1940           <funcdef>void <function>XmuCvtStringToLong</function></funcdef>
1941           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1942           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1943           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1944           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1945         </funcprototype>
1946       </funcsynopsis>
1947       <variablelist>
1948         <varlistentry>
1949           <term><parameter>args</parameter></term>
1950           <listitem><para>
1951 this argument is ignored
1952             </para></listitem>
1953         </varlistentry>
1954         <varlistentry>
1955           <term><parameter>num_args</parameter></term>
1956           <listitem><para>
1957 this argument must be a pointer to a Cardinal containing 0
1958             </para></listitem>
1959         </varlistentry>
1960         <varlistentry>
1961           <term><parameter>fromVal</parameter></term>
1962           <listitem><para>
1963 specifies the string to convert
1964             </para></listitem>
1965         </varlistentry>
1966         <varlistentry>
1967           <term><parameter>toVal</parameter></term>
1968           <listitem><para>
1969 returns the converted value
1970             </para></listitem>
1971         </varlistentry>
1972       </variablelist>
1973
1974 This function converts a string to an integer of type long.  It parses the
1975 string using
1976 <function>sscanf</function>
1977 with a format of "%ld".  To use this converter, include
1978 the following in your widget's ClassInitialize procedure:
1979
1980       <programlisting>
1981 XtAddConverter(XtRString, XtRLong, XmuCvtStringToLong, NULL, 0);
1982       </programlisting>
1983     </para>
1984
1985     <para id="XmuCvtStringToOrientation">
1986       <indexterm zone="XmuCvtStringToOrientation">
1987         <primary><function>XmuCvtStringToOrientation</function></primary>
1988       </indexterm>
1989       <funcsynopsis>
1990         <funcprototype>
1991           <funcdef>void <function>XmuCvtStringToOrientation</function></funcdef>
1992           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
1993           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
1994           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
1995           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
1996         </funcprototype>
1997       </funcsynopsis>
1998       <variablelist>
1999         <varlistentry>
2000           <term><parameter>args</parameter></term>
2001           <listitem><para>
2002 this argument is ignored
2003             </para></listitem>
2004         </varlistentry>
2005         <varlistentry>
2006           <term><parameter>num_args</parameter></term>
2007           <listitem><para>
2008 this argument is ignored
2009             </para></listitem>
2010         </varlistentry>
2011         <varlistentry>
2012           <term><parameter>fromVal</parameter></term>
2013           <listitem><para>
2014 specifies the string to convert
2015             </para></listitem>
2016         </varlistentry>
2017         <varlistentry>
2018           <term><parameter>toVal</parameter></term>
2019           <listitem><para>
2020 returns the converted value
2021             </para></listitem>
2022         </varlistentry>
2023       </variablelist>
2024
2025       <indexterm zone="XmuCvtStringToOrientation">
2026         <primary><type>XtOrientation</type></primary>
2027       </indexterm>
2028 This function converts a string to an
2029 <type>XtOrientation</type>
2030 enumeration value.  The string "horizontal" converts to
2031 <symbol>XtorientHorizontal</symbol>
2032 and "vertical" converts to
2033 <symbol>XtorientVertical</symbol>.
2034 The case of the string does not matter.  To use this converter,
2035 include the following in your widget's ClassInitialize procedure:
2036
2037       <programlisting>
2038 XtAddConverter(XtRString, XtROrientation, XmuCvtStringToOrientation, NULL, 0);
2039       </programlisting>
2040     </para>
2041
2042     <para id="XmuCvtStringToShapeStyle">
2043       <indexterm zone="XmuCvtStringToShapeStyle">
2044         <primary><function>XmuCvtStringToShapeStyle</function></primary>
2045       </indexterm>
2046       <funcsynopsis>
2047         <funcprototype>
2048           <funcdef>Boolean <function>XmuCvtStringToShapeStyle</function></funcdef>
2049           <paramdef>Display *<parameter>dpy</parameter></paramdef>
2050           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
2051           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
2052           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
2053           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
2054           <paramdef>XtPointer *<parameter>data</parameter></paramdef>
2055         </funcprototype>
2056       </funcsynopsis>
2057       <variablelist>
2058         <varlistentry>
2059           <term><parameter>dpy</parameter></term>
2060           <listitem><para>
2061 the display to use for conversion warnings
2062             </para></listitem>
2063         </varlistentry>
2064         <varlistentry>
2065           <term><parameter>args</parameter></term>
2066           <listitem><para>
2067 this argument is ignored
2068             </para></listitem>
2069         </varlistentry>
2070         <varlistentry>
2071           <term><parameter>num_args</parameter></term>
2072           <listitem><para>
2073 this argument is ignored
2074             </para></listitem>
2075         </varlistentry>
2076         <varlistentry>
2077           <term><parameter>fromVal</parameter></term>
2078           <listitem><para>
2079 the value to convert from
2080             </para></listitem>
2081         </varlistentry>
2082         <varlistentry>
2083           <term><parameter>toVal</parameter></term>
2084           <listitem><para>
2085 the place to store the converted value
2086             </para></listitem>
2087         </varlistentry>
2088         <varlistentry>
2089           <term><parameter>data</parameter></term>
2090           <listitem><para>
2091 this argument is ignored
2092             </para></listitem>
2093         </varlistentry>
2094       </variablelist>
2095
2096 This function converts a string to an integer shape style.  The string
2097 "rectangle" converts to
2098 <symbol>XmuShapeRectangle</symbol>,
2099 "oval" converts to
2100 <symbol>XmuShapeOval</symbol>,
2101 "ellipse" converts to
2102 <symbol>XmuShapeEllipse</symbol>,
2103 and "roundedRectangle" converts to
2104 <symbol>XmuShapeRoundedRectangle</symbol>.
2105 The case of the string does not matter.  To use this converter,
2106 include the following in your widget's ClassInitialize procedure:
2107
2108       <programlisting>
2109 XtSetTypeConverter(XtRString, XtRShapeStyle, XmuCvtStringToShapeStyle,
2110                      NULL, 0, XtCacheNone, NULL);
2111       </programlisting>
2112     </para>
2113
2114     <para id="XmuReshapeWidget">
2115       <indexterm zone="XmuReshapeWidget">
2116         <primary><function>XmuReshapeWidget</function></primary>
2117       </indexterm>
2118       <funcsynopsis>
2119         <funcprototype>
2120           <funcdef>Boolean <function>XmuReshapeWidget</function></funcdef>
2121           <paramdef>Widget <parameter>w</parameter></paramdef>
2122           <paramdef>int <parameter>shape_style</parameter></paramdef>
2123           <paramdef>int <parameter>corner_width</parameter></paramdef>
2124           <paramdef>int <parameter>corner_height</parameter></paramdef>
2125         </funcprototype>
2126       </funcsynopsis>
2127       <variablelist>
2128         <varlistentry>
2129           <term><parameter>w</parameter></term>
2130           <listitem><para>
2131 specifies the widget to reshape
2132             </para></listitem>
2133         </varlistentry>
2134         <varlistentry>
2135           <term><parameter>shape_style</parameter></term>
2136           <listitem><para>
2137 specifies the new shape
2138             </para></listitem>
2139         </varlistentry>
2140         <varlistentry>
2141           <term><parameter>corner_width</parameter></term>
2142           <listitem><para>
2143 specifies the width of the rounded rectangle corner
2144             </para></listitem>
2145         </varlistentry>
2146         <varlistentry>
2147           <term><parameter>corner_height</parameter></term>
2148           <listitem><para>
2149 specified the height of the rounded rectangle corner
2150             </para></listitem>
2151         </varlistentry>
2152       </variablelist>
2153
2154       <indexterm zone="XmuReshapeWidget">
2155         <primary>Shape extension</primary>
2156       </indexterm>
2157 This function reshapes the specified widget, using the Shape extension, to a
2158 rectangle, oval, ellipse, or rounded rectangle, as specified by shape_style
2159 (
2160 <symbol>XmuShapeRectangle</symbol>,
2161 <symbol>XmuShapeOval</symbol>,
2162 <symbol>XmuShapeEllipse</symbol>,
2163 and
2164 <symbol>XmuShapeRoundedRectangle</symbol>,
2165 respectively).
2166 The shape is bounded by the outside edges of the rectangular extents of the
2167 widget.  If the shape is a rounded rectangle, corner_width and corner_height
2168 specify the size of the bounding box that the corners are drawn inside of
2169 (see
2170 <link linkend="XmuFillRoundedRectangle"><function>XmuFillRoundedRectangle</function></link>);
2171 otherwise, corner_width and corner_height are ignored.
2172 The origin of the widget within its parent remains unchanged.
2173     </para>
2174
2175     <para id="XmuCvtStringToWidget">
2176       <indexterm zone="XmuCvtStringToWidget">
2177         <primary><function>XmuCvtStringToWidget</function></primary>
2178       </indexterm>
2179       <funcsynopsis>
2180         <funcprototype>
2181           <funcdef>void <function>XmuCvtStringToWidget</function></funcdef>
2182           <paramdef>XrmValue *<parameter>args</parameter></paramdef>
2183           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
2184           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
2185           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
2186         </funcprototype>
2187       </funcsynopsis>
2188       <variablelist>
2189         <varlistentry>
2190           <term><parameter>args</parameter></term>
2191           <listitem><para>
2192 the sole argument is the parent Widget
2193             </para></listitem>
2194         </varlistentry>
2195         <varlistentry>
2196           <term><parameter>num_args</parameter></term>
2197   <listitem><para>
2198 this argument must be 1
2199             </para></listitem>
2200         </varlistentry>
2201         <varlistentry>
2202           <term><parameter>fromVal</parameter></term>
2203   <listitem><para>
2204 specifies the string to convert
2205             </para></listitem>
2206         </varlistentry>
2207         <varlistentry>
2208           <term><parameter>toVal</parameter></term>
2209           <listitem><para>
2210 returns the converted value
2211             </para></listitem>
2212         </varlistentry>
2213       </variablelist>
2214
2215 This function converts a string to an immediate child widget of the parent
2216 widget passed as an argument.  Note that this converter only works for
2217 child widgets that have already been created; there is no lazy evaluation.
2218 The string is first compared against the
2219 names of the normal and popup children, and if a match is found the
2220 corresponding child is returned.  If no match is found, the string is
2221 compared against the classes of the normal and popup children, and if a
2222 match is found the corresponding child is returned.  The case of the string
2223 is significant.  To use this converter, include the following in your
2224 widget's ClassInitialize procedure:
2225
2226       <programlisting>
2227 static XtConvertArgRec parentCvtArg[] = {
2228   {XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)},
2229 };
2230
2231 XtAddConverter(XtRString, XtRWidget, XmuCvtStringToWidget,
2232                  parentCvtArg, XtNumber(parentCvtArg));
2233       </programlisting>
2234     </para>
2235
2236     <para id="XmuNewCvtStringToWidget">
2237       <indexterm zone="XmuNewCvtStringToWidget">
2238         <primary><function>XmuNewCvtStringToWidget</function></primary>
2239       </indexterm>
2240       <funcsynopsis>
2241         <funcprototype>
2242           <funcdef>Boolean <function>XmuNewCvtStringToWidget</function></funcdef>
2243           <paramdef>Display *<parameter>dpy</parameter></paramdef>
2244           <paramdef>XrmValuePtr <parameter>args</parameter></paramdef>
2245           <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
2246           <paramdef>XrmValuePtr <parameter>fromVal</parameter></paramdef>
2247           <paramdef>XrmValuePtr <parameter>toVal</parameter></paramdef>
2248           <paramdef>XtPointer *<parameter>data</parameter></paramdef>
2249         </funcprototype>
2250       </funcsynopsis>
2251       <variablelist>
2252         <varlistentry>
2253           <term><parameter>dpy</parameter></term>
2254           <listitem><para>
2255 the display to use for conversion warnings
2256             </para></listitem>
2257         </varlistentry>
2258         <varlistentry>
2259           <term><parameter>args</parameter></term>
2260           <listitem><para>
2261 the sole argument is the parent Widget
2262             </para></listitem>
2263         </varlistentry>
2264         <varlistentry>
2265           <term><parameter>num_args</parameter></term>
2266           <listitem><para>
2267 this argument must be a pointer to a Cardinal containing the value 1
2268             </para></listitem>
2269         </varlistentry>
2270         <varlistentry>
2271           <term><parameter>fromVal</parameter></term>
2272           <listitem><para>
2273 specifies the string to convert
2274             </para></listitem>
2275         </varlistentry>
2276         <varlistentry>
2277           <term><parameter>toVal</parameter></term>
2278           <listitem><para>
2279 returns the converted value
2280             </para></listitem>
2281         </varlistentry>
2282         <varlistentry>
2283           <term><parameter>data</parameter></term>
2284           <listitem><para>
2285 this argument is ignored
2286             </para></listitem>
2287         </varlistentry>
2288       </variablelist>
2289
2290 This converter is identical in functionality to
2291 <link linkend="XmuCvtStringToWidget"><function>XmuCvtStringToWidget</function></link>, except
2292 that it is a new-style converter, allowing the specification of a cache type
2293 at the time of registration.
2294 Most widgets will not cache the conversion results, as the application may
2295 dynamically create and destroy widgets, which would cause cached values to
2296 become illegal.  To use this converter, include the following in the widget's
2297 class initialize procedure:
2298
2299     <programlisting>
2300 static XtConvertArgRec parentCvtArg[] = {
2301   {XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.parent),
2302    sizeof(Widget)}
2303 };
2304
2305 XtSetTypeConverter(XtRString, XtRWidget, XmuNewCvtStringToWidget,
2306                    parentCvtArg, XtNumber(parentCvtArg), XtCacheNone, NULL);
2307       </programlisting>
2308
2309     </para>
2310
2311   </sect1>
2312
2313   <sect1 id='Character_Set_Functions'>
2314 <title>Character Set Functions</title>
2315
2316 <para>
2317 To use the functions defined in this section, you should include the header
2318 file
2319 &lt;<filename class='headerfile'>X11/Xmu/CharSet.h</filename>&gt;
2320 <indexterm>
2321 <primary><filename class='headerfile'>X11/Xmu/CharSet.h</filename></primary>
2322 </indexterm>
2323 and link against the libXmu or libXmuu library.
2324 </para>
2325
2326     <warning><para>
2327 The functions in this section are <emphasis remap='B'>deprecated</emphasis>
2328 because they don't work in most locales now supported by X11; most platforms
2329 provide alternatives in their system libraries.
2330       </para></warning>
2331
2332     <para id="XmuCopyISOLatin1Lowered">
2333       <indexterm zone="XmuCopyISOLatin1Lowered">
2334         <primary><function>XmuCopyISOLatin1Lowered</function></primary>
2335       </indexterm>
2336       <funcsynopsis>
2337         <funcprototype>
2338           <funcdef>void <function>XmuCopyISOLatin1Lowered</function></funcdef>
2339           <paramdef>char *<parameter>dst</parameter></paramdef>
2340           <paramdef>const char *<parameter>src</parameter></paramdef>
2341         </funcprototype>
2342       </funcsynopsis>
2343       <variablelist>
2344         <varlistentry>
2345           <term><parameter>dst</parameter></term>
2346           <listitem><para>
2347 returns the string copy
2348             </para></listitem>
2349         </varlistentry>
2350         <varlistentry>
2351           <term><parameter>src</parameter></term>
2352           <listitem><para>
2353 specifies the string to copy
2354             </para></listitem>
2355         </varlistentry>
2356       </variablelist>
2357
2358 This function copies a null terminated string from src to dst (including the
2359 null), changing all Latin-1 uppercase letters to lowercase.  The string is
2360 assumed to be encoded using ISO 8859-1.
2361     </para>
2362
2363     <para>
2364 Note that like <function>strcpy</function> the caller is responsible for
2365 ensuring the size of <parameter>dst</parameter> is at least as large as the
2366 size of <parameter>src</parameter>.
2367     </para>
2368
2369     <para id="XmuNCopyISOLatin1Lowered">
2370       <indexterm zone="XmuNCopyISOLatin1Lowered">
2371         <primary><function>XmuNCopyISOLatin1Lowered</function></primary>
2372       </indexterm>
2373       <funcsynopsis>
2374         <funcprototype>
2375           <funcdef>void <function>XmuNCopyISOLatin1Lowered</function></funcdef>
2376           <paramdef>char *<parameter>dst</parameter></paramdef>
2377           <paramdef>const char *<parameter>src</parameter></paramdef>
2378           <paramdef>int <parameter>size</parameter></paramdef>
2379         </funcprototype>
2380       </funcsynopsis>
2381       <variablelist>
2382         <varlistentry>
2383           <term><parameter>dst</parameter></term>
2384           <listitem><para>
2385 returns the string copy
2386             </para></listitem>
2387         </varlistentry>
2388         <varlistentry>
2389           <term><parameter>src</parameter></term>
2390           <listitem><para>
2391 specifies the string to copy
2392             </para></listitem>
2393         </varlistentry>
2394         <varlistentry>
2395           <term><parameter>size</parameter></term>
2396           <listitem><para>
2397 maximum number of characters (including the null terminator) to write to dst
2398             </para></listitem>
2399         </varlistentry>
2400       </variablelist>
2401
2402 This function copies up to <code><parameter>size</parameter> - 1</code>
2403 characters of a null terminated string from <parameter>src</parameter>
2404 to <parameter>dst</parameter>, and terminates it with a null,
2405 changing all Latin-1 uppercase letters to lowercase.  The string is
2406 assumed to be encoded using ISO 8859-1.
2407     </para>
2408
2409     <para id="XmuCopyISOLatin1Uppered">
2410       <indexterm zone="XmuCopyISOLatin1Uppered">
2411         <primary><function>XmuCopyISOLatin1Uppered</function></primary>
2412       </indexterm>
2413       <funcsynopsis>
2414         <funcprototype>
2415           <funcdef>void <function>XmuCopyISOLatin1Uppered</function></funcdef>
2416           <paramdef>char *<parameter>dst</parameter></paramdef>
2417           <paramdef>const char *<parameter>src</parameter></paramdef>
2418         </funcprototype>
2419       </funcsynopsis>
2420       <variablelist>
2421         <varlistentry>
2422           <term><parameter>dst</parameter></term>
2423           <listitem><para>
2424 returns the string copy
2425             </para></listitem>
2426         </varlistentry>
2427         <varlistentry>
2428           <term><parameter>src</parameter></term>
2429           <listitem><para>
2430 specifies the string to copy
2431             </para></listitem>
2432         </varlistentry>
2433       </variablelist>
2434
2435 This function copies a null terminated string from src to dst (including the
2436 null), changing all Latin-1 lowercase letters to uppercase.  The string is
2437 assumed to be encoded using ISO 8859-1.
2438     </para>
2439
2440     <para>
2441 Note that like <function>strcpy</function> the caller is responsible for
2442 ensuring the size of <parameter>dst</parameter> is at least as large as the
2443 size of <parameter>src</parameter>.
2444     </para>
2445
2446     <para id="XmuNCopyISOLatin1Uppered">
2447       <indexterm zone="XmuNCopyISOLatin1Uppered">
2448         <primary><function>XmuNCopyISOLatin1Uppered</function></primary>
2449       </indexterm>
2450       <funcsynopsis>
2451         <funcprototype>
2452           <funcdef>void <function>XmuNCopyISOLatin1Uppered</function></funcdef>
2453           <paramdef>char *<parameter>dst</parameter></paramdef>
2454           <paramdef>const char *<parameter>src</parameter></paramdef>
2455           <paramdef>int <parameter>size</parameter></paramdef>
2456         </funcprototype>
2457       </funcsynopsis>
2458       <variablelist>
2459         <varlistentry>
2460           <term><parameter>dst</parameter></term>
2461           <listitem><para>
2462 returns the string copy
2463             </para></listitem>
2464         </varlistentry>
2465         <varlistentry>
2466           <term><parameter>src</parameter></term>
2467           <listitem><para>
2468 specifies the string to copy
2469             </para></listitem>
2470         </varlistentry>
2471         <varlistentry>
2472           <term><parameter>size</parameter></term>
2473           <listitem><para>
2474 maximum number of characters (including the null terminator) to write to dst
2475             </para></listitem>
2476         </varlistentry>
2477       </variablelist>
2478
2479 This function copies up to <code><parameter>size</parameter> - 1</code>
2480 characters of a null terminated string from <parameter>src</parameter>
2481 to <parameter>dst</parameter>, and terminates it with a null,
2482 changing all Latin-1 lowercase letters to uppercase.  The string is
2483 assumed to be encoded using ISO 8859-1.
2484     </para>
2485
2486     <para id="XmuCompareISOLatin1">
2487       <indexterm zone="XmuCompareISOLatin1">
2488         <primary><function>XmuCompareISOLatin1</function></primary>
2489       </indexterm>
2490       <funcsynopsis>
2491         <funcprototype>
2492           <funcdef>int <function>XmuCompareISOLatin1</function></funcdef>
2493           <paramdef>const char *<parameter>first</parameter></paramdef>
2494           <paramdef>const char *<parameter>second</parameter></paramdef>
2495         </funcprototype>
2496       </funcsynopsis>
2497       <variablelist>
2498         <varlistentry>
2499           <term><parameter>first</parameter></term>
2500           <listitem><para>
2501               specifies a string to compare
2502             </para></listitem>
2503         </varlistentry>
2504         <varlistentry>
2505           <term><parameter>second</parameter></term>
2506           <listitem><para>
2507 specifies a string to compare
2508             </para></listitem>
2509         </varlistentry>
2510       </variablelist>
2511
2512 This function compares two null terminated Latin-1 strings, ignoring case
2513 differences, and returns an integer greater than, equal to, or less than 0,
2514 according to whether first is lexicographically greater than, equal to, or
2515 less than second.  The two strings are assumed to be encoded using ISO
2516 8859-1.
2517     </para>
2518   </sect1>
2519
2520   <sect1 id='Keyboard_Event_Translation_Functions'>
2521 <title>Keyboard Event Translation Functions</title>
2522
2523     <para>
2524 To use the functions defined in this section, you should include the header
2525 file
2526 &lt;<filename class='headerfile'>X11/Xmu/Lookup.h</filename>&gt;
2527 <indexterm>
2528 <primary><filename class='headerfile'>X11/Xmu/Lookup.h</filename></primary>
2529 </indexterm>.
2530 and link against the libXmu library.
2531     </para>
2532
2533     <warning><para>
2534 The functions in this section are <emphasis remap='B'>deprecated</emphasis> because they don't work
2535 in most locales now supported by X11; the function
2536 <olink targetdoc='libX11' targetptr='XmbLookupString'><function>XmbLookupString</function></olink>
2537 provides a better alternative.
2538       </para></warning>
2539
2540     <para id="XmuLookupLatin1">
2541       <indexterm zone="XmuLookupLatin1">
2542         <primary><function>XmuLookupLatin1</function></primary>
2543       </indexterm>
2544       <funcsynopsis>
2545         <funcprototype>
2546           <funcdef>int <function>XmuLookupLatin1</function></funcdef>
2547           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2548           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2549           <paramdef>int <parameter>nbytes</parameter></paramdef>
2550           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2551           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2552         </funcprototype>
2553       </funcsynopsis>
2554       <variablelist>
2555         <varlistentry>
2556           <term><parameter>event</parameter></term>
2557           <listitem><para>
2558 specifies the key event
2559             </para></listitem>
2560         </varlistentry>
2561         <varlistentry>
2562           <term><parameter>buffer</parameter></term>
2563           <listitem><para>
2564 returns the translated characters
2565             </para></listitem>
2566         </varlistentry>
2567         <varlistentry>
2568           <term><parameter>nbytes</parameter></term>
2569           <listitem><para>
2570 specifies the length of the buffer
2571             </para></listitem>
2572         </varlistentry>
2573         <varlistentry>
2574           <term><parameter>keysym</parameter></term>
2575           <listitem><para>
2576 returns the computed KeySym, or None
2577             </para></listitem>
2578         </varlistentry>
2579         <varlistentry>
2580           <term><parameter>status</parameter></term>
2581           <listitem><para>
2582 specifies or returns the compose state
2583             </para></listitem>
2584         </varlistentry>
2585       </variablelist>
2586
2587 This function is identical to
2588 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2589 and exists only for naming symmetry with other functions.
2590     </para>
2591
2592     <para id="XmuLookupLatin2">
2593       <indexterm zone="XmuLookupLatin2">
2594         <primary><function>XmuLookupLatin2</function></primary>
2595       </indexterm>
2596       <funcsynopsis>
2597         <funcprototype>
2598           <funcdef>int <function>XmuLookupLatin2</function></funcdef>
2599           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2600           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2601           <paramdef>int <parameter>nbytes</parameter></paramdef>
2602           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2603           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2604         </funcprototype>
2605       </funcsynopsis>
2606       <variablelist>
2607         <varlistentry>
2608           <term><parameter>event</parameter></term>
2609           <listitem><para>
2610 specifies the key event
2611             </para></listitem>
2612         </varlistentry>
2613         <varlistentry>
2614           <term><parameter>buffer</parameter></term>
2615           <listitem><para>
2616 returns the translated characters
2617             </para></listitem>
2618         </varlistentry>
2619         <varlistentry>
2620           <term><parameter>nbytes</parameter></term>
2621           <listitem><para>
2622 specifies the length of the buffer
2623             </para></listitem>
2624         </varlistentry>
2625         <varlistentry>
2626           <term><parameter>keysym</parameter></term>
2627           <listitem><para>
2628 returns the computed KeySym, or None
2629             </para></listitem>
2630         </varlistentry>
2631         <varlistentry>
2632           <term><parameter>status</parameter></term>
2633           <listitem><para>
2634 specifies or returns the compose state
2635             </para></listitem>
2636         </varlistentry>
2637       </variablelist>
2638
2639 This function is similar to
2640 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2641 except that it maps a key event
2642 to an Latin-2 (ISO 8859-2) string, or to an ASCII control string.
2643     </para>
2644
2645     <para id="XmuLookupLatin3">
2646       <indexterm zone="XmuLookupLatin3">
2647         <primary><function>XmuLookupLatin3</function></primary>
2648       </indexterm>
2649       <funcsynopsis>
2650         <funcprototype>
2651           <funcdef>int <function>XmuLookupLatin3</function></funcdef>
2652           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2653           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2654           <paramdef>int <parameter>nbytes</parameter></paramdef>
2655           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2656           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2657         </funcprototype>
2658       </funcsynopsis>
2659       <variablelist>
2660         <varlistentry>
2661           <term><parameter>event</parameter></term>
2662           <listitem><para>
2663 specifies the key event
2664             </para></listitem>
2665         </varlistentry>
2666         <varlistentry>
2667           <term><parameter>buffer</parameter></term>
2668           <listitem><para>
2669 returns the translated characters
2670             </para></listitem>
2671         </varlistentry>
2672         <varlistentry>
2673           <term><parameter>nbytes</parameter></term>
2674           <listitem><para>
2675 specifies the length of the buffer
2676             </para></listitem>
2677         </varlistentry>
2678         <varlistentry>
2679           <term><parameter>keysym</parameter></term>
2680           <listitem><para>
2681 returns the computed KeySym, or None
2682             </para></listitem>
2683         </varlistentry>
2684         <varlistentry>
2685           <term><parameter>status</parameter></term>
2686           <listitem><para>
2687 specifies or returns the compose state
2688             </para></listitem>
2689         </varlistentry>
2690       </variablelist>
2691
2692 This function is similar to
2693 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2694 except that it maps a key event
2695 to an Latin-3 (ISO 8859-3) string, or to an ASCII control string.
2696     </para>
2697
2698     <para id="XmuLookupLatin4">
2699       <indexterm zone="XmuLookupLatin4">
2700         <primary><function>XmuLookupLatin4</function></primary>
2701       </indexterm>
2702       <funcsynopsis>
2703         <funcprototype>
2704           <funcdef>int <function>XmuLookupLatin4</function></funcdef>
2705           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2706           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2707           <paramdef>int <parameter>nbytes</parameter></paramdef>
2708           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2709           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2710         </funcprototype>
2711       </funcsynopsis>
2712       <variablelist>
2713         <varlistentry>
2714           <term><parameter>event</parameter></term>
2715           <listitem><para>
2716 specifies the key event
2717             </para></listitem>
2718         </varlistentry>
2719         <varlistentry>
2720           <term><parameter>buffer</parameter></term>
2721           <listitem><para>
2722 returns the translated characters
2723             </para></listitem>
2724         </varlistentry>
2725         <varlistentry>
2726           <term><parameter>nbytes</parameter></term>
2727           <listitem><para>
2728 specifies the length of the buffer
2729             </para></listitem>
2730         </varlistentry>
2731         <varlistentry>
2732           <term><parameter>keysym</parameter></term>
2733           <listitem><para>
2734 returns the computed KeySym, or None
2735             </para></listitem>
2736         </varlistentry>
2737         <varlistentry>
2738           <term><parameter>status</parameter></term>
2739           <listitem><para>
2740 specifies or returns the compose state
2741             </para></listitem>
2742         </varlistentry>
2743       </variablelist>
2744
2745 This function is similar to
2746 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2747 except that it maps a key event
2748 to an Latin-4 (ISO 8859-4) string, or to an ASCII control string.
2749     </para>
2750
2751     <para id="XmuLookupKana">
2752       <indexterm zone="XmuLookupKana">
2753         <primary><function>XmuLookupKana</function></primary>
2754       </indexterm>
2755       <funcsynopsis>
2756         <funcprototype>
2757           <funcdef>int <function>XmuLookupKana</function></funcdef>
2758           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2759           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2760           <paramdef>int <parameter>nbytes</parameter></paramdef>
2761           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2762           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2763         </funcprototype>
2764       </funcsynopsis>
2765       <variablelist>
2766         <varlistentry>
2767           <term><parameter>event</parameter></term>
2768           <listitem><para>
2769 specifies the key event
2770             </para></listitem>
2771         </varlistentry>
2772         <varlistentry>
2773           <term><parameter>buffer</parameter></term>
2774           <listitem><para>
2775 returns the translated characters
2776             </para></listitem>
2777         </varlistentry>
2778         <varlistentry>
2779           <term><parameter>nbytes</parameter></term>
2780           <listitem><para>
2781 specifies the length of the buffer
2782             </para></listitem>
2783         </varlistentry>
2784         <varlistentry>
2785           <term><parameter>keysym</parameter></term>
2786           <listitem><para>
2787 returns the computed KeySym, or None
2788             </para></listitem>
2789         </varlistentry>
2790         <varlistentry>
2791           <term><parameter>status</parameter></term>
2792           <listitem><para>
2793 specifies or returns the compose state
2794             </para></listitem>
2795         </varlistentry>
2796       </variablelist>
2797
2798 This function is similar to
2799 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2800 except that it maps a key event
2801 to a string in an encoding consisting of Latin-1 (ISO 8859-1) and ASCII
2802 control in the Graphics Left half (values 0 to 127), and Katakana in the
2803 Graphics Right half (values 128 to 255), using the values from JIS
2804 X201-1976.
2805     </para>
2806
2807     <para id="XmuLookupJISX0201">
2808       <indexterm zone="XmuLookupJISX0201">
2809         <primary><function>XmuLookupJISX0201</function></primary>
2810       </indexterm>
2811       <funcsynopsis>
2812         <funcprototype>
2813           <funcdef>int <function>XmuLookupJISX0201</function></funcdef>
2814           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2815           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2816           <paramdef>int <parameter>nbytes</parameter></paramdef>
2817           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2818           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2819         </funcprototype>
2820       </funcsynopsis>
2821       <variablelist>
2822         <varlistentry>
2823           <term><parameter>event</parameter></term>
2824           <listitem><para>
2825 specifies the key event
2826             </para></listitem>
2827         </varlistentry>
2828         <varlistentry>
2829           <term><parameter>buffer</parameter></term>
2830           <listitem><para>
2831 returns the translated characters
2832             </para></listitem>
2833         </varlistentry>
2834         <varlistentry>
2835           <term><parameter>nbytes</parameter></term>
2836           <listitem><para>
2837 specifies the length of the buffer
2838             </para></listitem>
2839         </varlistentry>
2840         <varlistentry>
2841           <term><parameter>keysym</parameter></term>
2842           <listitem><para>
2843 returns the computed KeySym, or None
2844             </para></listitem>
2845         </varlistentry>
2846         <varlistentry>
2847           <term><parameter>status</parameter></term>
2848           <listitem><para>
2849 specifies or returns the compose state
2850             </para></listitem>
2851         </varlistentry>
2852       </variablelist>
2853
2854 This function is similar to
2855 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2856 except that it maps a key event
2857 to a string in the JIS X0201-1976 encoding, including ASCII control.
2858     </para>
2859
2860     <para id="XmuLookupArabic">
2861       <indexterm zone="XmuLookupArabic">
2862         <primary><function>XmuLookupArabic</function></primary>
2863       </indexterm>
2864       <funcsynopsis>
2865         <funcprototype>
2866           <funcdef>int <function>XmuLookupArabic</function></funcdef>
2867           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2868           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2869           <paramdef>int <parameter>nbytes</parameter></paramdef>
2870           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2871           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2872         </funcprototype>
2873       </funcsynopsis>
2874       <variablelist>
2875         <varlistentry>
2876           <term><parameter>event</parameter></term>
2877           <listitem><para>
2878 specifies the key event
2879             </para></listitem>
2880         </varlistentry>
2881         <varlistentry>
2882           <term><parameter>buffer</parameter></term>
2883           <listitem><para>
2884 returns the translated characters
2885             </para></listitem>
2886         </varlistentry>
2887         <varlistentry>
2888           <term><parameter>nbytes</parameter></term>
2889           <listitem><para>
2890 specifies the length of the buffer
2891             </para></listitem>
2892         </varlistentry>
2893         <varlistentry>
2894           <term><parameter>keysym</parameter></term>
2895           <listitem><para>
2896 returns the computed KeySym, or None
2897             </para></listitem>
2898         </varlistentry>
2899         <varlistentry>
2900           <term><parameter>status</parameter></term>
2901           <listitem><para>
2902 specifies or returns the compose state
2903             </para></listitem>
2904         </varlistentry>
2905       </variablelist>
2906
2907 This function is similar to
2908 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2909 except that it maps a key event
2910 to a Latin/Arabic (ISO 8859-6) string, or to an ASCII control string.
2911     </para>
2912
2913     <para id="XmuLookupCyrillic">
2914       <indexterm zone="XmuLookupCyrillic">
2915         <primary><function>XmuLookupCyrillic</function></primary>
2916       </indexterm>
2917       <funcsynopsis>
2918         <funcprototype>
2919           <funcdef>int <function>XmuLookupCyrillic</function></funcdef>
2920           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2921           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2922           <paramdef>int <parameter>nbytes</parameter></paramdef>
2923           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2924           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2925         </funcprototype>
2926       </funcsynopsis>
2927       <variablelist>
2928         <varlistentry>
2929           <term><parameter>event</parameter></term>
2930           <listitem><para>
2931 specifies the key event
2932             </para></listitem>
2933         </varlistentry>
2934         <varlistentry>
2935           <term><parameter>buffer</parameter></term>
2936           <listitem><para>
2937 returns the translated characters
2938             </para></listitem>
2939         </varlistentry>
2940         <varlistentry>
2941           <term><parameter>nbytes</parameter></term>
2942           <listitem><para>
2943 specifies the length of the buffer
2944             </para></listitem>
2945         </varlistentry>
2946         <varlistentry>
2947           <term><parameter>keysym</parameter></term>
2948           <listitem><para>
2949 returns the computed KeySym, or None
2950             </para></listitem>
2951         </varlistentry>
2952         <varlistentry>
2953           <term><parameter>status</parameter></term>
2954           <listitem><para>
2955 specifies or returns the compose state
2956             </para></listitem>
2957         </varlistentry>
2958       </variablelist>
2959
2960 This function is similar to
2961 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2962 except that it maps a key event
2963 to a Latin/Cyrillic (ISO 8859-5) string, or to an ASCII control string.
2964     </para>
2965
2966     <para id="XmuLookupGreek">
2967       <indexterm zone="XmuLookupGreek">
2968         <primary><function>XmuLookupGreek</function></primary>
2969       </indexterm>
2970       <funcsynopsis>
2971         <funcprototype>
2972           <funcdef>int <function>XmuLookupGreek</function></funcdef>
2973           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
2974           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
2975           <paramdef>int <parameter>nbytes</parameter></paramdef>
2976           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
2977           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
2978         </funcprototype>
2979       </funcsynopsis>
2980       <variablelist>
2981         <varlistentry>
2982           <term><parameter>event</parameter></term>
2983           <listitem><para>
2984 specifies the key event
2985             </para></listitem>
2986         </varlistentry>
2987         <varlistentry>
2988           <term><parameter>buffer</parameter></term>
2989           <listitem><para>
2990 returns the translated characters
2991             </para></listitem>
2992         </varlistentry>
2993         <varlistentry>
2994           <term><parameter>nbytes</parameter></term>
2995           <listitem><para>
2996 specifies the length of the buffer
2997             </para></listitem>
2998         </varlistentry>
2999         <varlistentry>
3000           <term><parameter>keysym</parameter></term>
3001           <listitem><para>
3002 returns the computed KeySym, or None
3003             </para></listitem>
3004         </varlistentry>
3005         <varlistentry>
3006           <term><parameter>status</parameter></term>
3007           <listitem><para>
3008 specifies or returns the compose state
3009             </para></listitem>
3010         </varlistentry>
3011       </variablelist>
3012
3013 This function is similar to
3014 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
3015 except that it maps a key event
3016 to a Latin/Greek (ISO 8859-7) string, or to an ASCII control string.
3017     </para>
3018
3019     <para id="XmuLookupHebrew">
3020       <indexterm zone="XmuLookupHebrew">
3021         <primary><function>XmuLookupHebrew</function></primary>
3022       </indexterm>
3023       <funcsynopsis>
3024         <funcprototype>
3025           <funcdef>int <function>XmuLookupHebrew</function></funcdef>
3026           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
3027           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
3028           <paramdef>int <parameter>nbytes</parameter></paramdef>
3029           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
3030           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
3031         </funcprototype>
3032       </funcsynopsis>
3033       <variablelist>
3034         <varlistentry>
3035           <term><parameter>event</parameter></term>
3036           <listitem><para>
3037 specifies the key event
3038             </para></listitem>
3039         </varlistentry>
3040         <varlistentry>
3041           <term><parameter>buffer</parameter></term>
3042           <listitem><para>
3043 returns the translated characters
3044             </para></listitem>
3045         </varlistentry>
3046         <varlistentry>
3047           <term><parameter>nbytes</parameter></term>
3048           <listitem><para>
3049 specifies the length of the buffer
3050             </para></listitem>
3051         </varlistentry>
3052         <varlistentry>
3053           <term><parameter>keysym</parameter></term>
3054           <listitem><para>
3055 returns the computed KeySym, or None
3056             </para></listitem>
3057         </varlistentry>
3058         <varlistentry>
3059           <term><parameter>status</parameter></term>
3060           <listitem><para>
3061 specifies or returns the compose state
3062             </para></listitem>
3063         </varlistentry>
3064       </variablelist>
3065
3066 This function is similar to
3067 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
3068 except that it maps a key event
3069 to a Latin/Hebrew (ISO 8859-8) string, or to an ASCII control string.
3070     </para>
3071
3072     <para id="XmuLookupAPL">
3073       <indexterm zone="XmuLookupAPL">
3074         <primary><function>XmuLookupAPL</function></primary>
3075       </indexterm>
3076       <funcsynopsis>
3077         <funcprototype>
3078           <funcdef>int <function>XmuLookupAPL</function></funcdef>
3079           <paramdef>XKeyEvent *<parameter>event</parameter></paramdef>
3080           <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
3081           <paramdef>int <parameter>nbytes</parameter></paramdef>
3082           <paramdef>KeySym *<parameter>keysym</parameter></paramdef>
3083           <paramdef>XComposeStatus *<parameter>status</parameter></paramdef>
3084         </funcprototype>
3085       </funcsynopsis>
3086       <variablelist>
3087         <varlistentry>
3088           <term><parameter>event</parameter></term>
3089           <listitem><para>
3090 specifies the key event
3091             </para></listitem>
3092         </varlistentry>
3093         <varlistentry>
3094           <term><parameter>buffer</parameter></term>
3095           <listitem><para>
3096 returns the translated characters
3097             </para></listitem>
3098         </varlistentry>
3099         <varlistentry>
3100           <term><parameter>nbytes</parameter></term>
3101           <listitem><para>
3102 specifies the length of the buffer
3103             </para></listitem>
3104         </varlistentry>
3105         <varlistentry>
3106           <term><parameter>keysym</parameter></term>
3107           <listitem><para>
3108 returns the computed KeySym, or None
3109             </para></listitem>
3110         </varlistentry>
3111         <varlistentry>
3112           <term><parameter>status</parameter></term>
3113           <listitem><para>
3114 specifies or returns the compose state
3115             </para></listitem>
3116         </varlistentry>
3117       </variablelist>
3118
3119 This function is similar to
3120 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
3121 except that it maps a key event to an APL string.
3122     </para>
3123
3124   </sect1>
3125
3126   <sect1 id='Compound_Text_Functions'>
3127 <title>Compound Text Functions</title>
3128
3129     <para>
3130 The functions defined in this section are for parsing Compound Text strings,
3131 decomposing them into individual segments. Definitions needed to use these
3132 routines are in the include file
3133 &lt;<filename class='headerfile'>X11/Xmu/Xct.h</filename>&gt;
3134 <indexterm>
3135 <primary><filename class='headerfile'>X11/Xmu/Xct.h</filename></primary>
3136 </indexterm>
3137 and link against the libXmu library.
3138     </para>
3139
3140     <warning><para>
3141 The functions in this section are <emphasis remap='B'>deprecated</emphasis> because they shift the
3142 burden for recently introduced locale encodings to the application. The
3143 use of the
3144 <symbol>UTF8_STRING</symbol>
3145 text encoding provides a better alternative.
3146       </para></warning>
3147
3148     <para>
3149 A Compound Text string is represented as the following type:
3150
3151       <synopsis>
3152         typedef unsigned char *XctString;
3153       </synopsis>
3154     </para>
3155
3156     <para id="XctCreate">
3157       <indexterm zone="XctCreate">
3158         <primary><function>XctCreate</function></primary>
3159       </indexterm>
3160       <funcsynopsis>
3161         <funcprototype>
3162           <funcdef>XctData <function>XctCreate</function></funcdef>
3163           <paramdef>const XctString <parameter>string</parameter></paramdef>
3164           <paramdef>int <parameter>length</parameter></paramdef>
3165           <paramdef>XctFlags <parameter>flags</parameter></paramdef>
3166         </funcprototype>
3167       </funcsynopsis>
3168       <variablelist>
3169         <varlistentry>
3170           <term><parameter>string</parameter></term>
3171           <listitem><para>
3172 the Compound Text string
3173             </para></listitem>
3174         </varlistentry>
3175         <varlistentry>
3176           <term><parameter>length</parameter></term>
3177           <listitem><para>
3178 the number of bytes in string
3179             </para></listitem>
3180         </varlistentry>
3181         <varlistentry>
3182           <term><parameter>flags</parameter></term>
3183           <listitem><para>
3184 parsing control flags
3185             </para></listitem>
3186         </varlistentry>
3187       </variablelist>
3188
3189 This function creates an
3190 <type>XctData</type>
3191 structure for parsing a Compound Text
3192 string.  The string need not be null terminated.  The following flags are
3193 defined to control parsing of the string:
3194
3195     <variablelist>
3196       <varlistentry>
3197         <term><symbol>XctSingleSetSegments</symbol></term>
3198         <listitem><para>
3199 This means that returned segments should contain
3200 characters from only one set (C0, C1, GL, GR).  When this is requested,
3201 <symbol>XctSegment</symbol>
3202 is never returned by
3203 <function>XctNextItem</function>,
3204 instead
3205 <symbol>XctC0Segment</symbol>,
3206 <symbol>XctC1Segment</symbol>,
3207 <symbol>XctGlSegment</symbol>,
3208 and
3209 <symbol>XctGRSegment</symbol>
3210 are returned.  C0 and C1
3211 segments are always returned as singleton characters.
3212           </para></listitem>
3213       </varlistentry>
3214
3215       <varlistentry>
3216         <term><symbol>XctProvideExtensions</symbol></term>
3217         <listitem><para>
3218 This means that if the Compound Text string is from a
3219 higher version than this code is implemented to, then syntactically correct
3220 but unknown control sequences should be returned as
3221 <symbol>XctExtension</symbol>
3222 items by
3223 <function>XctNextItem</function>.
3224 If this flag is not set, and the Compound Text string version
3225 indicates that extensions cannot be ignored, then each unknown control
3226 sequence will be reported as an
3227 <symbol>XctError</symbol>.
3228           </para></listitem>
3229       </varlistentry>
3230
3231       <varlistentry>
3232         <term><symbol>XctAcceptC0Extensions</symbol></term>
3233         <listitem><para>
3234 This means that if the Compound Text string is from
3235 a higher version than this code is implemented to, then unknown C0
3236 characters should be treated as if they were legal, and returned as C0
3237 characters (regardless of how
3238 <symbol>XctProvideExtensions</symbol>
3239 is set) by
3240 <function>XctNextItem</function>.
3241 If this flag is not set, then all unknown C0 characters are treated
3242 according to
3243 <symbol>XctProvideExtensions</symbol>.
3244           </para></listitem>
3245       </varlistentry>
3246
3247       <varlistentry>
3248         <term><symbol>XctAcceptC1Extensions</symbol></term>
3249         <listitem><para>
3250 This means that if the Compound Text string is from
3251 a higher version than this code is implemented to, then unknown C1
3252 characters should be treated as if they were legal, and returned as C1
3253 characters (regardless of how
3254 <symbol>XctProvideExtensions</symbol>
3255 is set) by
3256 <function>XctNextItem</function>.
3257 If this flag is not set, then all unknown C1 characters are treated
3258 according to
3259 <symbol>XctProvideExtensions</symbol>.
3260           </para></listitem>
3261       </varlistentry>
3262       <varlistentry>
3263         <term><symbol>XctHideDirection</symbol></term>
3264         <listitem><para>
3265 This means that horizontal direction changes should be
3266 reported as
3267 <symbol>XctHorizontal</symbol>
3268 items by
3269 <function>XctNextItem</function>. If this flag is not set,
3270 then direction changes are not returned as items, but the current direction
3271 is still maintained and reported for other items.  The current direction is
3272 given as an enumeration, with the values
3273 <symbol>XctUnspecified</symbol>,
3274 <symbol>XctLeftToRight</symbol>,
3275 and
3276 <symbol>XctRightToLeft</symbol>.
3277           </para></listitem>
3278       </varlistentry>
3279       <varlistentry>
3280         <term><symbol>XctFreeString</symbol></term>
3281         <listitem><para>
3282 This means that
3283 <function>XctFree</function>
3284 should free the Compound Text string that is passed to
3285 <function>XctCreate</function>.
3286 If this flag is not set, the string is not freed.
3287           </para></listitem>
3288       </varlistentry>
3289
3290       <varlistentry>
3291         <term><symbol>XctShiftMultiGRToGL</symbol></term>
3292         <listitem><para>
3293 This means that
3294 <function>XctNextItem</function>
3295 should translate GR
3296 segments on-the-fly into GL segments for the GR sets: GB2312.1980-1,
3297 JISX0208.1983-1, and KSC5601.1987-1.
3298           </para></listitem>
3299       </varlistentry>
3300     </variablelist>
3301   </para>
3302
3303     <para id="XctReset">
3304       <indexterm zone="XctReset">
3305         <primary><function>XctReset</function></primary>
3306       </indexterm>
3307       <funcsynopsis>
3308         <funcprototype>
3309           <funcdef>void <function>XctReset</function></funcdef>
3310             <paramdef>XctData <parameter>data</parameter></paramdef>
3311           </funcprototype>
3312         </funcsynopsis>
3313         <variablelist>
3314           <varlistentry>
3315             <term><parameter>data</parameter></term>
3316             <listitem><para>
3317 specifies the Compound Text structure
3318               </para></listitem>
3319           </varlistentry>
3320         </variablelist>
3321
3322 This function resets the
3323 <type>XctData</type>
3324 structure to reparse the Compound Text string from the beginning.
3325       </para>
3326
3327       <para id="XctNextItem">
3328       <indexterm zone="XctNextItem">
3329         <primary><function>XctNextItem</function></primary>
3330       </indexterm>
3331       <funcsynopsis>
3332         <funcprototype>
3333           <funcdef>XctResult <function>XctNextItem</function></funcdef>
3334             <paramdef>XctData <parameter>data</parameter></paramdef>
3335           </funcprototype>
3336         </funcsynopsis>
3337         <variablelist>
3338           <varlistentry>
3339             <term><parameter>data</parameter></term>
3340             <listitem><para>
3341 specifies the Compound Text structure
3342               </para></listitem>
3343           </varlistentry>
3344         </variablelist>
3345
3346 This function parses the next &ldquo;item&rdquo; from the Compound Text string.  The
3347 return value indicates what kind of item is returned.  The item itself, its
3348 length, and the current contextual state, are reported as components of the
3349 <type>XctData</type>
3350 structure.
3351 <type>XctResult</type>
3352 is an enumeration, with the following values:
3353
3354         <variablelist>
3355           <varlistentry>
3356             <term><symbol>XctSegment</symbol></term>
3357             <listitem><para>
3358 the item contains some mixture of C0, GL, GR, and C1 characters.
3359               </para></listitem>
3360           </varlistentry>
3361
3362           <varlistentry>
3363             <term><symbol>XctC0Segment</symbol></term>
3364             <listitem><para>
3365 the item contains only C0 characters.
3366               </para></listitem>
3367           </varlistentry>
3368
3369           <varlistentry>
3370             <term><symbol>XctGLSegment</symbol></term>
3371             <listitem><para>
3372 the item contains only GL characters.
3373               </para></listitem>
3374           </varlistentry>
3375
3376           <varlistentry>
3377             <term><symbol>XctC1Segment</symbol></term>
3378             <listitem><para>
3379 the item contains only C1 characters.
3380               </para></listitem>
3381           </varlistentry>
3382
3383           <varlistentry>
3384             <term><symbol>XctGRSegment</symbol></term>
3385             <listitem><para>
3386 the item contains only GR characters.
3387               </para></listitem>
3388           </varlistentry>
3389
3390           <varlistentry>
3391             <term><symbol>XctExtendedSegment</symbol></term>
3392             <listitem><para>
3393 the item contains an extended segment.
3394               </para></listitem>
3395           </varlistentry>
3396
3397           <varlistentry>
3398             <term><symbol>XctExtension</symbol></term>
3399             <listitem><para>
3400 the item is an unknown extension control sequence.
3401               </para></listitem>
3402           </varlistentry>
3403
3404           <varlistentry>
3405             <term><symbol>XctHorizontal</symbol></term>
3406             <listitem><para>
3407 the item indicates a change in horizontal direction or
3408 depth.  The new direction and depth are recorded in the
3409 <type>XctData</type>
3410 structure.
3411               </para></listitem>
3412           </varlistentry>
3413
3414           <varlistentry>
3415             <term><symbol>XctEndOfText</symbol></term>
3416             <listitem><para>
3417 The end of the Compound Text string has been reached.
3418               </para></listitem>
3419           </varlistentry>
3420
3421           <varlistentry>
3422             <term><symbol>XctError</symbol></term>
3423             <listitem><para>
3424 the string contains a syntactic or semantic error; no further
3425 parsing should be performed.
3426               </para></listitem>
3427           </varlistentry>
3428         </variablelist>
3429     </para>
3430
3431     <para id="XctData">
3432       <indexterm zone="XctData">
3433         <primary><type>XctData</type></primary>
3434       </indexterm>
3435 The following state values are stored in the
3436 <type>XctData</type>
3437 structure:
3438         <synopsis>
3439     XctString           item;           /* the action item */
3440     unsigned            item_length;    /* length of item in bytes */
3441     int                 char_size;      /* the number of bytes per character in
3442                                          * item, with zero meaning variable */
3443     char                *encoding;      /* the XLFD encoding name for item */
3444     XctHDirection       horizontal;     /* the direction of item */
3445     unsigned            horz_depth;     /* the current direction nesting depth */
3446     char                *GL;            /* the "{I} F" string for the current GL */
3447     char                *GL_encoding;   /* the XLFD encoding name for the current GL */
3448     int                 GL_set_size;    /* 94 or 96 */
3449     int                 GL_char_size;   /* the number of bytes per GL character */
3450     char                *GR;            /* the "{I} F" string for the current GR */
3451     char                *GR_encoding;   /* the XLFD encoding name for the current GR */
3452     int                 GR_set_size;    /* 94 or 96 */
3453     int                 GR_char_size;   /* number of bytes per GR character */
3454     char                *GLGR_encoding; /* the XLFD encoding name for the current
3455                                          *  GL+GR, if known */
3456         </synopsis>
3457       </para>
3458       <para>
3459         <funcsynopsis>
3460           <funcprototype>
3461             <funcdef>void <function>XctFree</function></funcdef>
3462             <paramdef>XctData <parameter>data</parameter></paramdef>
3463           </funcprototype>
3464         </funcsynopsis>
3465         <variablelist>
3466           <varlistentry>
3467             <term><parameter>data</parameter></term>
3468             <listitem><para>
3469 specifies the Compound Text structure
3470               </para></listitem>
3471           </varlistentry>
3472         </variablelist>
3473
3474 This function frees all data associated with the
3475 <type>XctData</type>
3476 structure.
3477       </para>
3478
3479   </sect1>
3480
3481   <sect1 id='CloseDisplay_Hook_Functions'>
3482 <title>CloseDisplay Hook Functions</title>
3483
3484     <para>
3485 To use the functions defined in this section, you should include the header
3486 file
3487 &lt;<filename class='headerfile'>X11/Xmu/CloseHook.h</filename>&gt;
3488 <indexterm>
3489 <primary><filename class='headerfile'>X11/Xmu/CloseHook.h</filename></primary>
3490 </indexterm>
3491 and link against the libXmu library.
3492     </para>
3493
3494     <para id="XmuAddCloseDisplayHook">
3495       <indexterm zone="XmuAddCloseDisplayHook">
3496         <primary><function>XmuAddCloseDisplayHook</function></primary>
3497       </indexterm>
3498       <funcsynopsis>
3499         <funcprototype>
3500           <funcdef>CloseHook <function>XmuAddCloseDisplayHook</function></funcdef>
3501           <paramdef>Display *<parameter>dpy</parameter></paramdef>
3502           <paramdef>int <parameter>( *func )</parameter>
3503             <funcparams>Display *, XPointer</funcparams></paramdef>
3504           <paramdef>XPointer <parameter>arg</parameter></paramdef>
3505         </funcprototype>
3506       </funcsynopsis>
3507       <variablelist>
3508         <varlistentry>
3509           <term><parameter>dpy</parameter></term>
3510           <listitem><para>
3511 specifies the connection to the X server
3512             </para></listitem>
3513         </varlistentry>
3514         <varlistentry>
3515           <term><parameter>func</parameter></term>
3516           <listitem><para>
3517 specifies the function to call at display close
3518             </para></listitem>
3519         </varlistentry>
3520         <varlistentry>
3521           <term><parameter>arg</parameter></term>
3522           <listitem><para>
3523 specifies arbitrary data to pass to <parameter>func</parameter>
3524             </para></listitem>
3525         </varlistentry>
3526       </variablelist>
3527
3528 This function adds a callback for the given display.  When the display is
3529 closed, the given function will be called with the given display and
3530 argument as:
3531
3532       <programlisting>
3533         (*func)(dpy, arg)
3534       </programlisting>
3535     </para>
3536
3537     <para>
3538 The function is declared to return an int even though the value is ignored,
3539 because some compilers used to have problems with functions returning void.
3540     </para>
3541
3542     <para>
3543 This routine returns <symbol>NULL</symbol> if it was unable to add the
3544 callback, otherwise it
3545 returns an opaque handle that can be used to remove or lookup the callback.
3546     </para>
3547
3548     <para id="XmuRemoveCloseDisplayHook">
3549       <indexterm zone="XmuRemoveCloseDisplayHook">
3550         <primary><function>XmuRemoveCloseDisplayHook</function></primary>
3551       </indexterm>
3552       <funcsynopsis>
3553         <funcprototype>
3554           <funcdef>Bool <function>XmuRemoveCloseDisplayHook</function></funcdef>
3555           <paramdef>Display *<parameter>dpy</parameter></paramdef>
3556           <paramdef>CloseHook <parameter>handle</parameter></paramdef>
3557           <paramdef>int <parameter>( *func )</parameter>
3558             <funcparams>Display *, XPointer</funcparams></paramdef>
3559           <paramdef>XPointer <parameter>arg</parameter></paramdef>
3560         </funcprototype>
3561       </funcsynopsis>
3562       <variablelist>
3563         <varlistentry>
3564           <term><parameter>dpy</parameter></term>
3565           <listitem><para>
3566 specifies the connection to the X server
3567             </para></listitem>
3568         </varlistentry>
3569         <varlistentry>
3570           <term><parameter>handle</parameter></term>
3571           <listitem><para>
3572 specifies the callback by id, or <symbol>NULL</symbol>
3573             </para></listitem>
3574         </varlistentry>
3575         <varlistentry>
3576           <term><function>func</function></term>
3577           <listitem><para>
3578 specifies the callback by function
3579             </para></listitem>
3580         </varlistentry>
3581         <varlistentry>
3582           <term><parameter>arg</parameter></term>
3583                 <listitem><para>
3584 specifies the function data to match
3585             </para></listitem>
3586         </varlistentry>
3587       </variablelist>
3588
3589 This function deletes a callback that has been added with
3590 <function>XmuAddCloseDisplayHook</function>.
3591 If handle is not <symbol>NULL</symbol>, it specifies the callback to
3592 remove, and the func and arg parameters are ignored.  If handle is <symbol>NULL</symbol>, the
3593 first callback found to match the specified func and arg will be removed.
3594 Returns
3595 <symbol>True</symbol>
3596 if a callback was removed, else returns
3597 <symbol>False</symbol>.
3598     </para>
3599
3600     <para id="XmuLookupCloseDisplayHook">
3601       <indexterm zone="XmuLookupCloseDisplayHook">
3602         <primary><function>XmuLookupCloseDisplayHook</function></primary>
3603       </indexterm>
3604       <funcsynopsis>
3605         <funcprototype>
3606           <funcdef>Bool <function>XmuLookupCloseDisplayHook</function></funcdef>
3607           <paramdef>Display *<parameter>dpy</parameter></paramdef>
3608           <paramdef>CloseHook <parameter>handle</parameter></paramdef>
3609           <paramdef>int <parameter>( *func )</parameter>
3610             <funcparams>Display *, XPointer</funcparams></paramdef>
3611           <paramdef>XPointer <parameter>arg</parameter></paramdef>
3612         </funcprototype>
3613       </funcsynopsis>
3614       <variablelist>
3615         <varlistentry>
3616           <term><parameter>dpy</parameter></term>
3617           <listitem><para>
3618 specifies the connection to the X server
3619             </para></listitem>
3620         </varlistentry>
3621         <varlistentry>
3622           <term><parameter>handle</parameter></term>
3623           <listitem><para>
3624 specifies the callback by id, or <symbol>NULL</symbol>
3625             </para></listitem>
3626         </varlistentry>
3627         <varlistentry>
3628           <term><function>func</function></term>
3629           <listitem><para>
3630 specifies the callback by function
3631             </para></listitem>
3632         </varlistentry>
3633         <varlistentry>
3634           <term><parameter>arg</parameter></term>
3635           <listitem><para>
3636 specifies the function data to match
3637             </para></listitem>
3638         </varlistentry>
3639       </variablelist>
3640
3641 This function determines if a callback is installed.  If handle is not
3642 <symbol>NULL</symbol>,
3643 it specifies the callback to look for, and the func and arg parameters are
3644 ignored.  If handle is <symbol>NULL</symbol>, the function will look for
3645 any callback for the
3646 specified func and arg.  Returns
3647 <symbol>True</symbol>
3648 if a matching callback exists, else returns
3649 <symbol>False</symbol>.
3650
3651
3652     </para>
3653   </sect1>
3654
3655   <sect1 id='Display_Queue_Functions'>
3656 <title>Display Queue Functions</title>
3657
3658     <para>
3659 To use the functions and types defined in this section, you should include the
3660 header file
3661 &lt;<filename class='headerfile'>X11/Xmu/DisplayQue.h</filename>&gt;
3662 <indexterm>
3663 <primary><filename class='headerfile'>X11/Xmu/DisplayQue.h</filename></primary>
3664 </indexterm>
3665 and link against the libXmu library.
3666 <filename class='headerfile'>DisplayQue.h</filename> defines the following
3667 types:
3668
3669       <indexterm zone="XmuDisplayQueue">
3670         <primary><type>XmuDisplayQueue</type></primary>
3671       </indexterm>
3672       <synopsis id="XmuDisplayQueue">
3673 typedef int (*XmuCloseDisplayQueueProc)(XmuDisplayQueue *queue,
3674                                         XmuDisplayQueueEntry *entry);
3675
3676 typedef int (*XmuFreeDisplayQueueProc)(XmuDisplayQueue *queue);
3677
3678 typedef struct _XmuDisplayQueueEntry {
3679         struct _XmuDisplayQueueEntry *prev, *next;
3680         Display *display;
3681         CloseHook closehook;
3682         XPointer data;
3683 } XmuDisplayQueueEntry;
3684
3685 typedef struct _XmuDisplayQueue {
3686         int nentries;
3687         XmuDisplayQueueEntry *head, *tail;
3688         XmuCloseDisplayQueueProc closefunc;
3689         XmuFreeDisplayQueueProc freefunc;
3690         XPointer data;
3691 } XmuDisplayQueue;
3692       </synopsis>
3693     </para>
3694
3695     <para id="XmuDQCreate">
3696       <indexterm zone="XmuDQCreate">
3697         <primary><function>XmuDQCreate</function></primary>
3698       </indexterm>
3699       <funcsynopsis>
3700         <funcprototype>
3701           <funcdef>XmuDisplayQueue *<function>XmuDQCreate</function></funcdef>
3702           <paramdef>XmuCloseDisplayQueueProc <parameter>closefunc</parameter></paramdef>
3703           <paramdef>XmuFreeDisplayQueueProc <parameter>freefunc</parameter></paramdef>
3704           <paramdef>XPointer <parameter>data</parameter></paramdef>
3705         </funcprototype>
3706       </funcsynopsis>
3707       <variablelist>
3708         <varlistentry>
3709           <term><parameter>closefunc</parameter></term>
3710           <listitem><para>
3711 specifies the close function
3712             </para></listitem>
3713         </varlistentry>
3714         <varlistentry>
3715           <term><parameter>freefunc</parameter></term>
3716           <listitem><para>
3717 specifies the free function
3718             </para></listitem>
3719         </varlistentry>
3720         <varlistentry>
3721           <term><parameter>data</parameter></term>
3722           <listitem><para>
3723 specifies private data for the functions
3724             </para></listitem>
3725         </varlistentry>
3726       </variablelist>
3727
3728 This function creates and returns an empty
3729 <type>XmuDisplayQueue</type>
3730 (which is really just a set of displays, but is called a queue for
3731 historical reasons).  The queue is initially empty, but displays
3732 can be added using
3733 <function>XmuAddDisplay</function>.
3734 The data value is simply stored in the queue for use by the closefunc
3735 and freefunc callbacks.
3736 Whenever a display in the queue is closed using
3737 <function>XCloseDisplay</function>,
3738 the <parameter>closefunc</parameter> (if non-<symbol>NULL</symbol>) is called with the queue and the display's
3739 <function>XmuDisplayQueueEntry</function>
3740 as follows:
3741       <programlisting>
3742         (*closefunc)(queue, entry)
3743       </programlisting>
3744     </para>
3745
3746     <para>
3747 The <parameter>freefunc</parameter> (if non-<symbol>NULL</symbol>) is called whenever the last
3748 display in the
3749 queue is closed, as follows:
3750
3751       <programlisting>
3752         (*freefunc)(queue)
3753       </programlisting>
3754     </para>
3755
3756     <para>
3757 The application is responsible for actually freeing the queue, by calling
3758 <function>XmuDQDestroy</function>.
3759     </para>
3760
3761     <para id="XmuDQAddDisplay">
3762       <indexterm zone="XmuDQAddDisplay">
3763         <primary><function>XmuDQAddDisplay</function></primary>
3764       </indexterm>
3765       <funcsynopsis>
3766         <funcprototype>
3767           <funcdef>XmuDisplayQueueEntry *<function>XmuDQAddDisplay</function></funcdef>
3768           <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3769           <paramdef>Display *<parameter>dpy</parameter></paramdef>
3770           <paramdef>XPointer <parameter>data</parameter></paramdef>
3771         </funcprototype>
3772      </funcsynopsis>
3773
3774       <variablelist>
3775         <varlistentry>
3776           <term><parameter>q</parameter></term>
3777           <listitem><para>
3778 specifies the queue
3779             </para></listitem>
3780         </varlistentry>
3781         <varlistentry>
3782           <term><parameter>dpy</parameter></term>
3783           <listitem><para>
3784 specifies the display to add
3785             </para></listitem>
3786         </varlistentry>
3787         <varlistentry>
3788           <term><parameter>data</parameter></term>
3789           <listitem><para>
3790 specifies private data for the free function
3791             </para></listitem>
3792         </varlistentry>
3793       </variablelist>
3794
3795 This function adds the specified display to the queue.  If successful,
3796 the queue entry is returned, otherwise <symbol>NULL</symbol> is returned.
3797 The data value is simply stored in the queue entry for use by the
3798 queue's freefunc callback.  This function does not attempt to prevent
3799 duplicate entries in the queue; the caller should use
3800 <function>XmuDQLookupDisplay</function>
3801 to determine if a display has already been added to a queue.
3802     </para>
3803
3804     <para id="XmuDQLookupDisplay">
3805       <indexterm zone="XmuDQLookupDisplay">
3806         <primary><function>XmuDQLookupDisplay</function></primary>
3807       </indexterm>
3808       <funcsynopsis>
3809         <funcprototype>
3810           <funcdef>XmuDisplayQueueEntry *<function>XmuDQLookupDisplay</function></funcdef>
3811           <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3812           <paramdef>Display *<parameter>dpy</parameter></paramdef>
3813         </funcprototype>
3814       </funcsynopsis>
3815       <variablelist>
3816         <varlistentry>
3817           <term><parameter>q</parameter></term>
3818           <listitem><para>
3819 specifies the queue
3820             </para></listitem>
3821         </varlistentry>
3822         <varlistentry>
3823           <term><parameter>dpy</parameter></term>
3824           <listitem><para>
3825 specifies the display to lookup
3826             </para></listitem>
3827         </varlistentry>
3828       </variablelist>
3829
3830 This function returns the queue entry for the specified display, or
3831 <symbol>NULL</symbol> if
3832 the display is not in the queue.
3833     </para>
3834
3835     <para id="XmuDQNDisplays">
3836       <indexterm zone="XmuDQNDisplays">
3837         <primary><function>XmuDQNDisplays</function></primary>
3838       </indexterm>
3839       <funcsynopsis>
3840         <funcprototype>
3841           <funcdef><function>XmuDQNDisplays</function></funcdef>
3842               <paramdef><parameter>q</parameter></paramdef>
3843         </funcprototype>
3844       </funcsynopsis>
3845 This macro returns the number of displays in the specified queue.
3846     </para>
3847
3848     <para id="XmuDQRemoveDisplay">
3849       <indexterm zone="XmuDQRemoveDisplay">
3850         <primary><function>XmuDQRemoveDisplay</function></primary>
3851       </indexterm>
3852       <funcsynopsis>
3853         <funcprototype>
3854           <funcdef>Bool <function>XmuDQRemoveDisplay</function></funcdef>
3855           <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3856           <paramdef>Display *<parameter>dpy</parameter></paramdef>
3857         </funcprototype>
3858       </funcsynopsis>
3859       <variablelist>
3860         <varlistentry>
3861           <term><parameter>q</parameter></term>
3862           <listitem><para>
3863 specifies the queue
3864             </para></listitem>
3865         </varlistentry>
3866         <varlistentry>
3867           <term><parameter>dpy</parameter></term>
3868           <listitem><para>
3869 specifies the display to remove
3870             </para></listitem>
3871         </varlistentry>
3872       </variablelist>
3873
3874 This function removes the specified display from the specified queue.
3875 No callbacks are performed.
3876 If the display is not found in the queue,
3877 <symbol>False</symbol>
3878 is returned, otherwise
3879 <symbol>True</symbol>
3880 is returned.
3881     </para>
3882
3883     <para id="XmuDQDestroy">
3884       <indexterm zone="XmuDQDestroy">
3885         <primary><function>XmuDQDestroy</function></primary>
3886       </indexterm>
3887       <funcsynopsis>
3888         <funcprototype>
3889           <funcdef>Bool <function>XmuDQDestroy</function></funcdef>
3890           <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3891           <paramdef>Bool <parameter>docallbacks</parameter></paramdef>
3892         </funcprototype>
3893       </funcsynopsis>
3894       <variablelist>
3895         <varlistentry>
3896           <term><parameter>q</parameter></term>
3897           <listitem><para>
3898 specifies the queue to destroy
3899             </para></listitem>
3900         </varlistentry>
3901         <varlistentry>
3902           <term><parameter>docallbacks</parameter></term>
3903           <listitem><para>
3904 specifies whether close functions should be called
3905             </para></listitem>
3906         </varlistentry>
3907       </variablelist>
3908
3909 This function releases all memory associated with the specified queue.
3910 If docallbacks is
3911 <symbol>True</symbol>,
3912 then the queue's closefunc callback (if non-<symbol>NULL</symbol>) is first called
3913 for each display in the queue, even though
3914 <function>XCloseDisplay</function>
3915 is not called on the display.
3916     </para>
3917
3918   </sect1>
3919
3920   <sect1 id='Toolkit_Convenience_Functions'>
3921 <title>Toolkit Convenience Functions</title>
3922
3923     <para>
3924 To use the functions defined in this section, you should include the header
3925 file
3926 &lt;<filename class='headerfile'>X11/Xmu/Initer.h</filename>&gt;
3927 <indexterm>
3928 <primary><filename class='headerfile'>X11/Xmu/Initer.h</filename></primary>
3929 </indexterm>
3930 and link against the libXmu library.
3931     </para>
3932
3933     <para id="XmuAddInitializer">
3934       <indexterm zone="XmuAddInitializer">
3935         <primary><function>XmuAddInitializer</function></primary>
3936       </indexterm>
3937       <funcsynopsis>
3938         <funcprototype>
3939           <funcdef>void <function>XmuAddInitializer</function></funcdef>
3940           <paramdef>void <parameter>( *func )</parameter>
3941             <funcparams>XtAppContext, XPointer</funcparams></paramdef>
3942           <paramdef>XPointer <parameter>data</parameter></paramdef>
3943         </funcprototype>
3944       </funcsynopsis>
3945       <variablelist>
3946         <varlistentry>
3947           <term><parameter>func</parameter></term>
3948           <listitem><para>
3949 specifies the procedure to register
3950             </para></listitem>
3951         </varlistentry>
3952         <varlistentry>
3953           <term><parameter>data</parameter></term>
3954           <listitem><para>
3955 specifies private data for the procedure
3956             </para></listitem>
3957         </varlistentry>
3958       </variablelist>
3959
3960 This function registers a procedure, to be invoked the first time
3961 <function>XmuCallInitializers</function>
3962 is called on a given application context.  The procedure
3963 is called with the application context and the specified data:
3964
3965       <programlisting>
3966         (*func)(app_con, data)
3967       </programlisting>
3968     </para>
3969
3970     <para id="XmuCallInitializers">
3971       <indexterm zone="XmuCallInitializers">
3972         <primary><function>XmuCallInitializers</function></primary>
3973       </indexterm>
3974       <funcsynopsis>
3975         <funcprototype>
3976           <funcdef>void <function>XmuCallInitializers</function></funcdef>
3977           <paramdef>XtAppContext <parameter>app_con</parameter></paramdef>
3978         </funcprototype>
3979       </funcsynopsis>
3980       <variablelist>
3981         <varlistentry>
3982           <term><parameter>app_con</parameter></term>
3983           <listitem><para>
3984 specifies the application context to initialize
3985             </para></listitem>
3986         </varlistentry>
3987       </variablelist>
3988
3989 This function calls each of the procedures that have been registered with
3990 <function>XmuAddInitializer</function>,
3991 if this is the first time the application context has been passed to
3992 <function>XmuCallInitializers</function>.
3993 Otherwise, this function does nothing.
3994     </para>
3995
3996   </sect1>
3997
3998   <sect1 id='Standard_Colormap_Functions'>
3999 <title>Standard Colormap Functions</title>
4000
4001     <para>
4002 To use the functions defined in this section, you should include the header
4003 file
4004 &lt;<filename class='headerfile'>X11/Xmu/StdCmap.h</filename>&gt;
4005 <indexterm>
4006 <primary><filename class='headerfile'>X11/Xmu/StdCmap.h</filename></primary>
4007 </indexterm>
4008 and link against the libXmu library.
4009     </para>
4010
4011     <para id="XmuAllStandardColormaps">
4012       <indexterm zone="XmuAllStandardColormaps">
4013         <primary><function>XmuAllStandardColormaps</function></primary>
4014       </indexterm>
4015       <funcsynopsis>
4016         <funcprototype>
4017           <funcdef>Status <function>XmuAllStandardColormaps</function></funcdef>
4018           <paramdef>Display *<parameter>dpy</parameter></paramdef>
4019         </funcprototype>
4020       </funcsynopsis>
4021       <variablelist>
4022         <varlistentry>
4023           <term><parameter>dpy</parameter></term>
4024           <listitem><para>
4025 specifies the connection to the X server
4026             </para></listitem>
4027         </varlistentry>
4028       </variablelist>
4029
4030       <indexterm>
4031         <primary>colormaps</primary><secondary>standard</secondary>
4032       </indexterm>
4033 To create all of the appropriate standard colormaps for every visual of
4034 every screen on a given display, use
4035 <function>XmuAllStandardColormaps</function>.
4036     </para>
4037
4038     <para>
4039 This function defines and retains as permanent resources all standard
4040 colormaps which are meaningful for the visuals of each screen of the
4041 display.  It returns 0 on failure, non-zero on success.  If the property of
4042 any standard colormap is already defined, this function will redefine it.
4043     </para>
4044
4045     <para>
4046 This function is intended to be used by window managers or a special client
4047 at the start of a session.
4048     </para>
4049
4050     <para>
4051 The standard colormaps of a screen are defined by properties associated with
4052 the screen's root window.  The property names of standard colormaps are
4053 predefined, and each property name except
4054 <property>RGB_DEFAULT_MAP</property> may describe at
4055 most one colormap.
4056     </para>
4057
4058     <para>
4059 The standard colormaps are: <property>RGB_BEST_MAP</property>,
4060 <property>RGB_RED_MAP</property>, <property>RGB_GREEN_MAP</property>,
4061 <property>RGB_BLUE_MAP</property>, <property>RGB_DEFAULT_MAP</property>,
4062  and <property>RGB_GRAY_MAP</property>.  Therefore a screen may
4063 have at most 6 standard colormap properties defined.
4064     </para>
4065
4066     <para>
4067 A standard colormap is associated with a particular visual of the screen.  A
4068 screen may have multiple visuals defined, including visuals of the same
4069 class at different depths.  Note that a visual id might be repeated for more
4070 than one depth, so the visual id and the depth of a visual identify the
4071 visual.  The characteristics of the visual will determine which standard
4072 colormaps are meaningful under that visual, and will determine how the
4073 standard colormap is defined.  Because a standard colormap is associated
4074 with a specific visual, there must be a method of determining which visuals
4075 take precedence in defining standard colormaps.
4076     </para>
4077
4078     <para>
4079 The method used here is: for the visual of greatest depth, define all
4080 standard colormaps meaningful to that visual class, according to this order
4081 of (descending) precedence:
4082 <symbol>DirectColor</symbol>;
4083 <symbol>PseudoColor</symbol>;
4084 <symbol>TrueColor</symbol>
4085 and
4086 <symbol>GrayScale</symbol>;
4087 and finally
4088 <symbol>StaticColor</symbol>
4089 and
4090 <symbol>StaticGray</symbol>.
4091     </para>
4092
4093 <para>This function allows success, on a per screen basis.  For example, if a map
4094 on screen 1 fails, the maps on screen 0, created earlier, will remain.
4095 However, none on screen 1 will remain.  If a map on screen 0 fails, none
4096 will remain.
4097     </para>
4098
4099     <para>
4100 See
4101 <link linkend="XmuVisualStandardColormaps"><function>XmuVisualStandardColormaps</function></link>
4102 for which standard colormaps are meaningful under these classes of visuals.
4103     </para>
4104
4105     <para id="XmuVisualStandardColormaps">
4106       <indexterm zone="XmuVisualStandardColormaps">
4107         <primary><function>XmuVisualStandardColormaps</function></primary>
4108       </indexterm>
4109       <funcsynopsis>
4110         <funcprototype>
4111           <funcdef>Status <function>XmuVisualStandardColormaps</function></funcdef>
4112           <paramdef>Display *<parameter>dpy</parameter></paramdef>
4113           <paramdef>int <parameter>screen</parameter></paramdef>
4114           <paramdef>VisualID <parameter>visualid</parameter></paramdef>
4115           <paramdef>unsigned int <parameter>depth</parameter></paramdef>
4116           <paramdef>Bool <parameter>replace</parameter></paramdef>
4117           <paramdef>Bool <parameter>retain</parameter></paramdef>
4118         </funcprototype>
4119       </funcsynopsis>
4120       <variablelist>
4121         <varlistentry>
4122           <term><parameter>dpy</parameter></term>
4123           <listitem><para>
4124 specifies the connection to the X server
4125             </para></listitem>
4126         </varlistentry>
4127         <varlistentry>
4128           <term><parameter>screen</parameter></term>
4129           <listitem><para>
4130 specifies the screen of the display
4131             </para></listitem>
4132         </varlistentry>
4133         <varlistentry>
4134           <term><parameter>visualid</parameter></term>
4135           <listitem><para>
4136 specifies the visual type
4137             </para></listitem>
4138         </varlistentry>
4139         <varlistentry>
4140           <term><parameter>depth</parameter></term>
4141           <listitem><para>
4142 specifies the visual depth
4143             </para></listitem>
4144         </varlistentry>
4145         <varlistentry>
4146           <term><parameter>replace</parameter></term>
4147           <listitem><para>
4148 specifies whether or not to replace
4149             </para></listitem>
4150         </varlistentry>
4151         <varlistentry>
4152           <term><parameter>retain</parameter></term>
4153           <listitem><para>
4154 specifies whether or not to retain
4155             </para></listitem>
4156         </varlistentry>
4157       </variablelist>
4158
4159 To create all of the appropriate standard colormaps for a given visual on a
4160 given screen, use
4161 <function>XmuVisualStandardColormaps</function>.
4162     </para>
4163
4164     <para>
4165 This function defines all appropriate standard colormap properties for the
4166 given visual.  If replace is
4167 <symbol>True</symbol>,
4168 any previous definition will be removed.
4169 If retain is
4170 <symbol>True</symbol>,
4171 new properties will be retained for the duration of the
4172 server session.  This function returns 0 on failure, non-zero on success.
4173 On failure, no new properties will be defined, but old ones may have been
4174 removed if replace was <symbol>True</symbol>.
4175     </para>
4176
4177     <para>
4178 Not all standard colormaps are meaningful to all visual classes.  This
4179 routine will check and define the following properties for the following
4180 classes, provided that the size of the colormap is not too small.  For
4181 <symbol>DirectColor</symbol>
4182 and
4183 <symbol>PseudoColor</symbol>:
4184 <property>RGB_DEFAULT_MAP</property>, <property>RGB_BEST_MAP</property>,
4185 <property>RGB_RED_MAP</property>, <property>RGB_GREEN_MAP</property>,
4186 <property>RGB_BLUE_MAP</property>, and <property>RGB_GRAY_MAP</property>.
4187 For
4188 <symbol>TrueColor</symbol>
4189 and
4190 <symbol>StaticColor</symbol>:
4191 <property>RGB_BEST_MAP</property>.  For
4192 <symbol>GrayScale</symbol>
4193 and
4194 <symbol>StaticGray</symbol>:
4195 <property>RGB_GRAY_MAP</property>.
4196     </para>
4197
4198     <para id="XmuLookupStandardColormap">
4199       <indexterm zone="XmuLookupStandardColormap">
4200         <primary><function>XmuLookupStandardColormap</function></primary>
4201       </indexterm>
4202       <funcsynopsis>
4203         <funcprototype>
4204           <funcdef>Status <function>XmuLookupStandardColormap</function></funcdef>
4205           <paramdef>Display *<parameter>dpy</parameter></paramdef>
4206           <paramdef>int <parameter>screen</parameter></paramdef>
4207           <paramdef>VisualID <parameter>visualid</parameter></paramdef>
4208           <paramdef>unsigned int <parameter>depth</parameter></paramdef>
4209           <paramdef>Atom <parameter>property</parameter></paramdef>
4210           <paramdef>Bool <parameter>replace</parameter></paramdef>
4211           <paramdef>Bool <parameter>retain</parameter></paramdef>
4212         </funcprototype>
4213       </funcsynopsis>
4214       <variablelist>
4215         <varlistentry>
4216           <term><parameter>dpy</parameter></term>
4217           <listitem><para>
4218 specifies the connection to the X server
4219             </para></listitem>
4220         </varlistentry>
4221         <varlistentry>
4222           <term><parameter>screen</parameter></term>
4223           <listitem><para>
4224 specifies the screen of the display
4225             </para></listitem>
4226         </varlistentry>
4227         <varlistentry>
4228           <term><parameter>visualid</parameter></term>
4229           <listitem><para>
4230 specifies the visual type
4231             </para></listitem>
4232         </varlistentry>
4233         <varlistentry>
4234           <term><parameter>depth</parameter></term>
4235           <listitem><para>
4236 specifies the visual depth
4237             </para></listitem>
4238         </varlistentry>
4239         <varlistentry>
4240           <term><parameter>property</parameter></term>
4241           <listitem><para>
4242 specifies the standard colormap property
4243             </para></listitem>
4244         </varlistentry>
4245         <varlistentry>
4246           <term><parameter>replace</parameter></term>
4247           <listitem><para>
4248 specifies whether or not to replace
4249             </para></listitem>
4250         </varlistentry>
4251         <varlistentry>
4252           <term><parameter>retain</parameter></term>
4253           <listitem><para>
4254 specifies whether or not to retain
4255             </para></listitem>
4256         </varlistentry>
4257       </variablelist>
4258
4259 To create a standard colormap if one does not currently exist, or replace
4260 the currently existing standard colormap, use
4261 <function>XmuLookupStandardColormap</function>.
4262     </para>
4263
4264     <para>
4265 Given a screen, a visual, and a property, this function will determine the
4266 best allocation for the property under the specified visual, and determine
4267 the whether to create a new colormap or to use the default colormap of the
4268 screen.
4269     </para>
4270
4271     <para>
4272 If replace is True, any previous definition of the property will be
4273 replaced.  If retain is True, the property and the colormap will be made
4274 permanent for the duration of the server session.  However, pre-existing
4275 property definitions which are not replaced cannot be made permanent by a
4276 call to this function; a request to retain resources pertains to newly
4277 created resources.
4278     </para>
4279
4280     <para>
4281 This function returns 0 on failure, non-zero on success.  A request to
4282 create a standard colormap upon a visual which cannot support such a map is
4283 considered a failure.  An example of this would be requesting any standard
4284 colormap property on a monochrome visual, or, requesting an
4285 <property>RGB_BEST_MAP</property> on
4286 a display whose colormap size is 16.
4287     </para>
4288
4289     <para id="XmuGetColormapAllocation">
4290       <indexterm zone="XmuGetColormapAllocation">
4291         <primary><function>XmuGetColormapAllocation</function></primary>
4292       </indexterm>
4293       <funcsynopsis>
4294         <funcprototype>
4295           <funcdef>Status <function>XmuGetColormapAllocation</function></funcdef>
4296           <paramdef>XVisualInfo *<parameter>vinfo</parameter></paramdef>
4297           <paramdef>Atom <parameter>property</parameter></paramdef>
4298           <paramdef>unsigned long *<parameter>red_max</parameter></paramdef>
4299           <paramdef>unsigned long *<parameter>green_max</parameter></paramdef>
4300           <paramdef>unsigned long *<parameter>blue_max</parameter></paramdef>
4301         </funcprototype>
4302       </funcsynopsis>
4303       <variablelist>
4304         <varlistentry>
4305           <term><parameter>vinfo</parameter></term>
4306           <listitem><para>
4307 specifies visual information for a chosen visual
4308             </para></listitem>
4309         </varlistentry>
4310         <varlistentry>
4311           <term><parameter>property</parameter></term>
4312           <listitem><para>
4313 specifies one of the standard colormap property names
4314             </para></listitem>
4315         </varlistentry>
4316         <varlistentry>
4317           <term><parameter>red_max</parameter></term>
4318           <listitem><para>
4319 returns maximum red value</para>
4320           </listitem>
4321         </varlistentry>
4322         <varlistentry>
4323           <term><parameter>green_max</parameter></term>
4324           <listitem><para>
4325 returns maximum green value
4326             </para></listitem>
4327         </varlistentry>
4328         <varlistentry>
4329           <term><parameter>blue_max</parameter></term>
4330           <listitem><para>
4331 returns maximum blue value
4332           </para></listitem>
4333         </varlistentry>
4334       </variablelist>
4335
4336 To determine the best allocation of reds, greens, and blues in a standard
4337 colormap, use
4338 <function>XmuGetColormapAllocation</function>.
4339     </para>
4340
4341     <para>
4342 <function>XmuGetColormapAllocation</function>
4343 returns 0 on failure, non-zero on success.  It is
4344 assumed that the visual is appropriate for the colormap property.
4345     </para>
4346
4347     <para id="XmuStandardColormap">
4348       <indexterm zone="XmuStandardColormap">
4349         <primary><function>XmuStandardColormap</function></primary>
4350       </indexterm>
4351       <funcsynopsis>
4352         <funcprototype>
4353           <funcdef>XStandardColormap *<function>XmuStandardColormap</function></funcdef>
4354           <paramdef>Display *<parameter>dpy</parameter></paramdef>
4355           <paramdef>int <parameter>screen</parameter></paramdef>
4356           <paramdef>VisualID <parameter>visualid</parameter></paramdef>
4357           <paramdef>unsigned int <parameter>depth</parameter></paramdef>
4358           <paramdef>Atom <parameter>property</parameter></paramdef>
4359           <paramdef>Colormap <parameter>cmap</parameter></paramdef>
4360           <paramdef>unsigned long <parameter>red_max</parameter></paramdef>
4361           <paramdef>unsigned long <parameter>green_max</parameter></paramdef>
4362           <paramdef>unsigned long <parameter>blue_max</parameter></paramdef>
4363         </funcprototype>
4364       </funcsynopsis>
4365       <variablelist>
4366         <varlistentry>
4367           <term><parameter>dpy</parameter></term>
4368           <listitem><para>
4369 specifies the connection to the X server
4370             </para></listitem>
4371         </varlistentry>
4372         <varlistentry>
4373           <term><parameter>screen</parameter></term>
4374           <listitem><para>
4375 specifies the screen of the display
4376             </para></listitem>
4377         </varlistentry>
4378         <varlistentry>
4379           <term><parameter>visualid</parameter></term>
4380           <listitem><para>
4381 specifies the visual type
4382             </para></listitem>
4383         </varlistentry>
4384         <varlistentry>
4385           <term><parameter>depth</parameter></term>
4386           <listitem><para>
4387 specifies the visual depth
4388             </para></listitem>
4389         </varlistentry>
4390         <varlistentry>
4391           <term><parameter>property</parameter></term>
4392           <listitem><para>
4393 specifies the standard colormap property
4394             </para></listitem>
4395         </varlistentry>
4396         <varlistentry>
4397           <term><parameter>cmap</parameter></term>
4398           <listitem><para>
4399 specifies the colormap ID, or None
4400             </para></listitem>
4401         </varlistentry>
4402         <varlistentry>
4403           <term><parameter>red_max</parameter></term>
4404           <listitem><para>
4405 specifies the red allocation
4406             </para></listitem>
4407         </varlistentry>
4408         <varlistentry>
4409           <term><parameter>green_max</parameter></term>
4410           <listitem><para>
4411 specifies the green allocation
4412             </para></listitem>
4413         </varlistentry>
4414         <varlistentry>
4415           <term><parameter>blue_max</parameter></term>
4416           <listitem><para>
4417 specifies the blue allocation
4418             </para></listitem>
4419         </varlistentry>
4420       </variablelist>
4421
4422 To create any one standard colormap, use
4423 <function>XmuStandardColormap</function>.
4424     </para>
4425
4426     <para>
4427 This function creates a standard colormap for the given screen, visualid,
4428 and visual depth, with the given red, green, and blue maximum values, with
4429 the given standard property name.  Upon success, it returns a pointer to an
4430 <function>XStandardColormap</function>
4431 structure which describes the newly created colormap.
4432 Upon failure, it returns <symbol>NULL</symbol>.
4433 If cmap is the default colormap of the screen, the standard colormap
4434 will be defined on the default colormap; otherwise a new colormap is created.
4435     </para>
4436
4437     <para>
4438 Resources created by this function are not made permanent; that is the
4439 caller's responsibility.
4440     </para>
4441
4442     <para id="XmuCreateColormap">
4443       <indexterm zone="XmuCreateColormap">
4444         <primary><function>XmuCreateColormap</function></primary>
4445       </indexterm>
4446       <funcsynopsis>
4447         <funcprototype>
4448           <funcdef>Status <function>XmuCreateColormap</function></funcdef>
4449           <paramdef>Display *<parameter>dpy</parameter></paramdef>
4450           <paramdef>XStandardColormap *<parameter>colormap</parameter></paramdef>
4451         </funcprototype>
4452       </funcsynopsis>
4453       <variablelist>
4454         <varlistentry>
4455           <term><parameter>dpy</parameter></term>
4456           <listitem><para>
4457 specifies the connection under which the map is created
4458             </para></listitem>
4459         </varlistentry>
4460         <varlistentry>
4461           <term><parameter>colormap</parameter></term>
4462           <listitem><para>
4463 specifies the map to be created</para></listitem>
4464         </varlistentry>
4465       </variablelist>
4466
4467 To create any one colormap which is described by an
4468 <structname>XStandardColormap</structname>
4469 structure, use
4470 <function>XmuCreateColormap</function>.
4471     </para>
4472
4473     <para>
4474 This function returns 0 on failure, and non-zero on success.  The base_pixel
4475 of the colormap is set on success.  Resources created by this function are
4476 not made permanent.  No argument error checking is provided; use at your own
4477 risk.
4478     </para>
4479
4480     <para>
4481 All colormaps are created with read-only allocations, with the exception of
4482 read-only allocations of colors which fail
4483 to return the expected pixel value, and these are individually defined as
4484 read/write allocations.  This is done so that all the cells defined in the
4485 colormap are contiguous, for use in image processing.  This typically
4486 happens with White and Black in the default map.
4487     </para>
4488
4489     <para>
4490 Colormaps of static visuals are considered to be successfully created if the
4491 map of the static visual matches the definition given in the standard
4492 colormap structure.
4493     </para>
4494
4495     <para id="XmuDeleteStandardColormap">
4496       <indexterm zone="XmuDeleteStandardColormap">
4497         <primary><function>XmuDeleteStandardColormap</function></primary>
4498       </indexterm>
4499       <funcsynopsis>
4500         <funcprototype>
4501           <funcdef>void <function>XmuDeleteStandardColormap</function></funcdef>
4502           <paramdef>Display *<parameter>dpy</parameter></paramdef>
4503           <paramdef>Screen *<parameter>screen</parameter></paramdef>
4504           <paramdef>Atom <parameter>property</parameter></paramdef>
4505         </funcprototype>
4506       </funcsynopsis>
4507       <variablelist>
4508         <varlistentry>
4509           <term><parameter>dpy</parameter></term>
4510           <listitem><para>
4511 specifies the connection to the X server
4512             </para></listitem>
4513         </varlistentry>
4514         <varlistentry>
4515           <term><parameter>screen</parameter></term>
4516           <listitem><para>
4517 specifies the screen of the display
4518             </para></listitem>
4519         </varlistentry>
4520         <varlistentry>
4521           <term><parameter>property</parameter></term>
4522           <listitem><para>
4523 specifies the standard colormap property
4524             </para></listitem>
4525         </varlistentry>
4526       </variablelist>
4527
4528 To remove any standard colormap property, use
4529 <function>XmuDeleteStandardColormap</function>.
4530 This function will remove the specified property from the specified screen,
4531 releasing any resources used by the colormap(s) of the property, if
4532 possible.
4533     </para>
4534
4535   </sect1>
4536
4537   <sect1 id='Widget_Description_Functions'>
4538 <title>Widget Description Functions</title>
4539
4540     <para>
4541 The functions defined in this section are for building a description of
4542 the structure of and resources associated with a hierarchy of widget classes.
4543 This package is typically used by applications that wish to manipulate the
4544 widget set itself.
4545     </para>
4546
4547     <para>
4548 The definitions needed to use these interfaces are in the header file
4549 &lt;<filename class='headerfile'>X11/Xmu/WidgetNode.h</filename>&gt;
4550 <indexterm>
4551 <primary><filename class='headerfile'>X11/Xmu/WidgetNode.h</filename></primary>
4552 </indexterm>.
4553 To call these functions, you need to link against the libXmu library.
4554 The following function must be called before any of the others described
4555 below:
4556
4557       <funcsynopsis>
4558         <funcprototype>
4559           <funcdef>void <function>XmuWnInitializeNodes</function></funcdef>
4560           <paramdef>XmuWidgetNode *<parameter>node_array</parameter></paramdef>
4561           <paramdef>int <parameter>num_nodes</parameter></paramdef>
4562         </funcprototype>
4563       </funcsynopsis>
4564       <variablelist>
4565         <varlistentry>
4566           <term><parameter>node_array</parameter></term>
4567           <listitem><para>
4568 specifies a list of widget classes, in alphabetical order
4569             </para></listitem>
4570         </varlistentry>
4571         <varlistentry>
4572           <term><parameter>num_nodes</parameter></term>
4573           <listitem><para>
4574 specifies the number of widget classes in the node array
4575             </para></listitem>
4576         </varlistentry>
4577       </variablelist>
4578     </para>
4579
4580     <para>
4581 To determine the resources provided by a widget class or classes, use
4582
4583       <funcsynopsis>
4584         <funcprototype>
4585           <funcdef>void <function>XmuWnFetchResources</function></funcdef>
4586           <paramdef>XmuWidgetNode *<parameter>node</parameter></paramdef>
4587           <paramdef>Widget <parameter>toplevel</parameter></paramdef>
4588           <paramdef>XmuWidgetNode *<parameter>top_node</parameter></paramdef>
4589         </funcprototype>
4590       </funcsynopsis>
4591       <variablelist>
4592         <varlistentry>
4593           <term><parameter>node</parameter></term>
4594           <listitem><para>
4595 specifies the widget class for which resources should be obtained.
4596             </para></listitem>
4597         </varlistentry>
4598         <varlistentry>
4599           <term><parameter>toplevel</parameter></term>
4600           <listitem><para>
4601 specifies the widget that should be used for creating an instance of
4602 <parameter>node</parameter>
4603 from which resources are extracted.  This is typically the value returned
4604 by <olink targetdoc='libXaw' targetptr='XtAppInitialize'><function>XtAppInitialize</function></olink>.
4605             </para></listitem>
4606         </varlistentry>
4607         <varlistentry>
4608           <term><parameter>top_node</parameter></term>
4609           <listitem><para>
4610 specifies the ancestor of <parameter>node</parameter> that should be
4611 treated as the root
4612 of the widget inheritance tree (used in determining which ancestor contributed
4613 which resources).
4614             </para></listitem>
4615         </varlistentry>
4616       </variablelist>
4617     </para>
4618
4619     <para>
4620 Each widget class inherits the resources of its parent.  To count the number
4621 of resources contributed by a particular widget class, use:
4622
4623       <funcsynopsis>
4624         <funcprototype>
4625           <funcdef>int <function>XmuWnCountOwnedResources</function></funcdef>
4626           <paramdef>XmuWidgetNode *<parameter>node</parameter></paramdef>
4627           <paramdef>XmuWidgetNode *<parameter>owner_node</parameter></paramdef>
4628           <paramdef>Bool <parameter>constraints</parameter></paramdef>
4629         </funcprototype>
4630       </funcsynopsis>
4631       <variablelist>
4632         <varlistentry>
4633           <term><parameter>node</parameter></term>
4634           <listitem><para>
4635 specifies the widget class whose resources are being examined.
4636             </para></listitem>
4637         </varlistentry>
4638         <varlistentry>
4639           <term><parameter>owner_node</parameter></term>
4640           <listitem><para>
4641 specifies the widget class of the ancestor of <parameter>node</parameter>
4642 whose contributions
4643 are being counted.
4644             </para></listitem>
4645         </varlistentry>
4646         <varlistentry>
4647           <term><parameter>constraints</parameter></term>
4648           <listitem><para>
4649 specifies whether or not to count constraint resources or normal resources.
4650             </para></listitem>
4651         </varlistentry>
4652       </variablelist>
4653
4654 This routine returns the number of resources contributed (or
4655 &ldquo;owned&rdquo;) by
4656 the specified widget class.
4657             </para>
4658
4659     <para id="XmuWnNameToNode">
4660       <indexterm zone="XmuWnNameToNode">
4661         <primary><function>XmuWnNameToNode</function></primary>
4662       </indexterm>
4663       <funcsynopsis>
4664         <funcprototype>
4665           <funcdef>XmuWidgetNode *<function>XmuWnNameToNode</function></funcdef>
4666           <paramdef>XmuWidgetNode *<parameter>node_list</parameter></paramdef>
4667           <paramdef>int <parameter>num_nodes</parameter></paramdef>
4668           <paramdef>char *<parameter>name</parameter></paramdef>
4669         </funcprototype>
4670       </funcsynopsis>
4671       <variablelist>
4672         <varlistentry>
4673           <term><parameter>node_list</parameter></term>
4674           <listitem><para>
4675 specifies a list of widget nodes
4676             </para></listitem>
4677         </varlistentry>
4678         <varlistentry>
4679           <term><parameter>num_nodes</parameter></term>
4680           <listitem><para>
4681 specifies the number of nodes in the list
4682             </para></listitem>
4683         </varlistentry>
4684         <varlistentry>
4685           <term><parameter>name</parameter></term>
4686           <listitem><para>
4687 specifies the name of the widget class in the node list to search for
4688             </para></listitem>
4689         </varlistentry>
4690       </variablelist>
4691
4692 This function returns the WidgetNode in the list that matches the given
4693 widget name or widget class name.  If no match is found, it returns
4694 <symbol>NULL</symbol>.
4695     </para>
4696
4697   </sect1>
4698
4699   <sect1 id='Participation_in_the_Editres_Protocol'>
4700 <title>Participation in the Editres Protocol</title>
4701
4702     <para>
4703       <indexterm>
4704         <primary>editres</primary>
4705       </indexterm>
4706 To participate in the editres protocol, applications which are not based
4707 on the Athena widget set should include the header file
4708 &lt;<filename class='headerfile'>X11/Xmu/Editres.h</filename>&gt;
4709 <indexterm>
4710 <primary><filename class='headerfile'>X11/Xmu/Editres.h</filename></primary>
4711 </indexterm>
4712 and link against the libXmu library.
4713     </para>
4714
4715     <para>
4716 To participate in the editres protocol, Xt applications which do not rely
4717 on the Athena widget set should register the editres protocol handler on
4718 each shell widget in the application, specifying an event mask of 0,
4719 nonmaskable events, and client data as <symbol>NULL</symbol>:
4720
4721     <programlisting>
4722 XtAddEventHandler(shell, (EventMask) 0, True, _XEditResCheckMessages, NULL);
4723     </programlisting>
4724     </para>
4725   </sect1>
4726
4727   <index />
4728 </article>