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>“Don't ask.”</para></abstract> 16 17 <legalnotice> 18 19 <para> 20Permission is hereby granted, free of charge, to any person obtaining a copy 21of this software and associated documentation files (the “Software”), to deal 22in the Software without restriction, including without limitation the rights 23to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 24copies of the Software, and to permit persons to whom the Software is 25furnished to do so, subject to the following conditions: 26 </para> 27 <para> 28The above copyright notice and this permission notice shall be included in 29all copies or substantial portions of the Software. 30 </para> 31 <para> 32THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 33IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 34FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 35X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN 36AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 37CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 38 </para> 39 <para> 40Except as contained in this notice, the name of the X Consortium shall not be 41used in advertising or otherwise to promote the sale, use or other dealings 42in this Software without prior written authorization from the X Consortium. 43 </para> 44 <para> 45<trademark><emphasis>X Window System</emphasis></trademark> 46is 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> 56The Xmu Library is a collection of miscellaneous (some might say random) 57utility functions that have been useful in building various applications 58and widgets. This library is required by the Athena Widgets. 59 </para> 60 61 <para> 62Starting in XFree86 4.1.0, and incorporated into X11R6.7 and later releases, 63a subset of the functions that do not rely on the Athena Widgets (libXaw) 64or X Toolkit Instrinsics (libXt) are provided in a second library, libXmuu. 65 </para> 66 67 <para> 68Programs using either of these libraries are encouraged to determine the 69correct 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> 74such as: 75 76 <screen> 77cc -c xapplication.c `pkg-config --cflags xmu` 78cc -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> 88To use the functions and macros defined in this section, you should include 89the header file 90<<filename class='headerfile'>X11/Xmu/Atoms.h</filename>> 91<indexterm> 92<primary><filename class='headerfile'>X11/Xmu/Atoms.h</filename></primary> 93</indexterm> 94and 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> 196These macros take a display as argument and return an 197<type>Atom</type>. 198The name of the 199atom is obtained from the macro name by removing the leading characters 200“<code>XA_</code>”. The 201<type>Atom</type> 202value is cached, such that subsequent requests do not cause 203another 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> 220specifies the atom name 221 </para></listitem> 222 </varlistentry> 223 </variablelist> 224 225This function creates and initializes an opaque object, an 226<type>AtomPtr</type>, 227for an 228<type>Atom</type> 229with the 230given name. 231<xref linkend='XmuInternAtom' xrefstyle='select: title'/> 232can 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> 249specifies the AtomPtr 250 </para></listitem> 251 </varlistentry> 252 </variablelist> 253 254The 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> 272specifies the connection to the X server 273 </para></listitem> 274 </varlistentry> 275 <varlistentry> 276 <term><parameter>atom_ptr</parameter></term> 277 <listitem><para> 278specifies the AtomPtr 279 </para></listitem> 280 </varlistentry> 281 </variablelist> 282 283This function returns the 284<type>Atom</type> 285for an 286<type>AtomPtr</type>. 287The 288<type>Atom</type> 289is cached, 290such 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> 308specifies the connection to the X server 309 </para></listitem> 310 </varlistentry> 311 <varlistentry> 312 <term><parameter>atom</parameter></term> 313 <listitem><para> 314specifies the atom whose name is desired 315 </para></listitem> 316 </varlistentry> 317 </variablelist> 318 319This function returns the name of an 320<type>Atom</type>. 321The result is cached, such that subsequent 322requests 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> 342specifies the connection to the X server 343 </para></listitem> 344 </varlistentry> 345 <varlistentry> 346 <term><parameter>names</parameter></term> 347 <listitem><para> 348specifies the strings to intern 349 </para></listitem> 350 </varlistentry> 351 <varlistentry> 352 <term><parameter>count</parameter></term> 353 <listitem><para> 354specifies the number of strings 355 </para></listitem> 356 </varlistentry> 357 <varlistentry> 358 <term><parameter>atoms</parameter></term> 359 <listitem><para> 360returns the list of Atom values 361 </para></listitem> 362 </varlistentry> 363 </variablelist> 364 365This function converts a list of atom names into 366<type>Atom</type> 367values. The results are cached, such 368that subsequent requests do not cause further round-trips to the server. 369The 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> 378To use the functions defined in this section, you should include the header 379file 380<<filename class='headerfile'>X11/Xmu/Error.h</filename>> 381<indexterm> 382<primary><filename class='headerfile'>X11/Xmu/Error.h</filename></primary> 383</indexterm> 384and 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> 403specifies the connection to the X server 404 </para></listitem> 405 </varlistentry> 406 <varlistentry> 407 <term><parameter>event</parameter></term> 408 <listitem><para> 409specifies 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 420This function prints an error message, equivalent to Xlib's default error 421message for protocol errors. It returns a non-zero value 422if the caller should consider exiting, otherwise it returns 0. 423This function can be used when you need to 424write your own error handler, but need to print out an error from within 425that 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> 443specifies the connection to the X server 444 </para></listitem> 445 </varlistentry> 446 <varlistentry> 447 <term><parameter>errorp</parameter></term> 448 <listitem><para> 449specifies the error 450 </para></listitem> 451 </varlistentry> 452 </variablelist> 453 454This function ignores errors for 455<errorname>BadWindow</errorname> 456errors for 457<olink targetdoc='libX11' targetptr='XQueryTree'><function>XQueryTree</function></olink> 458and 459<olink targetdoc='libX11' targetptr='XGetWindowAttributes'><function>XGetWindowAttributes</function></olink>, 460and ignores 461<errorname>BadDrawable</errorname> 462errors for 463<olink targetdoc='libX11' targetptr='XGetGeometry'><function>XGetGeometry</function></olink>; 464it returns 0 in those cases. Otherwise, it prints the default error message, 465and returns a non-zero value if the caller should consider exiting, 466and 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> 474To use the functions defined in this section, you should include the header 475file 476<<filename class='headerfile'>X11/Xmu/SysUtil.h</filename>> 477<indexterm> 478<primary><filename class='headerfile'>X11/Xmu/SysUtil.h</filename></primary> 479</indexterm> 480and 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> 498returns the host name 499 </para></listitem> 500 </varlistentry> 501 <varlistentry> 502 <term><parameter>maxlen</parameter></term> 503 <listitem><para> 504specifies the length of <parameter>buf</parameter> 505 </para></listitem> 506 </varlistentry> 507 </variablelist> 508 509This function stores the null terminated name of the local host in 510<parameter>buf</parameter>, and 511returns length of the name. This function hides operating system differences, 512such 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> 532string to write output to 533 </para></listitem> 534 </varlistentry> 535 <varlistentry> 536 <term><parameter>size</parameter></term> 537 <listitem><para> 538specifies the size of <parameter>str</parameter> 539 </para></listitem> 540 </varlistentry> 541 </variablelist> 542 543This function was provided as a portable implementation of 544<function>snprintf</function> before all platforms could be 545relied on to provide their own. It is now deprecated in favor of 546calling <function>snprintf</function> directly and should only be used 547in 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> 557To use the functions defined in this section, you should include the header 558file 559<<filename class='headerfile'>X11/Xmu/WinUtil.h</filename>> 560<indexterm> 561<primary><filename class='headerfile'>X11/Xmu/WinUtil.h</filename></primary> 562</indexterm>. 563To use <function>XmuClientWindow</function>, you may link against either the 564libXmu or libXmuu libraries. The other functions in this section require 565linking 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> 583specifies the connection to the X server 584 </para></listitem> 585 </varlistentry> 586 <varlistentry> 587 <term><parameter>w</parameter></term> 588 <listitem><para> 589specifies the window 590 </para></listitem> 591 </varlistentry> 592 </variablelist> 593 594This function returns the 595<type>Screen</type> 596on 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> 614specifies the connection to the X server 615 </para></listitem> 616 </varlistentry> 617 <varlistentry> 618 <term><parameter>win</parameter></term> 619 <listitem><para> 620specifies the window 621 </para></listitem> 622 </varlistentry> 623 </variablelist> 624 625 <indexterm zone="XmuClientWindow"> 626 <primary><property>WM_STATE</property></primary> 627 </indexterm> 628This 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 630returned, otherwise the 631argument 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> 650specifies the connection to the X server 651 </para></listitem> 652 </varlistentry> 653 <varlistentry> 654 <term><parameter>win</parameter></term> 655 <listitem><para> 656specifies the window 657 </para></listitem> 658 </varlistentry> 659 <varlistentry> 660 <term><parameter>hints</parameter></term> 661 <listitem><para> 662specifies the new hints, or <symbol>NULL</symbol> 663 </para></listitem> 664 </varlistentry> 665 </variablelist> 666 667This function clears the 668<symbol>PPosition</symbol> 669and 670<symbol>PSize</symbol> 671flags and sets the 672<symbol>USPosition</symbol> 673and 674<symbol>USSize</symbol> 675flags in the hints structure, and then stores the hints for the 676window 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> 681and returns 682<symbol>True</symbol>. 683If <symbol>NULL</symbol> is passed for the 684hints 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> 689and are used instead, and 690<symbol>True</symbol> 691is returned; otherwise 692<symbol>False</symbol> 693is returned. 694 </para> 695 696 </sect1> 697 698 <sect1 id='Cursor_Utility_Functions'> 699<title>Cursor Utility Functions</title> 700 701 <para> 702To use the functions defined in this section, you should include the header 703file 704<<filename class='headerfile'>X11/Xmu/CurUtil.h</filename>> 705<indexterm> 706<primary><filename class='headerfile'>X11/Xmu/CurUtil.h</filename></primary> 707</indexterm> 708and 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> 725specifies the name of the cursor 726 </para></listitem> 727 </varlistentry> 728 </variablelist> 729 730This function takes the name of a standard cursor and returns its index 731in the standard cursor font. The cursor names are formed by removing the 732“<code>XC_</code>” prefix from the cursor defines listed in 733Appendix B of the Xlib 734manual. 735 </para> 736 737 </sect1> 738 739 <sect1 id='Graphics_Functions'> 740<title>Graphics Functions</title> 741 742 <para> 743To use the functions defined in this section, you should include the header 744file 745<<filename class='headerfile'>X11/Xmu/Drawing.h</filename>> 746<indexterm> 747<primary><filename class='headerfile'>X11/Xmu/Drawing.h</filename></primary> 748</indexterm> 749and 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> 774specifies the connection to the X server 775 </para></listitem> 776 </varlistentry> 777 <varlistentry> 778 <term><parameter>draw</parameter></term> 779 <listitem><para> 780specifies the drawable 781 </para></listitem> 782 </varlistentry> 783 <varlistentry> 784 <term><parameter>gc</parameter></term> 785 <listitem><para> 786specifies the GC 787 </para></listitem> 788 </varlistentry> 789 <varlistentry> 790 <term><parameter>x</parameter></term> 791 <listitem><para> 792specifies the upper left x coordinate 793 </para></listitem> 794 </varlistentry> 795 <varlistentry> 796 <term><parameter>y</parameter></term> 797 <listitem><para> 798specifies the upper left y coordinate 799 </para></listitem> 800 </varlistentry> 801 <varlistentry> 802 <term><parameter>w</parameter></term> 803 <listitem><para> 804specifies the rectangle width 805 </para></listitem> 806 </varlistentry> 807 <varlistentry> 808 <term><parameter>h</parameter></term> 809 <listitem><para> 810specifies the rectangle height 811 </para></listitem> 812 </varlistentry> 813 <varlistentry> 814 <term><parameter>ew</parameter></term> 815 <listitem><para> 816specifies the corner width 817 </para></listitem> 818 </varlistentry> 819 <varlistentry> 820 <term><parameter>eh</parameter></term> 821 <listitem><para> 822specifies the corner height 823 </para></listitem> 824 </varlistentry> 825 </variablelist> 826 827This function draws a rounded rectangle, where x, y, w, h are the dimensions 828of the overall rectangle, and ew and eh are the sizes of a bounding box that 829the corners are drawn inside of; ew should be no more than half of w, and eh 830should be no more than half of h. The current GC line attributes control 831all 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> 856specifies the connection to the X server 857 </para></listitem> 858 </varlistentry> 859 <varlistentry> 860 <term><parameter>draw</parameter></term> 861 <listitem><para> 862specifies the drawable 863 </para></listitem> 864 </varlistentry> 865 <varlistentry> 866 <term><parameter>gc</parameter></term> 867 <listitem><para> 868specifies the GC 869 </para></listitem> 870 </varlistentry> 871 <varlistentry> 872 <term><parameter>x</parameter></term> 873 <listitem><para> 874specifies the upper left x coordinate 875 </para></listitem> 876 </varlistentry> 877 <varlistentry> 878 <term><parameter>y</parameter></term> 879 <listitem><para> 880specifies the upper left y coordinate 881 </para></listitem> 882 </varlistentry> 883 <varlistentry> 884 <term><parameter>w</parameter></term> 885 <listitem><para> 886specifies the rectangle width 887 </para></listitem> 888 </varlistentry> 889 <varlistentry> 890 <term><parameter>h</parameter></term> 891 <listitem><para> 892specifies the rectangle height 893 </para></listitem> 894 </varlistentry> 895 <varlistentry> 896 <term><parameter>ew</parameter></term> 897 <listitem><para> 898specifies the corner width 899 </para></listitem> 900 </varlistentry> 901 <varlistentry> 902 <term><parameter>eh</parameter></term> 903 <listitem><para> 904specifies the corner height 905 </para></listitem> 906 </varlistentry> 907 </variablelist> 908 909This function draws a filled rounded rectangle, where x, y, w, h are the 910dimensions of the overall rectangle, and ew and eh are the sizes of a 911bounding box that the corners are drawn inside of; ew should be no more than 912half of w, and eh should be no more than half of h. The current GC fill 913settings 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> 937specifies the connection to the X server 938 </para></listitem> 939 </varlistentry> 940 <varlistentry> 941 <term><parameter>drawable</parameter></term> 942 <listitem><para> 943specifies the drawable 944 </para></listitem> 945 </varlistentry> 946 <varlistentry> 947 <term><parameter>gcFore</parameter></term> 948 <listitem><para> 949specifies the foreground GC 950 </para></listitem> 951 </varlistentry> 952 <varlistentry> 953 <term><parameter>gcBack</parameter></term> 954 <listitem><para> 955specifies the background GC 956 </para></listitem> 957 </varlistentry> 958 <varlistentry> 959 <term><parameter>x</parameter></term> 960 <listitem><para> 961specifies the upper left x coordinate 962 </para></listitem> 963 </varlistentry> 964 <varlistentry> 965 <term><parameter>y</parameter></term> 966 <listitem><para> 967specifies the upper left y coordinate 968 </para></listitem> 969 </varlistentry> 970 <varlistentry> 971 <term><parameter>width</parameter></term> 972 <listitem><para> 973specifies the logo width 974 </para></listitem> 975 </varlistentry> 976 <varlistentry> 977 <term><parameter>height</parameter></term> 978 <listitem><para> 979specifies the logo height 980 </para></listitem> 981 </varlistentry> 982 </variablelist> 983 984This function draws the “official” X Window System logo 985(<xref linkend="xlogo"/>). The bounding box 986of the logo in the drawable is given by x, y, width, and height. The logo 987itself is filled using gcFore, and the rest of the rectangle is filled using 988gcBack. 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> 1015specifies the screen the pixmap is created on 1016 </para></listitem> 1017 </varlistentry> 1018 <varlistentry> 1019 <term><parameter>fore</parameter></term> 1020 <listitem><para> 1021specifies the foreground pixel value 1022 </para></listitem> 1023 </varlistentry> 1024 <varlistentry> 1025 <term><parameter>back</parameter></term> 1026 <listitem><para> 1027specifies the background pixel value 1028 </para></listitem> 1029 </varlistentry> 1030 <varlistentry> 1031 <term><parameter>depth</parameter></term> 1032 <listitem><para> 1033specifies the depth of the pixmap 1034 </para></listitem> 1035 </varlistentry> 1036 </variablelist> 1037 1038This function creates a two pixel by one pixel stippled pixmap of specified 1039depth on the specified screen. The pixmap is cached so that multiple 1040requests share the same pixmap. The pixmap should be freed with 1041<function>XmuReleaseStippledPixmap</function> 1042to 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> 1060specifies the screen the pixmap was created on 1061 </para></listitem> 1062 </varlistentry> 1063 <varlistentry> 1064 <term><parameter>pixmap</parameter></term> 1065 <listitem><para> 1066specifies the pixmap to free 1067 </para></listitem> 1068 </varlistentry> 1069 </variablelist> 1070 1071This 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> 1094specifies the stream to read from 1095 </para></listitem> 1096 </varlistentry> 1097 <varlistentry> 1098 <term><parameter>width</parameter></term> 1099 <listitem><para> 1100returns the width of the bitmap 1101 </para></listitem> 1102 </varlistentry> 1103 <varlistentry> 1104 <term><parameter>height</parameter></term> 1105 <listitem><para> 1106returns the height of the bitmap 1107 </para></listitem> 1108 </varlistentry> 1109 <varlistentry> 1110 <term><parameter>datap</parameter></term> 1111 <listitem><para> 1112returns the parsed bitmap data 1113 </para></listitem> 1114 </varlistentry> 1115 <varlistentry> 1116 <term><parameter>x_hot</parameter></term> 1117 <listitem><para> 1118returns the x coordinate of the hotspot 1119 </para></listitem> 1120 </varlistentry> 1121 <varlistentry> 1122 <term><parameter>y_hot</parameter></term> 1123 <listitem><para> 1124returns the y coordinate of the hotspot 1125 </para></listitem> 1126 </varlistentry> 1127 </variablelist> 1128 1129This function reads a standard bitmap file description from the specified 1130stream, and returns the parsed data in a format suitable for passing to 1131<olink targetdoc='libX11' targetptr='XCreateBitmapFromData'><function>XCreateBitmapFromData</function></olink>. 1132The return value of the function has the same 1133interpretation 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> 1156specifies the file to read from 1157 </para></listitem> 1158 </varlistentry> 1159 <varlistentry> 1160 <term><parameter>width</parameter></term> 1161 <listitem><para> 1162returns the width of the bitmap 1163 </para></listitem> 1164 </varlistentry> 1165 <varlistentry> 1166 <term><parameter>height</parameter></term> 1167 <listitem><para> 1168returns the height of the bitmap 1169 </para></listitem> 1170 </varlistentry> 1171 <varlistentry> 1172 <term><parameter>datap</parameter></term> 1173 <listitem><para> 1174returns the parsed bitmap data 1175 </para></listitem> 1176 </varlistentry> 1177 <varlistentry> 1178 <term><parameter>x_hot</parameter></term> 1179 <listitem><para> 1180returns the x coordinate of the hotspot 1181 </para></listitem> 1182 </varlistentry> 1183 <varlistentry> 1184 <term><parameter>y_hot</parameter></term> 1185 <listitem><para> 1186returns the y coordinate of the hotspot 1187 </para></listitem> 1188 </varlistentry> 1189 </variablelist> 1190 1191This function reads a standard bitmap file description from the specified 1192file, and returns the parsed data in a format suitable for passing to 1193<olink targetdoc='libX11' targetptr='XCreateBitmapFromData'><function>XCreateBitmapFromData</function></olink>. 1194The return value of the function has the same 1195interpretation 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> 1220specifies the screen the pixmap is created on 1221 </para></listitem> 1222 </varlistentry> 1223 <varlistentry> 1224 <term><parameter>name</parameter></term> 1225 <listitem><para> 1226specifies the file to read from 1227 </para></listitem> 1228 </varlistentry> 1229 <varlistentry> 1230 <term><parameter>srcname</parameter></term> 1231 <listitem><para> 1232returns the full filename of the bitmap 1233 </para></listitem> 1234 </varlistentry> 1235 <varlistentry> 1236 <term><parameter>srcnamelen</parameter></term> 1237 <listitem><para> 1238specifies the length of the srcname buffer 1239 </para></listitem> 1240 </varlistentry> 1241 <varlistentry> 1242 <term><parameter>width</parameter></term> 1243 <listitem><para> 1244returns the width of the bitmap 1245 </para></listitem> 1246 </varlistentry> 1247 <varlistentry> 1248 <term><parameter>height</parameter></term> 1249 <listitem><para> 1250returns the height of the bitmap 1251 </para></listitem> 1252 </varlistentry> 1253 <varlistentry> 1254 <term><parameter>xhotp</parameter></term> 1255 <listitem><para> 1256returns the x coordinate of the hotspot 1257 </para></listitem> 1258 </varlistentry> 1259 <varlistentry> 1260 <term><parameter>yhotp</parameter></term> 1261 <listitem><para> 1262returns the y coordinate of the hotspot 1263 </para></listitem> 1264 </varlistentry> 1265 </variablelist> 1266 1267This function reads a file in standard bitmap file format, using 1268<olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>, 1269and returns the created bitmap. The filename may be 1270absolute, 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 1275BitmapFilePath. If the resource is not defined, the default value is the 1276build symbol BITMAPDIR, which is typically 1277"<filename class="directory">/usr/include/X11/bitmaps</filename>". 1278If <parameter>srcnamelen</parameter> is greater than zero and 1279<parameter>srcname</parameter> is not <symbol>NULL</symbol>, 1280the null terminated filename will be copied into 1281<parameter>srcname</parameter>. The size and hotspot of the bitmap are 1282also 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> 1306specifies the connection to the X server 1307 </para></listitem> 1308 </varlistentry> 1309 <varlistentry> 1310 <term><parameter>screen</parameter></term> 1311 <listitem><para> 1312specifies the screen the pixmap is created on 1313 </para></listitem> 1314 </varlistentry> 1315 <varlistentry> 1316 <term><parameter>bitmap</parameter></term> 1317 <listitem><para> 1318specifies the bitmap source 1319 </para></listitem> 1320 </varlistentry> 1321 <varlistentry> 1322 <term><parameter>width</parameter></term> 1323 <listitem><para> 1324specifies the width of the pixmap 1325 </para></listitem> 1326 </varlistentry> 1327 <varlistentry> 1328 <term><parameter>height</parameter></term> 1329 <listitem><para> 1330specifies the height of the pixmap 1331 </para></listitem> 1332 </varlistentry> 1333 <varlistentry> 1334 <term><parameter>depth</parameter></term> 1335 <listitem><para> 1336specifies the depth of the pixmap 1337 </para></listitem> 1338 </varlistentry> 1339 <varlistentry> 1340 <term><parameter>fore</parameter></term> 1341 <listitem><para> 1342specifies the foreground pixel value 1343 </para></listitem> 1344 </varlistentry> 1345 <varlistentry> 1346 <term><parameter>back</parameter></term> 1347 <listitem><para> 1348specifies the background pixel value 1349 </para></listitem> 1350 </varlistentry> 1351 </variablelist> 1352 1353This function creates a pixmap of the specified width, height, and depth, on 1354the same screen as the specified drawable, and then performs an 1355<olink targetdoc='libX11' targetptr='XCopyPlane'><function>XCopyPlane</function></olink> 1356from the specified bitmap to the pixmap, 1357using the specified foreground and background pixel values. 1358The created pixmap is returned. 1359 </para> 1360 1361 </sect1> 1362 1363 <sect1 id='Selection_Functions'> 1364<title>Selection Functions</title> 1365 1366 <para> 1367To use the functions defined in this section, you should include the header 1368file 1369<<filename class='headerfile'>X11/Xmu/StdSel.h</filename>> 1370<indexterm> 1371<primary><filename class='headerfile'>X11/Xmu/StdSel.h</filename></primary> 1372</indexterm> 1373and 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> 1397specifies the widget which currently owns the selection 1398 </para></listitem> 1399 </varlistentry> 1400 <varlistentry> 1401 <term><parameter>time</parameter></term> 1402 <listitem><para> 1403specifies the time at which the selection was established 1404 </para></listitem> 1405 </varlistentry> 1406 <varlistentry> 1407 <term><parameter>selection</parameter></term> 1408 <listitem><para> 1409this argument is ignored 1410 </para></listitem> 1411 </varlistentry> 1412 <varlistentry> 1413 <term><parameter>target</parameter></term> 1414 <listitem><para> 1415specifies the target type of the selection 1416 </para></listitem> 1417 </varlistentry> 1418 <varlistentry> 1419 <term><parameter>type</parameter></term> 1420 <listitem><para> 1421returns the property type of the converted value 1422 </para></listitem> 1423 </varlistentry> 1424 <varlistentry> 1425 <term><parameter>value</parameter></term> 1426 <listitem><para> 1427returns the converted value 1428 </para></listitem> 1429 </varlistentry> 1430 <varlistentry> 1431 <term><parameter>length</parameter></term> 1432 <listitem><para> 1433returns the number of elements in the converted value 1434 </para></listitem> 1435 </varlistentry> 1436 <varlistentry> 1437 <term><parameter>format</parameter></term> 1438 <listitem><para> 1439returns the size in bits of the elements</para> 1440 </listitem> 1441 </varlistentry> 1442 </variablelist> 1443 1444This function converts the following standard selections: CLASS, 1445CLIENT_WINDOW, DECNET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS, 1446TARGETS, TIMESTAMP, and USER. It returns 1447<symbol>True</symbol> 1448if 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> 1457To use the functions defined in this section, you should include the header 1458file 1459<<filename class='headerfile'>X11/Xmu/Converters.h</filename>> 1460<indexterm> 1461<primary><filename class='headerfile'>X11/Xmu/Converters.h</filename></primary> 1462</indexterm> 1463and 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> 1483this argument is ignored 1484 </para></listitem> 1485 </varlistentry> 1486 <varlistentry> 1487 <term><parameter>num_args</parameter></term> 1488 <listitem><para> 1489this argument is ignored 1490 </para></listitem> 1491 </varlistentry> 1492 <varlistentry> 1493 <term><parameter>fromVal</parameter></term> 1494 <listitem><para> 1495the function to convert 1496 </para></listitem> 1497 </varlistentry> 1498 <varlistentry> 1499 <term><parameter>toVal</parameter></term> 1500 <listitem><para> 1501the place to store the converted value 1502 </para></listitem> 1503 </varlistentry> 1504 </variablelist> 1505 1506This function converts a callback procedure to a callback list containing 1507that procedure, with <symbol>NULL</symbol> closure data. To use this converter, include the 1508following in your widget's ClassInitialize procedure: 1509 1510 <programlisting> 1511XtAddConverter(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> 1532this argument is ignored 1533 </para></listitem> 1534 </varlistentry> 1535 <varlistentry> 1536 <term><parameter>num_args</parameter></term> 1537 <listitem><para> 1538this 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> 1544specifies the string to convert 1545 </para></listitem> 1546 </varlistentry> 1547 <varlistentry> 1548 <term><parameter>toVal</parameter></term> 1549 <listitem><para> 1550returns the converted value 1551 </para></listitem> 1552 </varlistentry> 1553 </variablelist> 1554 1555 <indexterm zone="XmuCvtStringToBackingStore"> 1556 <primary>backing-store</primary> 1557 </indexterm> 1558This function converts a string to a backing-store integer as defined in 1559<<filename class='headerfile'>X11/X.h</filename>>. 1560The string "notUseful" converts to 1561<symbol>NotUseful</symbol>, 1562"whenMapped" converts to 1563<symbol>WhenMapped</symbol>, 1564and "always" converts to 1565<symbol>Always</symbol>. 1566The string "default" converts to the value 1567<symbol>Always</symbol> + 1568<symbol>WhenMapped</symbol> + 1569<symbol>NotUseful</symbol>. 1570The case of the string does not matter. 1571To use this converter, include the following 1572in your widget's ClassInitialize procedure: 1573 1574 <programlisting> 1575XtAddConverter(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> 1596the 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> 1602must be the value 1 1603 </para></listitem> 1604 </varlistentry> 1605 <varlistentry> 1606 <term><parameter>fromVal</parameter></term> 1607 <listitem><para> 1608specifies the string to convert 1609 </para></listitem> 1610 </varlistentry> 1611 <varlistentry> 1612 <term><parameter>toVal</parameter></term> 1613 <listitem><para> 1614returns the converted value 1615 </para></listitem> 1616 </varlistentry> 1617 </variablelist> 1618 1619 <indexterm zone="XmuCvtStringToBitmap"> 1620 <primary>window manager icons</primary> 1621 </indexterm> 1622This function creates a bitmap (a Pixmap of depth one) suitable for window 1623manager icons. The string argument is the name of a file in standard bitmap 1624file format. For the possible filename specifications, see 1625<link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>. 1626To use this converter, include the following in your widget's 1627ClassInitialize procedure: 1628 1629 <programlisting> 1630static XtConvertArgRec screenConvertArg[] = { 1631 {XtBaseOffset, (XtPointer)XtOffset(Widget, core.screen), sizeof(Screen *)} 1632}; 1633 1634XtAddConverter(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> 1658specifies the display to use for conversion warnings 1659 </para></listitem> 1660 </varlistentry> 1661 <varlistentry> 1662 <term><parameter>args</parameter></term> 1663 <listitem><para> 1664specifies the required conversion arguments 1665 </para></listitem> 1666 </varlistentry> 1667 <varlistentry> 1668 <term><parameter>num_args</parameter></term> 1669 <listitem><para> 1670specifies 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> 1676specifies the string to convert 1677 </para></listitem> 1678 </varlistentry> 1679 <varlistentry> 1680 <term><parameter>toVal</parameter></term> 1681 <listitem><para> 1682returns the converted value 1683 </para></listitem> 1684 </varlistentry> 1685 <varlistentry> 1686 <term><parameter>data</parameter></term> 1687 <listitem><para> 1688this argument is ignored 1689 </para></listitem> 1690 </varlistentry> 1691 </variablelist> 1692 1693 <indexterm zone="XmuCvtStringToColorCursor"> 1694 <primary><type>Cursor</type></primary> 1695 </indexterm> 1696This function converts a string to a 1697<type>Cursor</type> 1698with the foreground and background pixels specified by the conversion 1699arguments. The string can either be a 1700standard cursor name formed by removing the <code>“XC_”</code> 1701prefix from any of the 1702cursor defines listed in Appendix B of the Xlib Manual, a font name and 1703glyph index in decimal of the form "FONT fontname index [[font] index]", 1704or a bitmap filename acceptable to 1705<link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>. 1706To use this converter, include 1707the following in the widget ClassInitialize procedure: 1708 1709 <programlisting> 1710static 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 1720XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor, 1721 colorCursorConvertArgs, XtNumber(colorCursorConvertArgs), 1722 XtCacheByDisplay, NULL); 1723 </programlisting> 1724 1725The widget must recognize XtNpointerColor and XtNpointerColorBackground as 1726resources, or specify other appropriate foreground and background resources. 1727The widget's Realize and SetValues methods must cause the converter to be 1728invoked with the appropriate arguments when one of the foreground, 1729background, or cursor resources has changed, or when the window is created, 1730and 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> 1750specifies the required conversion argument, the screen 1751 </para></listitem> 1752 </varlistentry> 1753 <varlistentry> 1754 <term><parameter>num_args</parameter></term> 1755 <listitem><para> 1756specifies 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> 1762specifies the string to convert 1763 </para></listitem> 1764 </varlistentry> 1765 <varlistentry> 1766 <term><parameter>toVal</parameter></term> 1767 <listitem><para> 1768returns the converted value 1769 </para></listitem> 1770 </varlistentry> 1771 </variablelist> 1772 1773 <indexterm zone="XmuCvtStringToCursor"> 1774 <primary><type>Cursor</type></primary> 1775 </indexterm> 1776This function converts a string to a 1777<type>Cursor</type>. 1778The string can either be a 1779standard cursor name formed by removing the <code>“XC_”</code> 1780prefix from any of the 1781cursor defines listed in Appendix B of the Xlib Manual, a font name and 1782glyph index in decimal of the form "FONT fontname index [[font] index]", or 1783a bitmap filename acceptable to 1784<link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>. 1785To use this converter, include 1786the following in your widget's ClassInitialize procedure: 1787 1788 <programlisting> 1789static XtConvertArgRec screenConvertArg[] = { 1790 {XtBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.screen), sizeof(Screen *)} 1791}; 1792 1793XtAddConverter(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> 1815this argument is ignored 1816 </para></listitem> 1817 </varlistentry> 1818 <varlistentry> 1819 <term><parameter>num_args</parameter></term> 1820 <listitem><para> 1821this 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> 1827specifies the string to convert 1828 </para></listitem> 1829 </varlistentry> 1830 <varlistentry> 1831 <term><parameter>toVal</parameter></term> 1832 <listitem><para> 1833returns the converted value 1834 </para></listitem> 1835 </varlistentry> 1836 </variablelist> 1837 1838 <indexterm zone="XmuCvtStringToGravity"> 1839 <primary><type>XtGravity</type></primary> 1840 </indexterm> 1841This function converts a string to an 1842<type>XtGravity</type> 1843enumeration value. The string "forget" and a <symbol>NULL</symbol> value convert to 1844<symbol>ForgetGravity</symbol>, 1845"NorthWestGravity" converts to 1846<symbol>NorthWestGravity</symbol>, 1847the strings "NorthGravity" and "top" convert to 1848<symbol>NorthGravity</symbol>, 1849"NorthEastGravity" converts to 1850<symbol>NorthEastGravity</symbol>, 1851the 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>, 1865and "UnmapGravity" converts to 1866<symbol>UnmapGravity</symbol>. 1867The case of the string does not matter. To use this converter, include 1868the following in your widget's class initialize procedure: 1869 1870 <programlisting> 1871XtAddConverter(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> 1892this argument is ignored 1893 </para></listitem> 1894 </varlistentry> 1895 <varlistentry> 1896 <term><parameter>num_args</parameter></term> 1897 <listitem><para> 1898this argument is ignored 1899 </para></listitem> 1900 </varlistentry> 1901 <varlistentry> 1902 <term><parameter>fromVal</parameter></term> 1903 <listitem><para> 1904specifies the string to convert 1905 </para></listitem> 1906 </varlistentry> 1907 <varlistentry> 1908 <term><parameter>toVal</parameter></term> 1909 <listitem><para> 1910returns the converted value 1911 </para></listitem> 1912 </varlistentry> 1913 </variablelist> 1914 1915 <indexterm zone="XmuCvtStringToJustify"> 1916 <primary><type>XtJustify</type></primary> 1917 </indexterm> 1918This function converts a string to an 1919<type>XtJustify</type> 1920enumeration value. The string "left" converts to 1921<symbol>XtJustifyLeft</symbol>, 1922"center" converts to 1923<symbol>XtJustifyCenter</symbol>, 1924and "right" converts to 1925<symbol>XtJustifyRight</symbol>. 1926The case of the string does not matter. To use this converter, 1927include the following in your widget's ClassInitialize procedure: 1928 1929 <programlisting> 1930XtAddConverter(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> 1951this argument is ignored 1952 </para></listitem> 1953 </varlistentry> 1954 <varlistentry> 1955 <term><parameter>num_args</parameter></term> 1956 <listitem><para> 1957this 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> 1963specifies the string to convert 1964 </para></listitem> 1965 </varlistentry> 1966 <varlistentry> 1967 <term><parameter>toVal</parameter></term> 1968 <listitem><para> 1969returns the converted value 1970 </para></listitem> 1971 </varlistentry> 1972 </variablelist> 1973 1974This function converts a string to an integer of type long. It parses the 1975string using 1976<function>sscanf</function> 1977with a format of "%ld". To use this converter, include 1978the following in your widget's ClassInitialize procedure: 1979 1980 <programlisting> 1981XtAddConverter(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> 2002this argument is ignored 2003 </para></listitem> 2004 </varlistentry> 2005 <varlistentry> 2006 <term><parameter>num_args</parameter></term> 2007 <listitem><para> 2008this argument is ignored 2009 </para></listitem> 2010 </varlistentry> 2011 <varlistentry> 2012 <term><parameter>fromVal</parameter></term> 2013 <listitem><para> 2014specifies the string to convert 2015 </para></listitem> 2016 </varlistentry> 2017 <varlistentry> 2018 <term><parameter>toVal</parameter></term> 2019 <listitem><para> 2020returns the converted value 2021 </para></listitem> 2022 </varlistentry> 2023 </variablelist> 2024 2025 <indexterm zone="XmuCvtStringToOrientation"> 2026 <primary><type>XtOrientation</type></primary> 2027 </indexterm> 2028This function converts a string to an 2029<type>XtOrientation</type> 2030enumeration value. The string "horizontal" converts to 2031<symbol>XtorientHorizontal</symbol> 2032and "vertical" converts to 2033<symbol>XtorientVertical</symbol>. 2034The case of the string does not matter. To use this converter, 2035include the following in your widget's ClassInitialize procedure: 2036 2037 <programlisting> 2038XtAddConverter(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> 2061the display to use for conversion warnings 2062 </para></listitem> 2063 </varlistentry> 2064 <varlistentry> 2065 <term><parameter>args</parameter></term> 2066 <listitem><para> 2067this argument is ignored 2068 </para></listitem> 2069 </varlistentry> 2070 <varlistentry> 2071 <term><parameter>num_args</parameter></term> 2072 <listitem><para> 2073this argument is ignored 2074 </para></listitem> 2075 </varlistentry> 2076 <varlistentry> 2077 <term><parameter>fromVal</parameter></term> 2078 <listitem><para> 2079the value to convert from 2080 </para></listitem> 2081 </varlistentry> 2082 <varlistentry> 2083 <term><parameter>toVal</parameter></term> 2084 <listitem><para> 2085the place to store the converted value 2086 </para></listitem> 2087 </varlistentry> 2088 <varlistentry> 2089 <term><parameter>data</parameter></term> 2090 <listitem><para> 2091this argument is ignored 2092 </para></listitem> 2093 </varlistentry> 2094 </variablelist> 2095 2096This 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>, 2103and "roundedRectangle" converts to 2104<symbol>XmuShapeRoundedRectangle</symbol>. 2105The case of the string does not matter. To use this converter, 2106include the following in your widget's ClassInitialize procedure: 2107 2108 <programlisting> 2109XtSetTypeConverter(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> 2131specifies the widget to reshape 2132 </para></listitem> 2133 </varlistentry> 2134 <varlistentry> 2135 <term><parameter>shape_style</parameter></term> 2136 <listitem><para> 2137specifies the new shape 2138 </para></listitem> 2139 </varlistentry> 2140 <varlistentry> 2141 <term><parameter>corner_width</parameter></term> 2142 <listitem><para> 2143specifies the width of the rounded rectangle corner 2144 </para></listitem> 2145 </varlistentry> 2146 <varlistentry> 2147 <term><parameter>corner_height</parameter></term> 2148 <listitem><para> 2149specified 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> 2157This function reshapes the specified widget, using the Shape extension, to a 2158rectangle, oval, ellipse, or rounded rectangle, as specified by shape_style 2159( 2160<symbol>XmuShapeRectangle</symbol>, 2161<symbol>XmuShapeOval</symbol>, 2162<symbol>XmuShapeEllipse</symbol>, 2163and 2164<symbol>XmuShapeRoundedRectangle</symbol>, 2165respectively). 2166The shape is bounded by the outside edges of the rectangular extents of the 2167widget. If the shape is a rounded rectangle, corner_width and corner_height 2168specify the size of the bounding box that the corners are drawn inside of 2169(see 2170<link linkend="XmuFillRoundedRectangle"><function>XmuFillRoundedRectangle</function></link>); 2171otherwise, corner_width and corner_height are ignored. 2172The 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> 2192the sole argument is the parent Widget 2193 </para></listitem> 2194 </varlistentry> 2195 <varlistentry> 2196 <term><parameter>num_args</parameter></term> 2197 <listitem><para> 2198this argument must be 1 2199 </para></listitem> 2200 </varlistentry> 2201 <varlistentry> 2202 <term><parameter>fromVal</parameter></term> 2203 <listitem><para> 2204specifies the string to convert 2205 </para></listitem> 2206 </varlistentry> 2207 <varlistentry> 2208 <term><parameter>toVal</parameter></term> 2209 <listitem><para> 2210returns the converted value 2211 </para></listitem> 2212 </varlistentry> 2213 </variablelist> 2214 2215This function converts a string to an immediate child widget of the parent 2216widget passed as an argument. Note that this converter only works for 2217child widgets that have already been created; there is no lazy evaluation. 2218The string is first compared against the 2219names of the normal and popup children, and if a match is found the 2220corresponding child is returned. If no match is found, the string is 2221compared against the classes of the normal and popup children, and if a 2222match is found the corresponding child is returned. The case of the string 2223is significant. To use this converter, include the following in your 2224widget's ClassInitialize procedure: 2225 2226 <programlisting> 2227static XtConvertArgRec parentCvtArg[] = { 2228 {XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)}, 2229}; 2230 2231XtAddConverter(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> 2255the display to use for conversion warnings 2256 </para></listitem> 2257 </varlistentry> 2258 <varlistentry> 2259 <term><parameter>args</parameter></term> 2260 <listitem><para> 2261the sole argument is the parent Widget 2262 </para></listitem> 2263 </varlistentry> 2264 <varlistentry> 2265 <term><parameter>num_args</parameter></term> 2266 <listitem><para> 2267this 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> 2273specifies the string to convert 2274 </para></listitem> 2275 </varlistentry> 2276 <varlistentry> 2277 <term><parameter>toVal</parameter></term> 2278 <listitem><para> 2279returns the converted value 2280 </para></listitem> 2281 </varlistentry> 2282 <varlistentry> 2283 <term><parameter>data</parameter></term> 2284 <listitem><para> 2285this argument is ignored 2286 </para></listitem> 2287 </varlistentry> 2288 </variablelist> 2289 2290This converter is identical in functionality to 2291<link linkend="XmuCvtStringToWidget"><function>XmuCvtStringToWidget</function></link>, except 2292that it is a new-style converter, allowing the specification of a cache type 2293at the time of registration. 2294Most widgets will not cache the conversion results, as the application may 2295dynamically create and destroy widgets, which would cause cached values to 2296become illegal. To use this converter, include the following in the widget's 2297class initialize procedure: 2298 2299 <programlisting> 2300static XtConvertArgRec parentCvtArg[] = { 2301 {XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.parent), 2302 sizeof(Widget)} 2303}; 2304 2305XtSetTypeConverter(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> 2317To use the functions defined in this section, you should include the header 2318file 2319<<filename class='headerfile'>X11/Xmu/CharSet.h</filename>> 2320<indexterm> 2321<primary><filename class='headerfile'>X11/Xmu/CharSet.h</filename></primary> 2322</indexterm> 2323and link against the libXmu or libXmuu library. 2324</para> 2325 2326 <warning><para> 2327The functions in this section are <emphasis remap='B'>deprecated</emphasis> 2328because they don't work in most locales now supported by X11; most platforms 2329provide 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> 2347returns the string copy 2348 </para></listitem> 2349 </varlistentry> 2350 <varlistentry> 2351 <term><parameter>src</parameter></term> 2352 <listitem><para> 2353specifies the string to copy 2354 </para></listitem> 2355 </varlistentry> 2356 </variablelist> 2357 2358This function copies a null terminated string from src to dst (including the 2359null), changing all Latin-1 uppercase letters to lowercase. The string is 2360assumed to be encoded using ISO 8859-1. 2361 </para> 2362 2363 <para> 2364Note that like <function>strcpy</function> the caller is responsible for 2365ensuring the size of <parameter>dst</parameter> is at least as large as the 2366size 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> 2385returns the string copy 2386 </para></listitem> 2387 </varlistentry> 2388 <varlistentry> 2389 <term><parameter>src</parameter></term> 2390 <listitem><para> 2391specifies the string to copy 2392 </para></listitem> 2393 </varlistentry> 2394 <varlistentry> 2395 <term><parameter>size</parameter></term> 2396 <listitem><para> 2397maximum number of characters (including the null terminator) to write to dst 2398 </para></listitem> 2399 </varlistentry> 2400 </variablelist> 2401 2402This function copies up to <code><parameter>size</parameter> - 1</code> 2403characters of a null terminated string from <parameter>src</parameter> 2404to <parameter>dst</parameter>, and terminates it with a null, 2405changing all Latin-1 uppercase letters to lowercase. The string is 2406assumed 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> 2424returns the string copy 2425 </para></listitem> 2426 </varlistentry> 2427 <varlistentry> 2428 <term><parameter>src</parameter></term> 2429 <listitem><para> 2430specifies the string to copy 2431 </para></listitem> 2432 </varlistentry> 2433 </variablelist> 2434 2435This function copies a null terminated string from src to dst (including the 2436null), changing all Latin-1 lowercase letters to uppercase. The string is 2437assumed to be encoded using ISO 8859-1. 2438 </para> 2439 2440 <para> 2441Note that like <function>strcpy</function> the caller is responsible for 2442ensuring the size of <parameter>dst</parameter> is at least as large as the 2443size 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> 2462returns the string copy 2463 </para></listitem> 2464 </varlistentry> 2465 <varlistentry> 2466 <term><parameter>src</parameter></term> 2467 <listitem><para> 2468specifies the string to copy 2469 </para></listitem> 2470 </varlistentry> 2471 <varlistentry> 2472 <term><parameter>size</parameter></term> 2473 <listitem><para> 2474maximum number of characters (including the null terminator) to write to dst 2475 </para></listitem> 2476 </varlistentry> 2477 </variablelist> 2478 2479This function copies up to <code><parameter>size</parameter> - 1</code> 2480characters of a null terminated string from <parameter>src</parameter> 2481to <parameter>dst</parameter>, and terminates it with a null, 2482changing all Latin-1 lowercase letters to uppercase. The string is 2483assumed 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> 2507specifies a string to compare 2508 </para></listitem> 2509 </varlistentry> 2510 </variablelist> 2511 2512This function compares two null terminated Latin-1 strings, ignoring case 2513differences, and returns an integer greater than, equal to, or less than 0, 2514according to whether first is lexicographically greater than, equal to, or 2515less than second. The two strings are assumed to be encoded using ISO 25168859-1. 2517 </para> 2518 </sect1> 2519 2520 <sect1 id='Keyboard_Event_Translation_Functions'> 2521<title>Keyboard Event Translation Functions</title> 2522 2523 <para> 2524To use the functions defined in this section, you should include the header 2525file 2526<<filename class='headerfile'>X11/Xmu/Lookup.h</filename>> 2527<indexterm> 2528<primary><filename class='headerfile'>X11/Xmu/Lookup.h</filename></primary> 2529</indexterm>. 2530and link against the libXmu library. 2531 </para> 2532 2533 <warning><para> 2534The functions in this section are <emphasis remap='B'>deprecated</emphasis> because they don't work 2535in most locales now supported by X11; the function 2536<olink targetdoc='libX11' targetptr='XmbLookupString'><function>XmbLookupString</function></olink> 2537provides 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> 2558specifies the key event 2559 </para></listitem> 2560 </varlistentry> 2561 <varlistentry> 2562 <term><parameter>buffer</parameter></term> 2563 <listitem><para> 2564returns the translated characters 2565 </para></listitem> 2566 </varlistentry> 2567 <varlistentry> 2568 <term><parameter>nbytes</parameter></term> 2569 <listitem><para> 2570specifies the length of the buffer 2571 </para></listitem> 2572 </varlistentry> 2573 <varlistentry> 2574 <term><parameter>keysym</parameter></term> 2575 <listitem><para> 2576returns the computed KeySym, or None 2577 </para></listitem> 2578 </varlistentry> 2579 <varlistentry> 2580 <term><parameter>status</parameter></term> 2581 <listitem><para> 2582specifies or returns the compose state 2583 </para></listitem> 2584 </varlistentry> 2585 </variablelist> 2586 2587This function is identical to 2588<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2589and 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> 2610specifies the key event 2611 </para></listitem> 2612 </varlistentry> 2613 <varlistentry> 2614 <term><parameter>buffer</parameter></term> 2615 <listitem><para> 2616returns the translated characters 2617 </para></listitem> 2618 </varlistentry> 2619 <varlistentry> 2620 <term><parameter>nbytes</parameter></term> 2621 <listitem><para> 2622specifies the length of the buffer 2623 </para></listitem> 2624 </varlistentry> 2625 <varlistentry> 2626 <term><parameter>keysym</parameter></term> 2627 <listitem><para> 2628returns the computed KeySym, or None 2629 </para></listitem> 2630 </varlistentry> 2631 <varlistentry> 2632 <term><parameter>status</parameter></term> 2633 <listitem><para> 2634specifies or returns the compose state 2635 </para></listitem> 2636 </varlistentry> 2637 </variablelist> 2638 2639This function is similar to 2640<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2641except that it maps a key event 2642to 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> 2663specifies the key event 2664 </para></listitem> 2665 </varlistentry> 2666 <varlistentry> 2667 <term><parameter>buffer</parameter></term> 2668 <listitem><para> 2669returns the translated characters 2670 </para></listitem> 2671 </varlistentry> 2672 <varlistentry> 2673 <term><parameter>nbytes</parameter></term> 2674 <listitem><para> 2675specifies the length of the buffer 2676 </para></listitem> 2677 </varlistentry> 2678 <varlistentry> 2679 <term><parameter>keysym</parameter></term> 2680 <listitem><para> 2681returns the computed KeySym, or None 2682 </para></listitem> 2683 </varlistentry> 2684 <varlistentry> 2685 <term><parameter>status</parameter></term> 2686 <listitem><para> 2687specifies or returns the compose state 2688 </para></listitem> 2689 </varlistentry> 2690 </variablelist> 2691 2692This function is similar to 2693<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2694except that it maps a key event 2695to 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> 2716specifies the key event 2717 </para></listitem> 2718 </varlistentry> 2719 <varlistentry> 2720 <term><parameter>buffer</parameter></term> 2721 <listitem><para> 2722returns the translated characters 2723 </para></listitem> 2724 </varlistentry> 2725 <varlistentry> 2726 <term><parameter>nbytes</parameter></term> 2727 <listitem><para> 2728specifies the length of the buffer 2729 </para></listitem> 2730 </varlistentry> 2731 <varlistentry> 2732 <term><parameter>keysym</parameter></term> 2733 <listitem><para> 2734returns the computed KeySym, or None 2735 </para></listitem> 2736 </varlistentry> 2737 <varlistentry> 2738 <term><parameter>status</parameter></term> 2739 <listitem><para> 2740specifies or returns the compose state 2741 </para></listitem> 2742 </varlistentry> 2743 </variablelist> 2744 2745This function is similar to 2746<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2747except that it maps a key event 2748to 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> 2769specifies the key event 2770 </para></listitem> 2771 </varlistentry> 2772 <varlistentry> 2773 <term><parameter>buffer</parameter></term> 2774 <listitem><para> 2775returns the translated characters 2776 </para></listitem> 2777 </varlistentry> 2778 <varlistentry> 2779 <term><parameter>nbytes</parameter></term> 2780 <listitem><para> 2781specifies the length of the buffer 2782 </para></listitem> 2783 </varlistentry> 2784 <varlistentry> 2785 <term><parameter>keysym</parameter></term> 2786 <listitem><para> 2787returns the computed KeySym, or None 2788 </para></listitem> 2789 </varlistentry> 2790 <varlistentry> 2791 <term><parameter>status</parameter></term> 2792 <listitem><para> 2793specifies or returns the compose state 2794 </para></listitem> 2795 </varlistentry> 2796 </variablelist> 2797 2798This function is similar to 2799<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2800except that it maps a key event 2801to a string in an encoding consisting of Latin-1 (ISO 8859-1) and ASCII 2802control in the Graphics Left half (values 0 to 127), and Katakana in the 2803Graphics Right half (values 128 to 255), using the values from JIS 2804X201-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> 2825specifies the key event 2826 </para></listitem> 2827 </varlistentry> 2828 <varlistentry> 2829 <term><parameter>buffer</parameter></term> 2830 <listitem><para> 2831returns the translated characters 2832 </para></listitem> 2833 </varlistentry> 2834 <varlistentry> 2835 <term><parameter>nbytes</parameter></term> 2836 <listitem><para> 2837specifies the length of the buffer 2838 </para></listitem> 2839 </varlistentry> 2840 <varlistentry> 2841 <term><parameter>keysym</parameter></term> 2842 <listitem><para> 2843returns the computed KeySym, or None 2844 </para></listitem> 2845 </varlistentry> 2846 <varlistentry> 2847 <term><parameter>status</parameter></term> 2848 <listitem><para> 2849specifies or returns the compose state 2850 </para></listitem> 2851 </varlistentry> 2852 </variablelist> 2853 2854This function is similar to 2855<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2856except that it maps a key event 2857to 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> 2878specifies the key event 2879 </para></listitem> 2880 </varlistentry> 2881 <varlistentry> 2882 <term><parameter>buffer</parameter></term> 2883 <listitem><para> 2884returns the translated characters 2885 </para></listitem> 2886 </varlistentry> 2887 <varlistentry> 2888 <term><parameter>nbytes</parameter></term> 2889 <listitem><para> 2890specifies the length of the buffer 2891 </para></listitem> 2892 </varlistentry> 2893 <varlistentry> 2894 <term><parameter>keysym</parameter></term> 2895 <listitem><para> 2896returns the computed KeySym, or None 2897 </para></listitem> 2898 </varlistentry> 2899 <varlistentry> 2900 <term><parameter>status</parameter></term> 2901 <listitem><para> 2902specifies or returns the compose state 2903 </para></listitem> 2904 </varlistentry> 2905 </variablelist> 2906 2907This function is similar to 2908<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2909except that it maps a key event 2910to 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> 2931specifies the key event 2932 </para></listitem> 2933 </varlistentry> 2934 <varlistentry> 2935 <term><parameter>buffer</parameter></term> 2936 <listitem><para> 2937returns the translated characters 2938 </para></listitem> 2939 </varlistentry> 2940 <varlistentry> 2941 <term><parameter>nbytes</parameter></term> 2942 <listitem><para> 2943specifies the length of the buffer 2944 </para></listitem> 2945 </varlistentry> 2946 <varlistentry> 2947 <term><parameter>keysym</parameter></term> 2948 <listitem><para> 2949returns the computed KeySym, or None 2950 </para></listitem> 2951 </varlistentry> 2952 <varlistentry> 2953 <term><parameter>status</parameter></term> 2954 <listitem><para> 2955specifies or returns the compose state 2956 </para></listitem> 2957 </varlistentry> 2958 </variablelist> 2959 2960This function is similar to 2961<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 2962except that it maps a key event 2963to 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> 2984specifies the key event 2985 </para></listitem> 2986 </varlistentry> 2987 <varlistentry> 2988 <term><parameter>buffer</parameter></term> 2989 <listitem><para> 2990returns the translated characters 2991 </para></listitem> 2992 </varlistentry> 2993 <varlistentry> 2994 <term><parameter>nbytes</parameter></term> 2995 <listitem><para> 2996specifies the length of the buffer 2997 </para></listitem> 2998 </varlistentry> 2999 <varlistentry> 3000 <term><parameter>keysym</parameter></term> 3001 <listitem><para> 3002returns the computed KeySym, or None 3003 </para></listitem> 3004 </varlistentry> 3005 <varlistentry> 3006 <term><parameter>status</parameter></term> 3007 <listitem><para> 3008specifies or returns the compose state 3009 </para></listitem> 3010 </varlistentry> 3011 </variablelist> 3012 3013This function is similar to 3014<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 3015except that it maps a key event 3016to 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> 3037specifies the key event 3038 </para></listitem> 3039 </varlistentry> 3040 <varlistentry> 3041 <term><parameter>buffer</parameter></term> 3042 <listitem><para> 3043returns the translated characters 3044 </para></listitem> 3045 </varlistentry> 3046 <varlistentry> 3047 <term><parameter>nbytes</parameter></term> 3048 <listitem><para> 3049specifies the length of the buffer 3050 </para></listitem> 3051 </varlistentry> 3052 <varlistentry> 3053 <term><parameter>keysym</parameter></term> 3054 <listitem><para> 3055returns the computed KeySym, or None 3056 </para></listitem> 3057 </varlistentry> 3058 <varlistentry> 3059 <term><parameter>status</parameter></term> 3060 <listitem><para> 3061specifies or returns the compose state 3062 </para></listitem> 3063 </varlistentry> 3064 </variablelist> 3065 3066This function is similar to 3067<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 3068except that it maps a key event 3069to 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> 3090specifies the key event 3091 </para></listitem> 3092 </varlistentry> 3093 <varlistentry> 3094 <term><parameter>buffer</parameter></term> 3095 <listitem><para> 3096returns the translated characters 3097 </para></listitem> 3098 </varlistentry> 3099 <varlistentry> 3100 <term><parameter>nbytes</parameter></term> 3101 <listitem><para> 3102specifies the length of the buffer 3103 </para></listitem> 3104 </varlistentry> 3105 <varlistentry> 3106 <term><parameter>keysym</parameter></term> 3107 <listitem><para> 3108returns the computed KeySym, or None 3109 </para></listitem> 3110 </varlistentry> 3111 <varlistentry> 3112 <term><parameter>status</parameter></term> 3113 <listitem><para> 3114specifies or returns the compose state 3115 </para></listitem> 3116 </varlistentry> 3117 </variablelist> 3118 3119This function is similar to 3120<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>, 3121except 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> 3130The functions defined in this section are for parsing Compound Text strings, 3131decomposing them into individual segments. Definitions needed to use these 3132routines are in the include file 3133<<filename class='headerfile'>X11/Xmu/Xct.h</filename>> 3134<indexterm> 3135<primary><filename class='headerfile'>X11/Xmu/Xct.h</filename></primary> 3136</indexterm> 3137and link against the libXmu library. 3138 </para> 3139 3140 <warning><para> 3141The functions in this section are <emphasis remap='B'>deprecated</emphasis> because they shift the 3142burden for recently introduced locale encodings to the application. The 3143use of the 3144<symbol>UTF8_STRING</symbol> 3145text encoding provides a better alternative. 3146 </para></warning> 3147 3148 <para> 3149A 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> 3172the Compound Text string 3173 </para></listitem> 3174 </varlistentry> 3175 <varlistentry> 3176 <term><parameter>length</parameter></term> 3177 <listitem><para> 3178the number of bytes in string 3179 </para></listitem> 3180 </varlistentry> 3181 <varlistentry> 3182 <term><parameter>flags</parameter></term> 3183 <listitem><para> 3184parsing control flags 3185 </para></listitem> 3186 </varlistentry> 3187 </variablelist> 3188 3189This function creates an 3190<type>XctData</type> 3191structure for parsing a Compound Text 3192string. The string need not be null terminated. The following flags are 3193defined to control parsing of the string: 3194 3195 <variablelist> 3196 <varlistentry> 3197 <term><symbol>XctSingleSetSegments</symbol></term> 3198 <listitem><para> 3199This means that returned segments should contain 3200characters from only one set (C0, C1, GL, GR). When this is requested, 3201<symbol>XctSegment</symbol> 3202is never returned by 3203<function>XctNextItem</function>, 3204instead 3205<symbol>XctC0Segment</symbol>, 3206<symbol>XctC1Segment</symbol>, 3207<symbol>XctGlSegment</symbol>, 3208and 3209<symbol>XctGRSegment</symbol> 3210are returned. C0 and C1 3211segments are always returned as singleton characters. 3212 </para></listitem> 3213 </varlistentry> 3214 3215 <varlistentry> 3216 <term><symbol>XctProvideExtensions</symbol></term> 3217 <listitem><para> 3218This means that if the Compound Text string is from a 3219higher version than this code is implemented to, then syntactically correct 3220but unknown control sequences should be returned as 3221<symbol>XctExtension</symbol> 3222items by 3223<function>XctNextItem</function>. 3224If this flag is not set, and the Compound Text string version 3225indicates that extensions cannot be ignored, then each unknown control 3226sequence 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> 3234This means that if the Compound Text string is from 3235a higher version than this code is implemented to, then unknown C0 3236characters should be treated as if they were legal, and returned as C0 3237characters (regardless of how 3238<symbol>XctProvideExtensions</symbol> 3239is set) by 3240<function>XctNextItem</function>. 3241If this flag is not set, then all unknown C0 characters are treated 3242according to 3243<symbol>XctProvideExtensions</symbol>. 3244 </para></listitem> 3245 </varlistentry> 3246 3247 <varlistentry> 3248 <term><symbol>XctAcceptC1Extensions</symbol></term> 3249 <listitem><para> 3250This means that if the Compound Text string is from 3251a higher version than this code is implemented to, then unknown C1 3252characters should be treated as if they were legal, and returned as C1 3253characters (regardless of how 3254<symbol>XctProvideExtensions</symbol> 3255is set) by 3256<function>XctNextItem</function>. 3257If this flag is not set, then all unknown C1 characters are treated 3258according to 3259<symbol>XctProvideExtensions</symbol>. 3260 </para></listitem> 3261 </varlistentry> 3262 <varlistentry> 3263 <term><symbol>XctHideDirection</symbol></term> 3264 <listitem><para> 3265This means that horizontal direction changes should be 3266reported as 3267<symbol>XctHorizontal</symbol> 3268items by 3269<function>XctNextItem</function>. If this flag is not set, 3270then direction changes are not returned as items, but the current direction 3271is still maintained and reported for other items. The current direction is 3272given as an enumeration, with the values 3273<symbol>XctUnspecified</symbol>, 3274<symbol>XctLeftToRight</symbol>, 3275and 3276<symbol>XctRightToLeft</symbol>. 3277 </para></listitem> 3278 </varlistentry> 3279 <varlistentry> 3280 <term><symbol>XctFreeString</symbol></term> 3281 <listitem><para> 3282This means that 3283<function>XctFree</function> 3284should free the Compound Text string that is passed to 3285<function>XctCreate</function>. 3286If 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> 3293This means that 3294<function>XctNextItem</function> 3295should translate GR 3296segments on-the-fly into GL segments for the GR sets: GB2312.1980-1, 3297JISX0208.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> 3317specifies the Compound Text structure 3318 </para></listitem> 3319 </varlistentry> 3320 </variablelist> 3321 3322This function resets the 3323<type>XctData</type> 3324structure 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> 3341specifies the Compound Text structure 3342 </para></listitem> 3343 </varlistentry> 3344 </variablelist> 3345 3346This function parses the next “item” from the Compound Text string. The 3347return value indicates what kind of item is returned. The item itself, its 3348length, and the current contextual state, are reported as components of the 3349<type>XctData</type> 3350structure. 3351<type>XctResult</type> 3352is an enumeration, with the following values: 3353 3354 <variablelist> 3355 <varlistentry> 3356 <term><symbol>XctSegment</symbol></term> 3357 <listitem><para> 3358the 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> 3365the item contains only C0 characters. 3366 </para></listitem> 3367 </varlistentry> 3368 3369 <varlistentry> 3370 <term><symbol>XctGLSegment</symbol></term> 3371 <listitem><para> 3372the item contains only GL characters. 3373 </para></listitem> 3374 </varlistentry> 3375 3376 <varlistentry> 3377 <term><symbol>XctC1Segment</symbol></term> 3378 <listitem><para> 3379the item contains only C1 characters. 3380 </para></listitem> 3381 </varlistentry> 3382 3383 <varlistentry> 3384 <term><symbol>XctGRSegment</symbol></term> 3385 <listitem><para> 3386the item contains only GR characters. 3387 </para></listitem> 3388 </varlistentry> 3389 3390 <varlistentry> 3391 <term><symbol>XctExtendedSegment</symbol></term> 3392 <listitem><para> 3393the item contains an extended segment. 3394 </para></listitem> 3395 </varlistentry> 3396 3397 <varlistentry> 3398 <term><symbol>XctExtension</symbol></term> 3399 <listitem><para> 3400the item is an unknown extension control sequence. 3401 </para></listitem> 3402 </varlistentry> 3403 3404 <varlistentry> 3405 <term><symbol>XctHorizontal</symbol></term> 3406 <listitem><para> 3407the item indicates a change in horizontal direction or 3408depth. The new direction and depth are recorded in the 3409<type>XctData</type> 3410structure. 3411 </para></listitem> 3412 </varlistentry> 3413 3414 <varlistentry> 3415 <term><symbol>XctEndOfText</symbol></term> 3416 <listitem><para> 3417The 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> 3424the string contains a syntactic or semantic error; no further 3425parsing 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> 3435The following state values are stored in the 3436<type>XctData</type> 3437structure: 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> 3469specifies the Compound Text structure 3470 </para></listitem> 3471 </varlistentry> 3472 </variablelist> 3473 3474This function frees all data associated with the 3475<type>XctData</type> 3476structure. 3477 </para> 3478 3479 </sect1> 3480 3481 <sect1 id='CloseDisplay_Hook_Functions'> 3482<title>CloseDisplay Hook Functions</title> 3483 3484 <para> 3485To use the functions defined in this section, you should include the header 3486file 3487<<filename class='headerfile'>X11/Xmu/CloseHook.h</filename>> 3488<indexterm> 3489<primary><filename class='headerfile'>X11/Xmu/CloseHook.h</filename></primary> 3490</indexterm> 3491and 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> 3511specifies the connection to the X server 3512 </para></listitem> 3513 </varlistentry> 3514 <varlistentry> 3515 <term><parameter>func</parameter></term> 3516 <listitem><para> 3517specifies the function to call at display close 3518 </para></listitem> 3519 </varlistentry> 3520 <varlistentry> 3521 <term><parameter>arg</parameter></term> 3522 <listitem><para> 3523specifies arbitrary data to pass to <parameter>func</parameter> 3524 </para></listitem> 3525 </varlistentry> 3526 </variablelist> 3527 3528This function adds a callback for the given display. When the display is 3529closed, the given function will be called with the given display and 3530argument as: 3531 3532 <programlisting> 3533 (*func)(dpy, arg) 3534 </programlisting> 3535 </para> 3536 3537 <para> 3538The function is declared to return an int even though the value is ignored, 3539because some compilers used to have problems with functions returning void. 3540 </para> 3541 3542 <para> 3543This routine returns <symbol>NULL</symbol> if it was unable to add the 3544callback, otherwise it 3545returns 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> 3566specifies the connection to the X server 3567 </para></listitem> 3568 </varlistentry> 3569 <varlistentry> 3570 <term><parameter>handle</parameter></term> 3571 <listitem><para> 3572specifies the callback by id, or <symbol>NULL</symbol> 3573 </para></listitem> 3574 </varlistentry> 3575 <varlistentry> 3576 <term><function>func</function></term> 3577 <listitem><para> 3578specifies the callback by function 3579 </para></listitem> 3580 </varlistentry> 3581 <varlistentry> 3582 <term><parameter>arg</parameter></term> 3583 <listitem><para> 3584specifies the function data to match 3585 </para></listitem> 3586 </varlistentry> 3587 </variablelist> 3588 3589This function deletes a callback that has been added with 3590<function>XmuAddCloseDisplayHook</function>. 3591If handle is not <symbol>NULL</symbol>, it specifies the callback to 3592remove, and the func and arg parameters are ignored. If handle is <symbol>NULL</symbol>, the 3593first callback found to match the specified func and arg will be removed. 3594Returns 3595<symbol>True</symbol> 3596if 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> 3618specifies the connection to the X server 3619 </para></listitem> 3620 </varlistentry> 3621 <varlistentry> 3622 <term><parameter>handle</parameter></term> 3623 <listitem><para> 3624specifies the callback by id, or <symbol>NULL</symbol> 3625 </para></listitem> 3626 </varlistentry> 3627 <varlistentry> 3628 <term><function>func</function></term> 3629 <listitem><para> 3630specifies the callback by function 3631 </para></listitem> 3632 </varlistentry> 3633 <varlistentry> 3634 <term><parameter>arg</parameter></term> 3635 <listitem><para> 3636specifies the function data to match 3637 </para></listitem> 3638 </varlistentry> 3639 </variablelist> 3640 3641This function determines if a callback is installed. If handle is not 3642<symbol>NULL</symbol>, 3643it specifies the callback to look for, and the func and arg parameters are 3644ignored. If handle is <symbol>NULL</symbol>, the function will look for 3645any callback for the 3646specified func and arg. Returns 3647<symbol>True</symbol> 3648if 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> 3659To use the functions and types defined in this section, you should include the 3660header file 3661<<filename class='headerfile'>X11/Xmu/DisplayQue.h</filename>> 3662<indexterm> 3663<primary><filename class='headerfile'>X11/Xmu/DisplayQue.h</filename></primary> 3664</indexterm> 3665and link against the libXmu library. 3666<filename class='headerfile'>DisplayQue.h</filename> defines the following 3667types: 3668 3669 <indexterm zone="XmuDisplayQueue"> 3670 <primary><type>XmuDisplayQueue</type></primary> 3671 </indexterm> 3672 <synopsis id="XmuDisplayQueue"> 3673typedef int (*XmuCloseDisplayQueueProc)(XmuDisplayQueue *queue, 3674 XmuDisplayQueueEntry *entry); 3675 3676typedef int (*XmuFreeDisplayQueueProc)(XmuDisplayQueue *queue); 3677 3678typedef struct _XmuDisplayQueueEntry { 3679 struct _XmuDisplayQueueEntry *prev, *next; 3680 Display *display; 3681 CloseHook closehook; 3682 XPointer data; 3683} XmuDisplayQueueEntry; 3684 3685typedef 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> 3711specifies the close function 3712 </para></listitem> 3713 </varlistentry> 3714 <varlistentry> 3715 <term><parameter>freefunc</parameter></term> 3716 <listitem><para> 3717specifies the free function 3718 </para></listitem> 3719 </varlistentry> 3720 <varlistentry> 3721 <term><parameter>data</parameter></term> 3722 <listitem><para> 3723specifies private data for the functions 3724 </para></listitem> 3725 </varlistentry> 3726 </variablelist> 3727 3728This 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 3731historical reasons). The queue is initially empty, but displays 3732can be added using 3733<function>XmuAddDisplay</function>. 3734The data value is simply stored in the queue for use by the closefunc 3735and freefunc callbacks. 3736Whenever a display in the queue is closed using 3737<function>XCloseDisplay</function>, 3738the <parameter>closefunc</parameter> (if non-<symbol>NULL</symbol>) is called with the queue and the display's 3739<function>XmuDisplayQueueEntry</function> 3740as follows: 3741 <programlisting> 3742 (*closefunc)(queue, entry) 3743 </programlisting> 3744 </para> 3745 3746 <para> 3747The <parameter>freefunc</parameter> (if non-<symbol>NULL</symbol>) is called whenever the last 3748display in the 3749queue is closed, as follows: 3750 3751 <programlisting> 3752 (*freefunc)(queue) 3753 </programlisting> 3754 </para> 3755 3756 <para> 3757The 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> 3778specifies the queue 3779 </para></listitem> 3780 </varlistentry> 3781 <varlistentry> 3782 <term><parameter>dpy</parameter></term> 3783 <listitem><para> 3784specifies the display to add 3785 </para></listitem> 3786 </varlistentry> 3787 <varlistentry> 3788 <term><parameter>data</parameter></term> 3789 <listitem><para> 3790specifies private data for the free function 3791 </para></listitem> 3792 </varlistentry> 3793 </variablelist> 3794 3795This function adds the specified display to the queue. If successful, 3796the queue entry is returned, otherwise <symbol>NULL</symbol> is returned. 3797The data value is simply stored in the queue entry for use by the 3798queue's freefunc callback. This function does not attempt to prevent 3799duplicate entries in the queue; the caller should use 3800<function>XmuDQLookupDisplay</function> 3801to 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> 3819specifies the queue 3820 </para></listitem> 3821 </varlistentry> 3822 <varlistentry> 3823 <term><parameter>dpy</parameter></term> 3824 <listitem><para> 3825specifies the display to lookup 3826 </para></listitem> 3827 </varlistentry> 3828 </variablelist> 3829 3830This function returns the queue entry for the specified display, or 3831<symbol>NULL</symbol> if 3832the 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> 3845This 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> 3863specifies the queue 3864 </para></listitem> 3865 </varlistentry> 3866 <varlistentry> 3867 <term><parameter>dpy</parameter></term> 3868 <listitem><para> 3869specifies the display to remove 3870 </para></listitem> 3871 </varlistentry> 3872 </variablelist> 3873 3874This function removes the specified display from the specified queue. 3875No callbacks are performed. 3876If the display is not found in the queue, 3877<symbol>False</symbol> 3878is returned, otherwise 3879<symbol>True</symbol> 3880is 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> 3898specifies the queue to destroy 3899 </para></listitem> 3900 </varlistentry> 3901 <varlistentry> 3902 <term><parameter>docallbacks</parameter></term> 3903 <listitem><para> 3904specifies whether close functions should be called 3905 </para></listitem> 3906 </varlistentry> 3907 </variablelist> 3908 3909This function releases all memory associated with the specified queue. 3910If docallbacks is 3911<symbol>True</symbol>, 3912then the queue's closefunc callback (if non-<symbol>NULL</symbol>) is first called 3913for each display in the queue, even though 3914<function>XCloseDisplay</function> 3915is 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> 3924To use the functions defined in this section, you should include the header 3925file 3926<<filename class='headerfile'>X11/Xmu/Initer.h</filename>> 3927<indexterm> 3928<primary><filename class='headerfile'>X11/Xmu/Initer.h</filename></primary> 3929</indexterm> 3930and 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> 3949specifies the procedure to register 3950 </para></listitem> 3951 </varlistentry> 3952 <varlistentry> 3953 <term><parameter>data</parameter></term> 3954 <listitem><para> 3955specifies private data for the procedure 3956 </para></listitem> 3957 </varlistentry> 3958 </variablelist> 3959 3960This function registers a procedure, to be invoked the first time 3961<function>XmuCallInitializers</function> 3962is called on a given application context. The procedure 3963is 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> 3984specifies the application context to initialize 3985 </para></listitem> 3986 </varlistentry> 3987 </variablelist> 3988 3989This function calls each of the procedures that have been registered with 3990<function>XmuAddInitializer</function>, 3991if this is the first time the application context has been passed to 3992<function>XmuCallInitializers</function>. 3993Otherwise, 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> 4002To use the functions defined in this section, you should include the header 4003file 4004<<filename class='headerfile'>X11/Xmu/StdCmap.h</filename>> 4005<indexterm> 4006<primary><filename class='headerfile'>X11/Xmu/StdCmap.h</filename></primary> 4007</indexterm> 4008and 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> 4025specifies 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> 4033To create all of the appropriate standard colormaps for every visual of 4034every screen on a given display, use 4035<function>XmuAllStandardColormaps</function>. 4036 </para> 4037 4038 <para> 4039This function defines and retains as permanent resources all standard 4040colormaps which are meaningful for the visuals of each screen of the 4041display. It returns 0 on failure, non-zero on success. If the property of 4042any standard colormap is already defined, this function will redefine it. 4043 </para> 4044 4045 <para> 4046This function is intended to be used by window managers or a special client 4047at the start of a session. 4048 </para> 4049 4050 <para> 4051The standard colormaps of a screen are defined by properties associated with 4052the screen's root window. The property names of standard colormaps are 4053predefined, and each property name except 4054<property>RGB_DEFAULT_MAP</property> may describe at 4055most one colormap. 4056 </para> 4057 4058 <para> 4059The 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 4063have at most 6 standard colormap properties defined. 4064 </para> 4065 4066 <para> 4067A standard colormap is associated with a particular visual of the screen. A 4068screen may have multiple visuals defined, including visuals of the same 4069class at different depths. Note that a visual id might be repeated for more 4070than one depth, so the visual id and the depth of a visual identify the 4071visual. The characteristics of the visual will determine which standard 4072colormaps are meaningful under that visual, and will determine how the 4073standard colormap is defined. Because a standard colormap is associated 4074with a specific visual, there must be a method of determining which visuals 4075take precedence in defining standard colormaps. 4076 </para> 4077 4078 <para> 4079The method used here is: for the visual of greatest depth, define all 4080standard colormaps meaningful to that visual class, according to this order 4081of (descending) precedence: 4082<symbol>DirectColor</symbol>; 4083<symbol>PseudoColor</symbol>; 4084<symbol>TrueColor</symbol> 4085and 4086<symbol>GrayScale</symbol>; 4087and finally 4088<symbol>StaticColor</symbol> 4089and 4090<symbol>StaticGray</symbol>. 4091 </para> 4092 4093<para>This function allows success, on a per screen basis. For example, if a map 4094on screen 1 fails, the maps on screen 0, created earlier, will remain. 4095However, none on screen 1 will remain. If a map on screen 0 fails, none 4096will remain. 4097 </para> 4098 4099 <para> 4100See 4101<link linkend="XmuVisualStandardColormaps"><function>XmuVisualStandardColormaps</function></link> 4102for 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> 4124specifies the connection to the X server 4125 </para></listitem> 4126 </varlistentry> 4127 <varlistentry> 4128 <term><parameter>screen</parameter></term> 4129 <listitem><para> 4130specifies the screen of the display 4131 </para></listitem> 4132 </varlistentry> 4133 <varlistentry> 4134 <term><parameter>visualid</parameter></term> 4135 <listitem><para> 4136specifies the visual type 4137 </para></listitem> 4138 </varlistentry> 4139 <varlistentry> 4140 <term><parameter>depth</parameter></term> 4141 <listitem><para> 4142specifies the visual depth 4143 </para></listitem> 4144 </varlistentry> 4145 <varlistentry> 4146 <term><parameter>replace</parameter></term> 4147 <listitem><para> 4148specifies whether or not to replace 4149 </para></listitem> 4150 </varlistentry> 4151 <varlistentry> 4152 <term><parameter>retain</parameter></term> 4153 <listitem><para> 4154specifies whether or not to retain 4155 </para></listitem> 4156 </varlistentry> 4157 </variablelist> 4158 4159To create all of the appropriate standard colormaps for a given visual on a 4160given screen, use 4161<function>XmuVisualStandardColormaps</function>. 4162 </para> 4163 4164 <para> 4165This function defines all appropriate standard colormap properties for the 4166given visual. If replace is 4167<symbol>True</symbol>, 4168any previous definition will be removed. 4169If retain is 4170<symbol>True</symbol>, 4171new properties will be retained for the duration of the 4172server session. This function returns 0 on failure, non-zero on success. 4173On failure, no new properties will be defined, but old ones may have been 4174removed if replace was <symbol>True</symbol>. 4175 </para> 4176 4177 <para> 4178Not all standard colormaps are meaningful to all visual classes. This 4179routine will check and define the following properties for the following 4180classes, provided that the size of the colormap is not too small. For 4181<symbol>DirectColor</symbol> 4182and 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>. 4187For 4188<symbol>TrueColor</symbol> 4189and 4190<symbol>StaticColor</symbol>: 4191<property>RGB_BEST_MAP</property>. For 4192<symbol>GrayScale</symbol> 4193and 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> 4218specifies the connection to the X server 4219 </para></listitem> 4220 </varlistentry> 4221 <varlistentry> 4222 <term><parameter>screen</parameter></term> 4223 <listitem><para> 4224specifies the screen of the display 4225 </para></listitem> 4226 </varlistentry> 4227 <varlistentry> 4228 <term><parameter>visualid</parameter></term> 4229 <listitem><para> 4230specifies the visual type 4231 </para></listitem> 4232 </varlistentry> 4233 <varlistentry> 4234 <term><parameter>depth</parameter></term> 4235 <listitem><para> 4236specifies the visual depth 4237 </para></listitem> 4238 </varlistentry> 4239 <varlistentry> 4240 <term><parameter>property</parameter></term> 4241 <listitem><para> 4242specifies the standard colormap property 4243 </para></listitem> 4244 </varlistentry> 4245 <varlistentry> 4246 <term><parameter>replace</parameter></term> 4247 <listitem><para> 4248specifies whether or not to replace 4249 </para></listitem> 4250 </varlistentry> 4251 <varlistentry> 4252 <term><parameter>retain</parameter></term> 4253 <listitem><para> 4254specifies whether or not to retain 4255 </para></listitem> 4256 </varlistentry> 4257 </variablelist> 4258 4259To create a standard colormap if one does not currently exist, or replace 4260the currently existing standard colormap, use 4261<function>XmuLookupStandardColormap</function>. 4262 </para> 4263 4264 <para> 4265Given a screen, a visual, and a property, this function will determine the 4266best allocation for the property under the specified visual, and determine 4267the whether to create a new colormap or to use the default colormap of the 4268screen. 4269 </para> 4270 4271 <para> 4272If replace is True, any previous definition of the property will be 4273replaced. If retain is True, the property and the colormap will be made 4274permanent for the duration of the server session. However, pre-existing 4275property definitions which are not replaced cannot be made permanent by a 4276call to this function; a request to retain resources pertains to newly 4277created resources. 4278 </para> 4279 4280 <para> 4281This function returns 0 on failure, non-zero on success. A request to 4282create a standard colormap upon a visual which cannot support such a map is 4283considered a failure. An example of this would be requesting any standard 4284colormap property on a monochrome visual, or, requesting an 4285<property>RGB_BEST_MAP</property> on 4286a 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> 4307specifies visual information for a chosen visual 4308 </para></listitem> 4309 </varlistentry> 4310 <varlistentry> 4311 <term><parameter>property</parameter></term> 4312 <listitem><para> 4313specifies one of the standard colormap property names 4314 </para></listitem> 4315 </varlistentry> 4316 <varlistentry> 4317 <term><parameter>red_max</parameter></term> 4318 <listitem><para> 4319returns maximum red value</para> 4320 </listitem> 4321 </varlistentry> 4322 <varlistentry> 4323 <term><parameter>green_max</parameter></term> 4324 <listitem><para> 4325returns maximum green value 4326 </para></listitem> 4327 </varlistentry> 4328 <varlistentry> 4329 <term><parameter>blue_max</parameter></term> 4330 <listitem><para> 4331returns maximum blue value 4332 </para></listitem> 4333 </varlistentry> 4334 </variablelist> 4335 4336To determine the best allocation of reds, greens, and blues in a standard 4337colormap, use 4338<function>XmuGetColormapAllocation</function>. 4339 </para> 4340 4341 <para> 4342<function>XmuGetColormapAllocation</function> 4343returns 0 on failure, non-zero on success. It is 4344assumed 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> 4369specifies the connection to the X server 4370 </para></listitem> 4371 </varlistentry> 4372 <varlistentry> 4373 <term><parameter>screen</parameter></term> 4374 <listitem><para> 4375specifies the screen of the display 4376 </para></listitem> 4377 </varlistentry> 4378 <varlistentry> 4379 <term><parameter>visualid</parameter></term> 4380 <listitem><para> 4381specifies the visual type 4382 </para></listitem> 4383 </varlistentry> 4384 <varlistentry> 4385 <term><parameter>depth</parameter></term> 4386 <listitem><para> 4387specifies the visual depth 4388 </para></listitem> 4389 </varlistentry> 4390 <varlistentry> 4391 <term><parameter>property</parameter></term> 4392 <listitem><para> 4393specifies the standard colormap property 4394 </para></listitem> 4395 </varlistentry> 4396 <varlistentry> 4397 <term><parameter>cmap</parameter></term> 4398 <listitem><para> 4399specifies the colormap ID, or None 4400 </para></listitem> 4401 </varlistentry> 4402 <varlistentry> 4403 <term><parameter>red_max</parameter></term> 4404 <listitem><para> 4405specifies the red allocation 4406 </para></listitem> 4407 </varlistentry> 4408 <varlistentry> 4409 <term><parameter>green_max</parameter></term> 4410 <listitem><para> 4411specifies the green allocation 4412 </para></listitem> 4413 </varlistentry> 4414 <varlistentry> 4415 <term><parameter>blue_max</parameter></term> 4416 <listitem><para> 4417specifies the blue allocation 4418 </para></listitem> 4419 </varlistentry> 4420 </variablelist> 4421 4422To create any one standard colormap, use 4423<function>XmuStandardColormap</function>. 4424 </para> 4425 4426 <para> 4427This function creates a standard colormap for the given screen, visualid, 4428and visual depth, with the given red, green, and blue maximum values, with 4429the given standard property name. Upon success, it returns a pointer to an 4430<function>XStandardColormap</function> 4431structure which describes the newly created colormap. 4432Upon failure, it returns <symbol>NULL</symbol>. 4433If cmap is the default colormap of the screen, the standard colormap 4434will be defined on the default colormap; otherwise a new colormap is created. 4435 </para> 4436 4437 <para> 4438Resources created by this function are not made permanent; that is the 4439caller'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> 4457specifies the connection under which the map is created 4458 </para></listitem> 4459 </varlistentry> 4460 <varlistentry> 4461 <term><parameter>colormap</parameter></term> 4462 <listitem><para> 4463specifies the map to be created</para></listitem> 4464 </varlistentry> 4465 </variablelist> 4466 4467To create any one colormap which is described by an 4468<structname>XStandardColormap</structname> 4469structure, use 4470<function>XmuCreateColormap</function>. 4471 </para> 4472 4473 <para> 4474This function returns 0 on failure, and non-zero on success. The base_pixel 4475of the colormap is set on success. Resources created by this function are 4476not made permanent. No argument error checking is provided; use at your own 4477risk. 4478 </para> 4479 4480 <para> 4481All colormaps are created with read-only allocations, with the exception of 4482read-only allocations of colors which fail 4483to return the expected pixel value, and these are individually defined as 4484read/write allocations. This is done so that all the cells defined in the 4485colormap are contiguous, for use in image processing. This typically 4486happens with White and Black in the default map. 4487 </para> 4488 4489 <para> 4490Colormaps of static visuals are considered to be successfully created if the 4491map of the static visual matches the definition given in the standard 4492colormap 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> 4511specifies the connection to the X server 4512 </para></listitem> 4513 </varlistentry> 4514 <varlistentry> 4515 <term><parameter>screen</parameter></term> 4516 <listitem><para> 4517specifies the screen of the display 4518 </para></listitem> 4519 </varlistentry> 4520 <varlistentry> 4521 <term><parameter>property</parameter></term> 4522 <listitem><para> 4523specifies the standard colormap property 4524 </para></listitem> 4525 </varlistentry> 4526 </variablelist> 4527 4528To remove any standard colormap property, use 4529<function>XmuDeleteStandardColormap</function>. 4530This function will remove the specified property from the specified screen, 4531releasing any resources used by the colormap(s) of the property, if 4532possible. 4533 </para> 4534 4535 </sect1> 4536 4537 <sect1 id='Widget_Description_Functions'> 4538<title>Widget Description Functions</title> 4539 4540 <para> 4541The functions defined in this section are for building a description of 4542the structure of and resources associated with a hierarchy of widget classes. 4543This package is typically used by applications that wish to manipulate the 4544widget set itself. 4545 </para> 4546 4547 <para> 4548The definitions needed to use these interfaces are in the header file 4549<<filename class='headerfile'>X11/Xmu/WidgetNode.h</filename>> 4550<indexterm> 4551<primary><filename class='headerfile'>X11/Xmu/WidgetNode.h</filename></primary> 4552</indexterm>. 4553To call these functions, you need to link against the libXmu library. 4554The following function must be called before any of the others described 4555below: 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> 4568specifies 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> 4574specifies the number of widget classes in the node array 4575 </para></listitem> 4576 </varlistentry> 4577 </variablelist> 4578 </para> 4579 4580 <para> 4581To 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> 4595specifies 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> 4601specifies the widget that should be used for creating an instance of 4602<parameter>node</parameter> 4603from which resources are extracted. This is typically the value returned 4604by <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> 4610specifies the ancestor of <parameter>node</parameter> that should be 4611treated as the root 4612of the widget inheritance tree (used in determining which ancestor contributed 4613which resources). 4614 </para></listitem> 4615 </varlistentry> 4616 </variablelist> 4617 </para> 4618 4619 <para> 4620Each widget class inherits the resources of its parent. To count the number 4621of 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> 4635specifies 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> 4641specifies the widget class of the ancestor of <parameter>node</parameter> 4642whose contributions 4643are being counted. 4644 </para></listitem> 4645 </varlistentry> 4646 <varlistentry> 4647 <term><parameter>constraints</parameter></term> 4648 <listitem><para> 4649specifies whether or not to count constraint resources or normal resources. 4650 </para></listitem> 4651 </varlistentry> 4652 </variablelist> 4653 4654This routine returns the number of resources contributed (or 4655“owned”) by 4656the 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> 4675specifies a list of widget nodes 4676 </para></listitem> 4677 </varlistentry> 4678 <varlistentry> 4679 <term><parameter>num_nodes</parameter></term> 4680 <listitem><para> 4681specifies the number of nodes in the list 4682 </para></listitem> 4683 </varlistentry> 4684 <varlistentry> 4685 <term><parameter>name</parameter></term> 4686 <listitem><para> 4687specifies the name of the widget class in the node list to search for 4688 </para></listitem> 4689 </varlistentry> 4690 </variablelist> 4691 4692This function returns the WidgetNode in the list that matches the given 4693widget 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> 4706To participate in the editres protocol, applications which are not based 4707on the Athena widget set should include the header file 4708<<filename class='headerfile'>X11/Xmu/Editres.h</filename>> 4709<indexterm> 4710<primary><filename class='headerfile'>X11/Xmu/Editres.h</filename></primary> 4711</indexterm> 4712and link against the libXmu library. 4713 </para> 4714 4715 <para> 4716To participate in the editres protocol, Xt applications which do not rely 4717on the Athena widget set should register the editres protocol handler on 4718each shell widget in the application, specifying an event mask of 0, 4719nonmaskable events, and client data as <symbol>NULL</symbol>: 4720 4721 <programlisting> 4722XtAddEventHandler(shell, (EventMask) 0, True, _XEditResCheckMessages, NULL); 4723 </programlisting> 4724 </para> 4725 </sect1> 4726 4727 <index /> 4728</article> 4729
