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"
5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
7 <!-- lifted from troff+ms+XMan by doclifter -->
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>
15 <abstract><para>“Don't ask.”</para></abstract>
20 Permission is hereby granted, free of charge, to any person obtaining a copy
21 of this software and associated documentation files (the “Software”), to deal
22 in the Software without restriction, including without limitation the rights
23 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
24 copies of the Software, and to permit persons to whom the Software is
25 furnished to do so, subject to the following conditions:
28 The above copyright notice and this permission notice shall be included in
29 all copies or substantial portions of the Software.
32 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
33 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
34 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
35 X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
36 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
37 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
40 Except as contained in this notice, the name of the X Consortium shall not be
41 used in advertising or otherwise to promote the sale, use or other dealings
42 in this Software without prior written authorization from the X Consortium.
45 <trademark><emphasis>X Window System</emphasis></trademark>
46 is a trademark of The Open Group.
52 <sect1 id='Introduction'>
53 <title>Introduction</title>
56 The Xmu Library is a collection of miscellaneous (some might say random)
57 utility functions that have been useful in building various applications
58 and widgets. This library is required by the Athena Widgets.
62 Starting in XFree86 4.1.0, and incorporated into X11R6.7 and later releases,
63 a subset of the functions that do not rely on the Athena Widgets (libXaw)
64 or X Toolkit Instrinsics (libXt) are provided in a second library, libXmuu.
68 Programs using either of these libraries are encouraged to determine the
69 correct compiler and linker options via the <userinput>xmu</userinput> or
70 <userinput>xmuu</userinput> module names for <command>pkg-config</command>,
72 <primary><command>pkg-config</command></primary>
77 cc -c xapplication.c `pkg-config --cflags xmu`
78 cc -o xapplication xapplication.o `pkg-config --libs xmu`
84 <sect1 id='Atom_Functions'>
85 <title>Atom Functions</title>
88 To use the functions and macros defined in this section, you should include
90 <<filename class='headerfile'>X11/Xmu/Atoms.h</filename>>
92 <primary><filename class='headerfile'>X11/Xmu/Atoms.h</filename></primary>
94 and link against the libXmu library.
99 <funcdef><function>XA_ATOM_PAIR</function></funcdef>
100 <paramdef><parameter>d</parameter></paramdef>
103 <funcdef><function>XA_CHARACTER_POSITION</function></funcdef>
104 <paramdef><parameter>d</parameter></paramdef>
107 <funcdef><function>XA_CLASS</function></funcdef>
108 <paramdef><parameter>d</parameter></paramdef>
111 <funcdef><function>XA_CLIENT_WINDOW</function></funcdef>
112 <paramdef><parameter>d</parameter></paramdef>
115 <funcdef><function>XA_CLIPBOARD</function></funcdef>
116 <paramdef><parameter>d</parameter></paramdef>
119 <funcdef><function>XA_COMPOUND_TEXT</function></funcdef>
120 <paramdef><parameter>d</parameter></paramdef>
123 <funcdef><function>XA_DECNET_ADDRESS</function></funcdef>
124 <paramdef><parameter>d</parameter></paramdef>
127 <funcdef><function>XA_DELETE</function></funcdef>
128 <paramdef><parameter>d</parameter></paramdef>
131 <funcdef><function>XA_FILENAME</function></funcdef>
132 <paramdef><parameter>d</parameter></paramdef>
135 <funcdef><function>XA_HOSTNAME</function></funcdef>
136 <paramdef><parameter>d</parameter></paramdef>
139 <funcdef><function>XA_IP_ADDRESS</function></funcdef>
140 <paramdef><parameter>d</parameter></paramdef>
143 <funcdef><function>XA_LENGTH</function></funcdef>
144 <paramdef><parameter>d</parameter></paramdef>
147 <funcdef><function>XA_LIST_LENGTH</function></funcdef>
148 <paramdef><parameter>d</parameter></paramdef>
151 <funcdef><function>XA_NAME</function></funcdef>
152 <paramdef><parameter>d</parameter></paramdef>
155 <funcdef><function>XA_NET_ADDRESS</function></funcdef>
156 <paramdef><parameter>d</parameter></paramdef>
159 <funcdef><function>XA_NULL</function></funcdef>
160 <paramdef><parameter>d</parameter></paramdef>
163 <funcdef><function>XA_OWNER_OS</function></funcdef>
164 <paramdef><parameter>d</parameter></paramdef>
167 <funcdef><function>XA_SPAN</function></funcdef>
168 <paramdef><parameter>d</parameter></paramdef>
171 <funcdef><function>XA_TARGETS</function></funcdef>
172 <paramdef><parameter>d</parameter></paramdef>
175 <funcdef><function>XA_TEXT</function></funcdef>
176 <paramdef><parameter>d</parameter></paramdef>
179 <funcdef><function>XA_TIMESTAMP</function></funcdef>
180 <paramdef><parameter>d</parameter></paramdef>
183 <funcdef><function>XA_USER</function></funcdef>
184 <paramdef><parameter>d</parameter></paramdef>
187 <funcdef><function>XA_UTF8_STRING</function></funcdef>
188 <paramdef><parameter>d</parameter></paramdef>
194 <primary><type>Atom</type></primary>
196 These macros take a display as argument and return an
199 atom is obtained from the macro name by removing the leading characters
200 “<code>XA_</code>”. The
202 value is cached, such that subsequent requests do not cause
203 another round-trip to the server.
207 <indexterm zone="XmuMakeAtom">
208 <primary><xref linkend='XmuMakeAtom' xrefstyle='select: title'/></primary>
210 <funcsynopsis id='XmuMakeAtom'>
212 <funcdef>AtomPtr <function>XmuMakeAtom</function></funcdef>
213 <paramdef>const char *<parameter>name</parameter></paramdef>
218 <term><parameter>name</parameter></term>
220 specifies the atom name
225 This function creates and initializes an opaque object, an
226 <type>AtomPtr</type>,
231 <xref linkend='XmuInternAtom' xrefstyle='select: title'/>
232 can be used to cache the Atom value for one or more displays.
236 <indexterm zone="XmuNameOfAtom">
237 <primary><xref linkend='XmuNameOfAtom' xrefstyle='select: title'/></primary>
239 <funcsynopsis id='XmuNameOfAtom'>
241 <funcdef>char *<function>XmuNameOfAtom</function></funcdef>
242 <paramdef>AtomPtr <parameter>atom_ptr</parameter></paramdef>
247 <term><parameter>atom_ptr</parameter></term>
249 specifies the AtomPtr
254 The function returns the name of an AtomPtr.
258 <indexterm zone="XmuInternAtom">
259 <primary><xref linkend='XmuInternAtom' xrefstyle='select: title'/></primary>
261 <funcsynopsis id='XmuInternAtom'>
263 <funcdef>Atom <function>XmuInternAtom</function></funcdef>
264 <paramdef>Display *<parameter>dpy</parameter></paramdef>
265 <paramdef>AtomPtr <parameter>atom_ptr</parameter></paramdef>
270 <term><parameter>dpy</parameter></term>
272 specifies the connection to the X server
276 <term><parameter>atom_ptr</parameter></term>
278 specifies the AtomPtr
283 This function returns the
286 <type>AtomPtr</type>.
290 such that subsequent requests do not cause another round-trip to the server.
294 <indexterm zone="XmuGetAtomName">
295 <primary><xref linkend='XmuGetAtomName' xrefstyle='select: title'/></primary>
297 <funcsynopsis id='XmuGetAtomName'>
299 <funcdef>char *<function>XmuGetAtomName</function></funcdef>
300 <paramdef>Display *<parameter>dpy</parameter></paramdef>
301 <paramdef>Atom <parameter>atom</parameter></paramdef>
306 <term><parameter>dpy</parameter></term>
308 specifies the connection to the X server
312 <term><parameter>atom</parameter></term>
314 specifies the atom whose name is desired
319 This function returns the name of an
321 The result is cached, such that subsequent
322 requests do not cause another round-trip to the server.
326 <indexterm zone="XmuInternStrings">
327 <primary><xref linkend='XmuInternStrings' xrefstyle='select: title'/></primary>
329 <funcsynopsis id='XmuInternStrings'>
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>
340 <term><parameter>dpy</parameter></term>
342 specifies the connection to the X server
346 <term><parameter>names</parameter></term>
348 specifies the strings to intern
352 <term><parameter>count</parameter></term>
354 specifies the number of strings
358 <term><parameter>atoms</parameter></term>
360 returns the list of Atom values
365 This function converts a list of atom names into
367 values. The results are cached, such
368 that subsequent requests do not cause further round-trips to the server.
369 The caller is responsible for preallocating the array pointed at by atoms.
374 <sect1 id='Error_Handler_Functions'>
375 <title>Error Handler Functions</title>
378 To use the functions defined in this section, you should include the header
380 <<filename class='headerfile'>X11/Xmu/Error.h</filename>>
382 <primary><filename class='headerfile'>X11/Xmu/Error.h</filename></primary>
384 and link against the libXmu or libXmuu library.
388 <indexterm zone="XmuPrintDefaultErrorMessage">
389 <primary><xref linkend='XmuPrintDefaultErrorMessage' xrefstyle='select: title'/></primary>
391 <funcsynopsis id='XmuPrintDefaultErrorMessage'>
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>
401 <term><parameter>dpy</parameter></term>
403 specifies the connection to the X server
407 <term><parameter>event</parameter></term>
413 <term><parameter>fp</parameter></term>
415 specifies where to print the error message
420 This function prints an error message, equivalent to Xlib's default error
421 message for protocol errors. It returns a non-zero value
422 if the caller should consider exiting, otherwise it returns 0.
423 This function can be used when you need to
424 write your own error handler, but need to print out an error from within
428 <para id="XmuSimpleErrorHandler">
429 <indexterm zone="XmuSimpleErrorHandler">
430 <primary><function>XmuSimpleErrorHandler</function></primary>
434 <funcdef>int <function>XmuSimpleErrorHandler</function></funcdef>
435 <paramdef>Display *<parameter>dpy</parameter></paramdef>
436 <paramdef>XErrorEvent *<parameter>errorp</parameter></paramdef>
441 <term><parameter>dpy</parameter></term>
443 specifies the connection to the X server
447 <term><parameter>errorp</parameter></term>
454 This function ignores errors for
455 <errorname>BadWindow</errorname>
457 <olink targetdoc='libX11' targetptr='XQueryTree'><function>XQueryTree</function></olink>
459 <olink targetdoc='libX11' targetptr='XGetWindowAttributes'><function>XGetWindowAttributes</function></olink>,
461 <errorname>BadDrawable</errorname>
463 <olink targetdoc='libX11' targetptr='XGetGeometry'><function>XGetGeometry</function></olink>;
464 it returns 0 in those cases. Otherwise, it prints the default error message,
465 and returns a non-zero value if the caller should consider exiting,
466 and 0 if the caller should not exit.
470 <sect1 id='System_Utility_Functions'>
471 <title>System Utility Functions</title>
474 To use the functions defined in this section, you should include the header
476 <<filename class='headerfile'>X11/Xmu/SysUtil.h</filename>>
478 <primary><filename class='headerfile'>X11/Xmu/SysUtil.h</filename></primary>
480 and link against the libXmu or libXmuu library.
483 <para id="XmuGetHostname">
484 <indexterm zone="XmuGetHostname">
485 <primary><function>XmuGetHostname</function></primary>
489 <funcdef>int <function>XmuGetHostname</function></funcdef>
490 <paramdef>char *<parameter>buf</parameter></paramdef>
491 <paramdef>int <parameter>maxlen</parameter></paramdef>
496 <term><parameter>buf</parameter></term>
498 returns the host name
502 <term><parameter>maxlen</parameter></term>
504 specifies the length of <parameter>buf</parameter>
509 This function stores the null terminated name of the local host in
510 <parameter>buf</parameter>, and
511 returns length of the name. This function hides operating system differences,
512 such as whether to call <function>gethostname</function> or
513 <function>uname</function>.
516 <para id="XmuSnprintf">
517 <indexterm zone="XmuSnprintf">
518 <primary><function>XmuSnprintf</function></primary>
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>
530 <term><parameter>str</parameter></term>
532 string to write output to
536 <term><parameter>size</parameter></term>
538 specifies the size of <parameter>str</parameter>
543 This function was provided as a portable implementation of
544 <function>snprintf</function> before all platforms could be
545 relied on to provide their own. It is now deprecated in favor of
546 calling <function>snprintf</function> directly and should only be used
547 in software that needs to continue to support non-Unix98 compliant platforms.
553 <sect1 id='Window_Utility_Functions'>
554 <title>Window Utility Functions</title>
557 To use the functions defined in this section, you should include the header
559 <<filename class='headerfile'>X11/Xmu/WinUtil.h</filename>>
561 <primary><filename class='headerfile'>X11/Xmu/WinUtil.h</filename></primary>
563 To use <function>XmuClientWindow</function>, you may link against either the
564 libXmu or libXmuu libraries. The other functions in this section require
565 linking against the libXmu library.
568 <para id="XmuScreenOfWindow">
569 <indexterm zone="XmuScreenOfWindow">
570 <primary><function>XmuScreenOfWindow</function></primary>
574 <funcdef>Screen *<function>XmuScreenOfWindow</function></funcdef>
575 <paramdef>Display *<parameter>dpy</parameter></paramdef>
576 <paramdef>Window <parameter>w</parameter></paramdef>
581 <term><parameter>dpy</parameter></term>
583 specifies the connection to the X server
587 <term><parameter>w</parameter></term>
594 This function returns the
596 on which the specified window was created.
599 <para id="XmuClientWindow">
600 <indexterm zone="XmuClientWindow">
601 <primary><function>XmuClientWindow</function></primary>
605 <funcdef>Window <function>XmuClientWindow</function></funcdef>
606 <paramdef>Display *<parameter>dpy</parameter></paramdef>
607 <paramdef>Window <parameter>win</parameter></paramdef>
612 <term><parameter>dpy</parameter></term>
614 specifies the connection to the X server
618 <term><parameter>win</parameter></term>
625 <indexterm zone="XmuClientWindow">
626 <primary><property>WM_STATE</property></primary>
628 This function finds a window, at or below the specified window, which has a
629 <property>WM_STATE</property> property. If such a window is found, it is
630 returned, otherwise the
631 argument window is returned.
634 <para id="XmuUpdateMapHints">
635 <indexterm zone="XmuUpdateMapHints">
636 <primary><function>XmuUpdateMapHints</function></primary>
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>
648 <term><parameter>dpy</parameter></term>
650 specifies the connection to the X server
654 <term><parameter>win</parameter></term>
660 <term><parameter>hints</parameter></term>
662 specifies the new hints, or <symbol>NULL</symbol>
667 This function clears the
668 <symbol>PPosition</symbol>
670 <symbol>PSize</symbol>
672 <symbol>USPosition</symbol>
674 <symbol>USSize</symbol>
675 flags in the hints structure, and then stores the hints for the
677 <indexterm zone="XmuUpdateMapHints">
678 <primary><olink targetdoc='libX11' targetptr='XSetWMNormalHints'><function>XSetWMNormalHints</function></olink></primary>
680 <olink targetdoc='libX11' targetptr='XSetWMNormalHints'><function>XSetWMNormalHints</function></olink>
682 <symbol>True</symbol>.
683 If <symbol>NULL</symbol> is passed for the
684 hints structure, then the current hints are read back from the window using
685 <indexterm zone="XmuUpdateMapHints">
686 <primary><olink targetdoc='libX11' targetptr='XGetWMNormalHints'><function>XGetWMNormalHints</function></olink></primary>
688 <olink targetdoc='libX11' targetptr='XGetWMNormalHints'><function>XGetWMNormalHints</function></olink>
689 and are used instead, and
690 <symbol>True</symbol>
691 is returned; otherwise
692 <symbol>False</symbol>
698 <sect1 id='Cursor_Utility_Functions'>
699 <title>Cursor Utility Functions</title>
702 To use the functions defined in this section, you should include the header
704 <<filename class='headerfile'>X11/Xmu/CurUtil.h</filename>>
706 <primary><filename class='headerfile'>X11/Xmu/CurUtil.h</filename></primary>
708 and link against the libXmu or libXmuu library.
711 <para id="XmuCursorNameToIndex">
712 <indexterm zone="XmuCursorNameToIndex">
713 <primary><function>XmuCursorNameToIndex</function></primary>
717 <funcdef>int <function>XmuCursorNameToIndex</function></funcdef>
718 <paramdef>const char *<parameter>name</parameter></paramdef>
723 <term><parameter>name</parameter></term>
725 specifies the name of the cursor
730 This function takes the name of a standard cursor and returns its index
731 in the standard cursor font. The cursor names are formed by removing the
732 “<code>XC_</code>” prefix from the cursor defines listed in
733 Appendix B of the Xlib
739 <sect1 id='Graphics_Functions'>
740 <title>Graphics Functions</title>
743 To use the functions defined in this section, you should include the header
745 <<filename class='headerfile'>X11/Xmu/Drawing.h</filename>>
747 <primary><filename class='headerfile'>X11/Xmu/Drawing.h</filename></primary>
749 and link against the libXmu library.
752 <para id="XmuDrawRoundedRectangle">
753 <indexterm zone="XmuDrawRoundedRectangle">
754 <primary><function>XmuDrawRoundedRectangle</function></primary>
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>
772 <term><parameter>dpy</parameter></term>
774 specifies the connection to the X server
778 <term><parameter>draw</parameter></term>
780 specifies the drawable
784 <term><parameter>gc</parameter></term>
790 <term><parameter>x</parameter></term>
792 specifies the upper left x coordinate
796 <term><parameter>y</parameter></term>
798 specifies the upper left y coordinate
802 <term><parameter>w</parameter></term>
804 specifies the rectangle width
808 <term><parameter>h</parameter></term>
810 specifies the rectangle height
814 <term><parameter>ew</parameter></term>
816 specifies the corner width
820 <term><parameter>eh</parameter></term>
822 specifies the corner height
827 This function draws a rounded rectangle, where x, y, w, h are the dimensions
828 of the overall rectangle, and ew and eh are the sizes of a bounding box that
829 the corners are drawn inside of; ew should be no more than half of w, and eh
830 should be no more than half of h. The current GC line attributes control
831 all attributes of the line.
834 <para id="XmuFillRoundedRectangle">
835 <indexterm zone="XmuFillRoundedRectangle">
836 <primary><function>XmuFillRoundedRectangle</function></primary>
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>
854 <term><parameter>dpy</parameter></term>
856 specifies the connection to the X server
860 <term><parameter>draw</parameter></term>
862 specifies the drawable
866 <term><parameter>gc</parameter></term>
872 <term><parameter>x</parameter></term>
874 specifies the upper left x coordinate
878 <term><parameter>y</parameter></term>
880 specifies the upper left y coordinate
884 <term><parameter>w</parameter></term>
886 specifies the rectangle width
890 <term><parameter>h</parameter></term>
892 specifies the rectangle height
896 <term><parameter>ew</parameter></term>
898 specifies the corner width
902 <term><parameter>eh</parameter></term>
904 specifies the corner height
909 This function draws a filled rounded rectangle, where x, y, w, h are the
910 dimensions of the overall rectangle, and ew and eh are the sizes of a
911 bounding box that the corners are drawn inside of; ew should be no more than
912 half of w, and eh should be no more than half of h. The current GC fill
913 settings control all attributes of the fill contents.
916 <para id="XmuDrawLogo">
917 <indexterm zone="XmuDrawLogo">
918 <primary><function>XmuDrawLogo</function></primary>
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>
935 <term><parameter>dpy</parameter></term>
937 specifies the connection to the X server
941 <term><parameter>drawable</parameter></term>
943 specifies the drawable
947 <term><parameter>gcFore</parameter></term>
949 specifies the foreground GC
953 <term><parameter>gcBack</parameter></term>
955 specifies the background GC
959 <term><parameter>x</parameter></term>
961 specifies the upper left x coordinate
965 <term><parameter>y</parameter></term>
967 specifies the upper left y coordinate
971 <term><parameter>width</parameter></term>
973 specifies the logo width
977 <term><parameter>height</parameter></term>
979 specifies the logo height
984 This function draws the “official” X Window System logo
985 (<xref linkend="xlogo"/>). The bounding box
986 of the logo in the drawable is given by x, y, width, and height. The logo
987 itself is filled using gcFore, and the rest of the rectangle is filled using
990 <figure id="xlogo" pgwide="0">
991 <title>The X Logo</title>
994 <imagedata id="xlogo-svg" format="SVG" fileref="xlogo.svg"/>
998 <para id="XmuCreateStippledPixmap">
999 <indexterm zone="XmuCreateStippledPixmap">
1000 <primary><function>XmuCreateStippledPixmap</function></primary>
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>
1013 <term><parameter>screen</parameter></term>
1015 specifies the screen the pixmap is created on
1019 <term><parameter>fore</parameter></term>
1021 specifies the foreground pixel value
1025 <term><parameter>back</parameter></term>
1027 specifies the background pixel value
1031 <term><parameter>depth</parameter></term>
1033 specifies the depth of the pixmap
1038 This function creates a two pixel by one pixel stippled pixmap of specified
1039 depth on the specified screen. The pixmap is cached so that multiple
1040 requests share the same pixmap. The pixmap should be freed with
1041 <function>XmuReleaseStippledPixmap</function>
1042 to maintain correct reference counts.
1045 <para id="XmuReleaseStippledPixmap">
1046 <indexterm zone="XmuReleaseStippledPixmap">
1047 <primary><function>XmuReleaseStippledPixmap</function></primary>
1051 <funcdef>void <function>XmuReleaseStippledPixmap</function></funcdef>
1052 <paramdef>Screen *<parameter>screen</parameter></paramdef>
1053 <paramdef>Pixmap <parameter>pixmap</parameter></paramdef>
1058 <term><parameter>screen</parameter></term>
1060 specifies the screen the pixmap was created on
1064 <term><parameter>pixmap</parameter></term>
1066 specifies the pixmap to free
1071 This function frees a pixmap created with
1072 <function>XmuCreateStippledPixmap</function>.
1075 <para id="XmuReadBitmapData">
1076 <indexterm zone="XmuReadBitmapData">
1077 <primary><function>XmuReadBitmapData</function></primary>
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>
1092 <term><parameter>fstream</parameter></term>
1094 specifies the stream to read from
1098 <term><parameter>width</parameter></term>
1100 returns the width of the bitmap
1104 <term><parameter>height</parameter></term>
1106 returns the height of the bitmap
1110 <term><parameter>datap</parameter></term>
1112 returns the parsed bitmap data
1116 <term><parameter>x_hot</parameter></term>
1118 returns the x coordinate of the hotspot
1122 <term><parameter>y_hot</parameter></term>
1124 returns the y coordinate of the hotspot
1129 This function reads a standard bitmap file description from the specified
1130 stream, and returns the parsed data in a format suitable for passing to
1131 <olink targetdoc='libX11' targetptr='XCreateBitmapFromData'><function>XCreateBitmapFromData</function></olink>.
1132 The return value of the function has the same
1133 interpretation as the return value for
1134 <olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>.
1137 <para id="XmuReadBitmapDataFromFile">
1138 <indexterm zone="XmuReadBitmapDataFromFile">
1139 <primary><function>XmuReadBitmapDataFromFile</function></primary>
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>
1154 <term><parameter>fstream</parameter></term>
1156 specifies the file to read from
1160 <term><parameter>width</parameter></term>
1162 returns the width of the bitmap
1166 <term><parameter>height</parameter></term>
1168 returns the height of the bitmap
1172 <term><parameter>datap</parameter></term>
1174 returns the parsed bitmap data
1178 <term><parameter>x_hot</parameter></term>
1180 returns the x coordinate of the hotspot
1184 <term><parameter>y_hot</parameter></term>
1186 returns the y coordinate of the hotspot
1191 This function reads a standard bitmap file description from the specified
1192 file, and returns the parsed data in a format suitable for passing to
1193 <olink targetdoc='libX11' targetptr='XCreateBitmapFromData'><function>XCreateBitmapFromData</function></olink>.
1194 The return value of the function has the same
1195 interpretation as the return value for
1196 <olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>.
1199 <para id="XmuLocateBitmapFile">
1200 <indexterm zone="XmuLocateBitmapFile">
1201 <primary><function>XmuLocateBitmapFile</function></primary>
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>
1218 <term><parameter>screen</parameter></term>
1220 specifies the screen the pixmap is created on
1224 <term><parameter>name</parameter></term>
1226 specifies the file to read from
1230 <term><parameter>srcname</parameter></term>
1232 returns the full filename of the bitmap
1236 <term><parameter>srcnamelen</parameter></term>
1238 specifies the length of the srcname buffer
1242 <term><parameter>width</parameter></term>
1244 returns the width of the bitmap
1248 <term><parameter>height</parameter></term>
1250 returns the height of the bitmap
1254 <term><parameter>xhotp</parameter></term>
1256 returns the x coordinate of the hotspot
1260 <term><parameter>yhotp</parameter></term>
1262 returns the y coordinate of the hotspot
1267 This function reads a file in standard bitmap file format, using
1268 <olink targetdoc='libX11' targetptr='XReadBitmapFile'><function>XReadBitmapFile</function></olink>,
1269 and returns the created bitmap. The filename may be
1270 absolute, or relative to the global resource named
1271 <indexterm zone="XmuLocateBitmapFile">
1272 <primary><systemitem class="resource">bitmapFilePath</systemitem></primary>
1274 <systemitem class="resource">bitmapFilePath</systemitem> with class
1275 BitmapFilePath. If the resource is not defined, the default value is the
1276 build symbol BITMAPDIR, which is typically
1277 "<filename class="directory">/usr/include/X11/bitmaps</filename>".
1278 If <parameter>srcnamelen</parameter> is greater than zero and
1279 <parameter>srcname</parameter> is not <symbol>NULL</symbol>,
1280 the null terminated filename will be copied into
1281 <parameter>srcname</parameter>. The size and hotspot of the bitmap are
1285 <para id="XmuCreatePixmapFromBitmap">
1286 <indexterm zone="XmuCreatePixmapFromBitmap">
1287 <primary><function>XmuCreatePixmapFromBitmap</function></primary>
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>
1304 <term><parameter>dpy</parameter></term>
1306 specifies the connection to the X server
1310 <term><parameter>screen</parameter></term>
1312 specifies the screen the pixmap is created on
1316 <term><parameter>bitmap</parameter></term>
1318 specifies the bitmap source
1322 <term><parameter>width</parameter></term>
1324 specifies the width of the pixmap
1328 <term><parameter>height</parameter></term>
1330 specifies the height of the pixmap
1334 <term><parameter>depth</parameter></term>
1336 specifies the depth of the pixmap
1340 <term><parameter>fore</parameter></term>
1342 specifies the foreground pixel value
1346 <term><parameter>back</parameter></term>
1348 specifies the background pixel value
1353 This function creates a pixmap of the specified width, height, and depth, on
1354 the same screen as the specified drawable, and then performs an
1355 <olink targetdoc='libX11' targetptr='XCopyPlane'><function>XCopyPlane</function></olink>
1356 from the specified bitmap to the pixmap,
1357 using the specified foreground and background pixel values.
1358 The created pixmap is returned.
1363 <sect1 id='Selection_Functions'>
1364 <title>Selection Functions</title>
1367 To use the functions defined in this section, you should include the header
1369 <<filename class='headerfile'>X11/Xmu/StdSel.h</filename>>
1371 <primary><filename class='headerfile'>X11/Xmu/StdSel.h</filename></primary>
1373 and link against the libXmu library.
1376 <para id="XmuConvertStandardSelection">
1377 <indexterm zone="XmuConvertStandardSelection">
1378 <primary><function>XmuConvertStandardSelection</function></primary>
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>
1395 <term><parameter>w</parameter></term>
1397 specifies the widget which currently owns the selection
1401 <term><parameter>time</parameter></term>
1403 specifies the time at which the selection was established
1407 <term><parameter>selection</parameter></term>
1409 this argument is ignored
1413 <term><parameter>target</parameter></term>
1415 specifies the target type of the selection
1419 <term><parameter>type</parameter></term>
1421 returns the property type of the converted value
1425 <term><parameter>value</parameter></term>
1427 returns the converted value
1431 <term><parameter>length</parameter></term>
1433 returns the number of elements in the converted value
1437 <term><parameter>format</parameter></term>
1439 returns the size in bits of the elements</para>
1444 This function converts the following standard selections: CLASS,
1445 CLIENT_WINDOW, DECNET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS,
1446 TARGETS, TIMESTAMP, and USER. It returns
1447 <symbol>True</symbol>
1448 if the conversion was successful, else it returns
1449 <symbol>False</symbol>.
1453 <sect1 id='Type_Converter_Functions'>
1454 <title>Type Converter Functions</title>
1457 To use the functions defined in this section, you should include the header
1459 <<filename class='headerfile'>X11/Xmu/Converters.h</filename>>
1461 <primary><filename class='headerfile'>X11/Xmu/Converters.h</filename></primary>
1463 and link against the libXmu library.
1466 <para id="XmuCvtFunctionToCallback">
1467 <indexterm zone="XmuCvtFunctionToCallback">
1468 <primary><function>XmuCvtFunctionToCallback</function></primary>
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>
1481 <term><parameter>args</parameter></term>
1483 this argument is ignored
1487 <term><parameter>num_args</parameter></term>
1489 this argument is ignored
1493 <term><parameter>fromVal</parameter></term>
1495 the function to convert
1499 <term><parameter>toVal</parameter></term>
1501 the place to store the converted value
1506 This function converts a callback procedure to a callback list containing
1507 that procedure, with <symbol>NULL</symbol> closure data. To use this converter, include the
1508 following in your widget's ClassInitialize procedure:
1511 XtAddConverter(XtRCallProc, XtRCallback, XmuCvtFunctionToCallback, NULL, 0);
1515 <para id="XmuCvtStringToBackingStore">
1516 <indexterm zone="XmuCvtStringToBackingStore">
1517 <primary><function>XmuCvtStringToBackingStore</function></primary>
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>
1530 <term><parameter>args</parameter></term>
1532 this argument is ignored
1536 <term><parameter>num_args</parameter></term>
1538 this argument must be a pointer to a Cardinal containing the value 0
1542 <term><parameter>fromVal</parameter></term>
1544 specifies the string to convert
1548 <term><parameter>toVal</parameter></term>
1550 returns the converted value
1555 <indexterm zone="XmuCvtStringToBackingStore">
1556 <primary>backing-store</primary>
1558 This function converts a string to a backing-store integer as defined in
1559 <<filename class='headerfile'>X11/X.h</filename>>.
1560 The string "notUseful" converts to
1561 <symbol>NotUseful</symbol>,
1562 "whenMapped" converts to
1563 <symbol>WhenMapped</symbol>,
1564 and "always" converts to
1565 <symbol>Always</symbol>.
1566 The string "default" converts to the value
1567 <symbol>Always</symbol> +
1568 <symbol>WhenMapped</symbol> +
1569 <symbol>NotUseful</symbol>.
1570 The case of the string does not matter.
1571 To use this converter, include the following
1572 in your widget's ClassInitialize procedure:
1575 XtAddConverter(XtRString, XtRBackingStore, XmuCvtStringToBackingStore, NULL, 0);
1579 <para id="XmuCvtStringToBitmap">
1580 <indexterm zone="XmuCvtStringToBitmap">
1581 <primary><function>XmuCvtStringToBitmap</function></primary>
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>
1594 <term><parameter>args</parameter></term>
1596 the sole argument specifies the Screen on which to create the bitmap
1600 <term><parameter>num_args</parameter></term>
1606 <term><parameter>fromVal</parameter></term>
1608 specifies the string to convert
1612 <term><parameter>toVal</parameter></term>
1614 returns the converted value
1619 <indexterm zone="XmuCvtStringToBitmap">
1620 <primary>window manager icons</primary>
1622 This function creates a bitmap (a Pixmap of depth one) suitable for window
1623 manager icons. The string argument is the name of a file in standard bitmap
1624 file format. For the possible filename specifications, see
1625 <link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>.
1626 To use this converter, include the following in your widget's
1627 ClassInitialize procedure:
1630 static XtConvertArgRec screenConvertArg[] = {
1631 {XtBaseOffset, (XtPointer)XtOffset(Widget, core.screen), sizeof(Screen *)}
1634 XtAddConverter(XtRString, XtRBitmap, XmuCvtStringToBitmap,
1635 screenConvertArg, XtNumber(screenConvertArg));
1639 <para id="XmuCvtStringToColorCursor">
1640 <indexterm zone="XmuCvtStringToColorCursor">
1641 <primary><function>XmuCvtStringToColorCursor</function></primary>
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>
1656 <term><parameter>dpy</parameter></term>
1658 specifies the display to use for conversion warnings
1662 <term><parameter>args</parameter></term>
1664 specifies the required conversion arguments
1668 <term><parameter>num_args</parameter></term>
1670 specifies the number of required conversion arguments, which is 4
1674 <term><parameter>fromVal</parameter></term>
1676 specifies the string to convert
1680 <term><parameter>toVal</parameter></term>
1682 returns the converted value
1686 <term><parameter>data</parameter></term>
1688 this argument is ignored
1693 <indexterm zone="XmuCvtStringToColorCursor">
1694 <primary><type>Cursor</type></primary>
1696 This function converts a string to a
1698 with the foreground and background pixels specified by the conversion
1699 arguments. The string can either be a
1700 standard cursor name formed by removing the <code>“XC_”</code>
1701 prefix from any of the
1702 cursor defines listed in Appendix B of the Xlib Manual, a font name and
1703 glyph index in decimal of the form "FONT fontname index [[font] index]",
1704 or a bitmap filename acceptable to
1705 <link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>.
1706 To use this converter, include
1707 the following in the widget ClassInitialize procedure:
1710 static XtConvertArgRec colorCursorConvertArgs[] = {
1711 {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.screen),
1713 {XtResourceString, (XtPointer) XtNpointerColor, sizeof(Pixel)},
1714 {XtResourceString, (XtPointer) XtNpointerColorBackground, sizeof(Pixel)},
1715 {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.colormap),
1720 XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor,
1721 colorCursorConvertArgs, XtNumber(colorCursorConvertArgs),
1722 XtCacheByDisplay, NULL);
1725 The widget must recognize XtNpointerColor and XtNpointerColorBackground as
1726 resources, or specify other appropriate foreground and background resources.
1727 The widget's Realize and SetValues methods must cause the converter to be
1728 invoked with the appropriate arguments when one of the foreground,
1729 background, or cursor resources has changed, or when the window is created,
1730 and must assign the cursor to the window of the widget.
1733 <para id="XmuCvtStringToCursor">
1734 <indexterm zone="XmuCvtStringToCursor">
1735 <primary><function>XmuCvtStringToCursor</function></primary>
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>
1748 <term><parameter>args</parameter></term>
1750 specifies the required conversion argument, the screen
1754 <term><parameter>num_args</parameter></term>
1756 specifies the number of required conversion arguments, which is 1
1760 <term><parameter>fromVal</parameter></term>
1762 specifies the string to convert
1766 <term><parameter>toVal</parameter></term>
1768 returns the converted value
1773 <indexterm zone="XmuCvtStringToCursor">
1774 <primary><type>Cursor</type></primary>
1776 This function converts a string to a
1777 <type>Cursor</type>.
1778 The string can either be a
1779 standard cursor name formed by removing the <code>“XC_”</code>
1780 prefix from any of the
1781 cursor defines listed in Appendix B of the Xlib Manual, a font name and
1782 glyph index in decimal of the form "FONT fontname index [[font] index]", or
1783 a bitmap filename acceptable to
1784 <link linkend="XmuLocateBitmapFile"><function>XmuLocateBitmapFile</function></link>.
1785 To use this converter, include
1786 the following in your widget's ClassInitialize procedure:
1789 static XtConvertArgRec screenConvertArg[] = {
1790 {XtBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.screen), sizeof(Screen *)}
1793 XtAddConverter(XtRString, XtRCursor, XmuCvtStringToCursor,
1794 screenConvertArg, XtNumber(screenConvertArg));
1798 <para id="XmuCvtStringToGravity">
1799 <indexterm zone="XmuCvtStringToGravity">
1800 <primary><function>XmuCvtStringToGravity</function></primary>
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>
1813 <term><parameter>args</parameter></term>
1815 this argument is ignored
1819 <term><parameter>num_args</parameter></term>
1821 this argument must be a pointer to a Cardinal containing the value 0
1825 <term><parameter>fromVal</parameter></term>
1827 specifies the string to convert
1831 <term><parameter>toVal</parameter></term>
1833 returns the converted value
1838 <indexterm zone="XmuCvtStringToGravity">
1839 <primary><type>XtGravity</type></primary>
1841 This function converts a string to an
1842 <type>XtGravity</type>
1843 enumeration value. The string "forget" and a <symbol>NULL</symbol> value convert to
1844 <symbol>ForgetGravity</symbol>,
1845 "NorthWestGravity" converts to
1846 <symbol>NorthWestGravity</symbol>,
1847 the strings "NorthGravity" and "top" convert to
1848 <symbol>NorthGravity</symbol>,
1849 "NorthEastGravity" converts to
1850 <symbol>NorthEastGravity</symbol>,
1851 the strings "West" and "left" convert to
1852 <symbol>WestGravity</symbol>,
1853 "CenterGravity" converts to
1854 <symbol>CenterGravity</symbol>,
1855 "EastGravity" and "right" convert to
1856 <symbol>EastGravity</symbol>,
1857 "SouthWestGravity" converts to
1858 <symbol>SouthWestGravity</symbol>,
1859 "SouthGravity" and "bottom" convert to
1860 <symbol>SouthGravity</symbol>,
1861 "SouthEastGravity" converts to
1862 <symbol>SouthEastGravity</symbol>,
1863 "StaticGravity" converts to
1864 <symbol>StaticGravity</symbol>,
1865 and "UnmapGravity" converts to
1866 <symbol>UnmapGravity</symbol>.
1867 The case of the string does not matter. To use this converter, include
1868 the following in your widget's class initialize procedure:
1871 XtAddConverter(XtRString, XtRGravity, XmuCvtStringToGravity, NULL, 0);
1875 <para id="XmuCvtStringToJustify">
1876 <indexterm zone="XmuCvtStringToJustify">
1877 <primary><function>XmuCvtStringToJustify</function></primary>
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>
1890 <term><parameter>args</parameter></term>
1892 this argument is ignored
1896 <term><parameter>num_args</parameter></term>
1898 this argument is ignored
1902 <term><parameter>fromVal</parameter></term>
1904 specifies the string to convert
1908 <term><parameter>toVal</parameter></term>
1910 returns the converted value
1915 <indexterm zone="XmuCvtStringToJustify">
1916 <primary><type>XtJustify</type></primary>
1918 This function converts a string to an
1919 <type>XtJustify</type>
1920 enumeration value. The string "left" converts to
1921 <symbol>XtJustifyLeft</symbol>,
1922 "center" converts to
1923 <symbol>XtJustifyCenter</symbol>,
1924 and "right" converts to
1925 <symbol>XtJustifyRight</symbol>.
1926 The case of the string does not matter. To use this converter,
1927 include the following in your widget's ClassInitialize procedure:
1930 XtAddConverter(XtRString, XtRJustify, XmuCvtStringToJustify, NULL, 0);
1934 <para id="XmuCvtStringToLong">
1935 <indexterm zone="XmuCvtStringToLong">
1936 <primary><function>XmuCvtStringToLong</function></primary>
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>
1949 <term><parameter>args</parameter></term>
1951 this argument is ignored
1955 <term><parameter>num_args</parameter></term>
1957 this argument must be a pointer to a Cardinal containing 0
1961 <term><parameter>fromVal</parameter></term>
1963 specifies the string to convert
1967 <term><parameter>toVal</parameter></term>
1969 returns the converted value
1974 This function converts a string to an integer of type long. It parses the
1976 <function>sscanf</function>
1977 with a format of "%ld". To use this converter, include
1978 the following in your widget's ClassInitialize procedure:
1981 XtAddConverter(XtRString, XtRLong, XmuCvtStringToLong, NULL, 0);
1985 <para id="XmuCvtStringToOrientation">
1986 <indexterm zone="XmuCvtStringToOrientation">
1987 <primary><function>XmuCvtStringToOrientation</function></primary>
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>
2000 <term><parameter>args</parameter></term>
2002 this argument is ignored
2006 <term><parameter>num_args</parameter></term>
2008 this argument is ignored
2012 <term><parameter>fromVal</parameter></term>
2014 specifies the string to convert
2018 <term><parameter>toVal</parameter></term>
2020 returns the converted value
2025 <indexterm zone="XmuCvtStringToOrientation">
2026 <primary><type>XtOrientation</type></primary>
2028 This function converts a string to an
2029 <type>XtOrientation</type>
2030 enumeration value. The string "horizontal" converts to
2031 <symbol>XtorientHorizontal</symbol>
2032 and "vertical" converts to
2033 <symbol>XtorientVertical</symbol>.
2034 The case of the string does not matter. To use this converter,
2035 include the following in your widget's ClassInitialize procedure:
2038 XtAddConverter(XtRString, XtROrientation, XmuCvtStringToOrientation, NULL, 0);
2042 <para id="XmuCvtStringToShapeStyle">
2043 <indexterm zone="XmuCvtStringToShapeStyle">
2044 <primary><function>XmuCvtStringToShapeStyle</function></primary>
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>
2059 <term><parameter>dpy</parameter></term>
2061 the display to use for conversion warnings
2065 <term><parameter>args</parameter></term>
2067 this argument is ignored
2071 <term><parameter>num_args</parameter></term>
2073 this argument is ignored
2077 <term><parameter>fromVal</parameter></term>
2079 the value to convert from
2083 <term><parameter>toVal</parameter></term>
2085 the place to store the converted value
2089 <term><parameter>data</parameter></term>
2091 this argument is ignored
2096 This function converts a string to an integer shape style. The string
2097 "rectangle" converts to
2098 <symbol>XmuShapeRectangle</symbol>,
2100 <symbol>XmuShapeOval</symbol>,
2101 "ellipse" converts to
2102 <symbol>XmuShapeEllipse</symbol>,
2103 and "roundedRectangle" converts to
2104 <symbol>XmuShapeRoundedRectangle</symbol>.
2105 The case of the string does not matter. To use this converter,
2106 include the following in your widget's ClassInitialize procedure:
2109 XtSetTypeConverter(XtRString, XtRShapeStyle, XmuCvtStringToShapeStyle,
2110 NULL, 0, XtCacheNone, NULL);
2114 <para id="XmuReshapeWidget">
2115 <indexterm zone="XmuReshapeWidget">
2116 <primary><function>XmuReshapeWidget</function></primary>
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>
2129 <term><parameter>w</parameter></term>
2131 specifies the widget to reshape
2135 <term><parameter>shape_style</parameter></term>
2137 specifies the new shape
2141 <term><parameter>corner_width</parameter></term>
2143 specifies the width of the rounded rectangle corner
2147 <term><parameter>corner_height</parameter></term>
2149 specified the height of the rounded rectangle corner
2154 <indexterm zone="XmuReshapeWidget">
2155 <primary>Shape extension</primary>
2157 This function reshapes the specified widget, using the Shape extension, to a
2158 rectangle, oval, ellipse, or rounded rectangle, as specified by shape_style
2160 <symbol>XmuShapeRectangle</symbol>,
2161 <symbol>XmuShapeOval</symbol>,
2162 <symbol>XmuShapeEllipse</symbol>,
2164 <symbol>XmuShapeRoundedRectangle</symbol>,
2166 The shape is bounded by the outside edges of the rectangular extents of the
2167 widget. If the shape is a rounded rectangle, corner_width and corner_height
2168 specify the size of the bounding box that the corners are drawn inside of
2170 <link linkend="XmuFillRoundedRectangle"><function>XmuFillRoundedRectangle</function></link>);
2171 otherwise, corner_width and corner_height are ignored.
2172 The origin of the widget within its parent remains unchanged.
2175 <para id="XmuCvtStringToWidget">
2176 <indexterm zone="XmuCvtStringToWidget">
2177 <primary><function>XmuCvtStringToWidget</function></primary>
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>
2190 <term><parameter>args</parameter></term>
2192 the sole argument is the parent Widget
2196 <term><parameter>num_args</parameter></term>
2198 this argument must be 1
2202 <term><parameter>fromVal</parameter></term>
2204 specifies the string to convert
2208 <term><parameter>toVal</parameter></term>
2210 returns the converted value
2215 This function converts a string to an immediate child widget of the parent
2216 widget passed as an argument. Note that this converter only works for
2217 child widgets that have already been created; there is no lazy evaluation.
2218 The string is first compared against the
2219 names of the normal and popup children, and if a match is found the
2220 corresponding child is returned. If no match is found, the string is
2221 compared against the classes of the normal and popup children, and if a
2222 match is found the corresponding child is returned. The case of the string
2223 is significant. To use this converter, include the following in your
2224 widget's ClassInitialize procedure:
2227 static XtConvertArgRec parentCvtArg[] = {
2228 {XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)},
2231 XtAddConverter(XtRString, XtRWidget, XmuCvtStringToWidget,
2232 parentCvtArg, XtNumber(parentCvtArg));
2236 <para id="XmuNewCvtStringToWidget">
2237 <indexterm zone="XmuNewCvtStringToWidget">
2238 <primary><function>XmuNewCvtStringToWidget</function></primary>
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>
2253 <term><parameter>dpy</parameter></term>
2255 the display to use for conversion warnings
2259 <term><parameter>args</parameter></term>
2261 the sole argument is the parent Widget
2265 <term><parameter>num_args</parameter></term>
2267 this argument must be a pointer to a Cardinal containing the value 1
2271 <term><parameter>fromVal</parameter></term>
2273 specifies the string to convert
2277 <term><parameter>toVal</parameter></term>
2279 returns the converted value
2283 <term><parameter>data</parameter></term>
2285 this argument is ignored
2290 This converter is identical in functionality to
2291 <link linkend="XmuCvtStringToWidget"><function>XmuCvtStringToWidget</function></link>, except
2292 that it is a new-style converter, allowing the specification of a cache type
2293 at the time of registration.
2294 Most widgets will not cache the conversion results, as the application may
2295 dynamically create and destroy widgets, which would cause cached values to
2296 become illegal. To use this converter, include the following in the widget's
2297 class initialize procedure:
2300 static XtConvertArgRec parentCvtArg[] = {
2301 {XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.parent),
2305 XtSetTypeConverter(XtRString, XtRWidget, XmuNewCvtStringToWidget,
2306 parentCvtArg, XtNumber(parentCvtArg), XtCacheNone, NULL);
2313 <sect1 id='Character_Set_Functions'>
2314 <title>Character Set Functions</title>
2317 To use the functions defined in this section, you should include the header
2319 <<filename class='headerfile'>X11/Xmu/CharSet.h</filename>>
2321 <primary><filename class='headerfile'>X11/Xmu/CharSet.h</filename></primary>
2323 and link against the libXmu or libXmuu library.
2327 The functions in this section are <emphasis remap='B'>deprecated</emphasis>
2328 because they don't work in most locales now supported by X11; most platforms
2329 provide alternatives in their system libraries.
2332 <para id="XmuCopyISOLatin1Lowered">
2333 <indexterm zone="XmuCopyISOLatin1Lowered">
2334 <primary><function>XmuCopyISOLatin1Lowered</function></primary>
2338 <funcdef>void <function>XmuCopyISOLatin1Lowered</function></funcdef>
2339 <paramdef>char *<parameter>dst</parameter></paramdef>
2340 <paramdef>const char *<parameter>src</parameter></paramdef>
2345 <term><parameter>dst</parameter></term>
2347 returns the string copy
2351 <term><parameter>src</parameter></term>
2353 specifies the string to copy
2358 This function copies a null terminated string from src to dst (including the
2359 null), changing all Latin-1 uppercase letters to lowercase. The string is
2360 assumed to be encoded using ISO 8859-1.
2364 Note that like <function>strcpy</function> the caller is responsible for
2365 ensuring the size of <parameter>dst</parameter> is at least as large as the
2366 size of <parameter>src</parameter>.
2369 <para id="XmuNCopyISOLatin1Lowered">
2370 <indexterm zone="XmuNCopyISOLatin1Lowered">
2371 <primary><function>XmuNCopyISOLatin1Lowered</function></primary>
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>
2383 <term><parameter>dst</parameter></term>
2385 returns the string copy
2389 <term><parameter>src</parameter></term>
2391 specifies the string to copy
2395 <term><parameter>size</parameter></term>
2397 maximum number of characters (including the null terminator) to write to dst
2402 This function copies up to <code><parameter>size</parameter> - 1</code>
2403 characters of a null terminated string from <parameter>src</parameter>
2404 to <parameter>dst</parameter>, and terminates it with a null,
2405 changing all Latin-1 uppercase letters to lowercase. The string is
2406 assumed to be encoded using ISO 8859-1.
2409 <para id="XmuCopyISOLatin1Uppered">
2410 <indexterm zone="XmuCopyISOLatin1Uppered">
2411 <primary><function>XmuCopyISOLatin1Uppered</function></primary>
2415 <funcdef>void <function>XmuCopyISOLatin1Uppered</function></funcdef>
2416 <paramdef>char *<parameter>dst</parameter></paramdef>
2417 <paramdef>const char *<parameter>src</parameter></paramdef>
2422 <term><parameter>dst</parameter></term>
2424 returns the string copy
2428 <term><parameter>src</parameter></term>
2430 specifies the string to copy
2435 This function copies a null terminated string from src to dst (including the
2436 null), changing all Latin-1 lowercase letters to uppercase. The string is
2437 assumed to be encoded using ISO 8859-1.
2441 Note that like <function>strcpy</function> the caller is responsible for
2442 ensuring the size of <parameter>dst</parameter> is at least as large as the
2443 size of <parameter>src</parameter>.
2446 <para id="XmuNCopyISOLatin1Uppered">
2447 <indexterm zone="XmuNCopyISOLatin1Uppered">
2448 <primary><function>XmuNCopyISOLatin1Uppered</function></primary>
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>
2460 <term><parameter>dst</parameter></term>
2462 returns the string copy
2466 <term><parameter>src</parameter></term>
2468 specifies the string to copy
2472 <term><parameter>size</parameter></term>
2474 maximum number of characters (including the null terminator) to write to dst
2479 This function copies up to <code><parameter>size</parameter> - 1</code>
2480 characters of a null terminated string from <parameter>src</parameter>
2481 to <parameter>dst</parameter>, and terminates it with a null,
2482 changing all Latin-1 lowercase letters to uppercase. The string is
2483 assumed to be encoded using ISO 8859-1.
2486 <para id="XmuCompareISOLatin1">
2487 <indexterm zone="XmuCompareISOLatin1">
2488 <primary><function>XmuCompareISOLatin1</function></primary>
2492 <funcdef>int <function>XmuCompareISOLatin1</function></funcdef>
2493 <paramdef>const char *<parameter>first</parameter></paramdef>
2494 <paramdef>const char *<parameter>second</parameter></paramdef>
2499 <term><parameter>first</parameter></term>
2501 specifies a string to compare
2505 <term><parameter>second</parameter></term>
2507 specifies a string to compare
2512 This function compares two null terminated Latin-1 strings, ignoring case
2513 differences, and returns an integer greater than, equal to, or less than 0,
2514 according to whether first is lexicographically greater than, equal to, or
2515 less than second. The two strings are assumed to be encoded using ISO
2520 <sect1 id='Keyboard_Event_Translation_Functions'>
2521 <title>Keyboard Event Translation Functions</title>
2524 To use the functions defined in this section, you should include the header
2526 <<filename class='headerfile'>X11/Xmu/Lookup.h</filename>>
2528 <primary><filename class='headerfile'>X11/Xmu/Lookup.h</filename></primary>
2530 and link against the libXmu library.
2534 The functions in this section are <emphasis remap='B'>deprecated</emphasis> because they don't work
2535 in most locales now supported by X11; the function
2536 <olink targetdoc='libX11' targetptr='XmbLookupString'><function>XmbLookupString</function></olink>
2537 provides a better alternative.
2540 <para id="XmuLookupLatin1">
2541 <indexterm zone="XmuLookupLatin1">
2542 <primary><function>XmuLookupLatin1</function></primary>
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>
2556 <term><parameter>event</parameter></term>
2558 specifies the key event
2562 <term><parameter>buffer</parameter></term>
2564 returns the translated characters
2568 <term><parameter>nbytes</parameter></term>
2570 specifies the length of the buffer
2574 <term><parameter>keysym</parameter></term>
2576 returns the computed KeySym, or None
2580 <term><parameter>status</parameter></term>
2582 specifies or returns the compose state
2587 This function is identical to
2588 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2589 and exists only for naming symmetry with other functions.
2592 <para id="XmuLookupLatin2">
2593 <indexterm zone="XmuLookupLatin2">
2594 <primary><function>XmuLookupLatin2</function></primary>
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>
2608 <term><parameter>event</parameter></term>
2610 specifies the key event
2614 <term><parameter>buffer</parameter></term>
2616 returns the translated characters
2620 <term><parameter>nbytes</parameter></term>
2622 specifies the length of the buffer
2626 <term><parameter>keysym</parameter></term>
2628 returns the computed KeySym, or None
2632 <term><parameter>status</parameter></term>
2634 specifies or returns the compose state
2639 This function is similar to
2640 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2641 except that it maps a key event
2642 to an Latin-2 (ISO 8859-2) string, or to an ASCII control string.
2645 <para id="XmuLookupLatin3">
2646 <indexterm zone="XmuLookupLatin3">
2647 <primary><function>XmuLookupLatin3</function></primary>
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>
2661 <term><parameter>event</parameter></term>
2663 specifies the key event
2667 <term><parameter>buffer</parameter></term>
2669 returns the translated characters
2673 <term><parameter>nbytes</parameter></term>
2675 specifies the length of the buffer
2679 <term><parameter>keysym</parameter></term>
2681 returns the computed KeySym, or None
2685 <term><parameter>status</parameter></term>
2687 specifies or returns the compose state
2692 This function is similar to
2693 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2694 except that it maps a key event
2695 to an Latin-3 (ISO 8859-3) string, or to an ASCII control string.
2698 <para id="XmuLookupLatin4">
2699 <indexterm zone="XmuLookupLatin4">
2700 <primary><function>XmuLookupLatin4</function></primary>
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>
2714 <term><parameter>event</parameter></term>
2716 specifies the key event
2720 <term><parameter>buffer</parameter></term>
2722 returns the translated characters
2726 <term><parameter>nbytes</parameter></term>
2728 specifies the length of the buffer
2732 <term><parameter>keysym</parameter></term>
2734 returns the computed KeySym, or None
2738 <term><parameter>status</parameter></term>
2740 specifies or returns the compose state
2745 This function is similar to
2746 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2747 except that it maps a key event
2748 to an Latin-4 (ISO 8859-4) string, or to an ASCII control string.
2751 <para id="XmuLookupKana">
2752 <indexterm zone="XmuLookupKana">
2753 <primary><function>XmuLookupKana</function></primary>
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>
2767 <term><parameter>event</parameter></term>
2769 specifies the key event
2773 <term><parameter>buffer</parameter></term>
2775 returns the translated characters
2779 <term><parameter>nbytes</parameter></term>
2781 specifies the length of the buffer
2785 <term><parameter>keysym</parameter></term>
2787 returns the computed KeySym, or None
2791 <term><parameter>status</parameter></term>
2793 specifies or returns the compose state
2798 This function is similar to
2799 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2800 except that it maps a key event
2801 to a string in an encoding consisting of Latin-1 (ISO 8859-1) and ASCII
2802 control in the Graphics Left half (values 0 to 127), and Katakana in the
2803 Graphics Right half (values 128 to 255), using the values from JIS
2807 <para id="XmuLookupJISX0201">
2808 <indexterm zone="XmuLookupJISX0201">
2809 <primary><function>XmuLookupJISX0201</function></primary>
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>
2823 <term><parameter>event</parameter></term>
2825 specifies the key event
2829 <term><parameter>buffer</parameter></term>
2831 returns the translated characters
2835 <term><parameter>nbytes</parameter></term>
2837 specifies the length of the buffer
2841 <term><parameter>keysym</parameter></term>
2843 returns the computed KeySym, or None
2847 <term><parameter>status</parameter></term>
2849 specifies or returns the compose state
2854 This function is similar to
2855 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2856 except that it maps a key event
2857 to a string in the JIS X0201-1976 encoding, including ASCII control.
2860 <para id="XmuLookupArabic">
2861 <indexterm zone="XmuLookupArabic">
2862 <primary><function>XmuLookupArabic</function></primary>
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>
2876 <term><parameter>event</parameter></term>
2878 specifies the key event
2882 <term><parameter>buffer</parameter></term>
2884 returns the translated characters
2888 <term><parameter>nbytes</parameter></term>
2890 specifies the length of the buffer
2894 <term><parameter>keysym</parameter></term>
2896 returns the computed KeySym, or None
2900 <term><parameter>status</parameter></term>
2902 specifies or returns the compose state
2907 This function is similar to
2908 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2909 except that it maps a key event
2910 to a Latin/Arabic (ISO 8859-6) string, or to an ASCII control string.
2913 <para id="XmuLookupCyrillic">
2914 <indexterm zone="XmuLookupCyrillic">
2915 <primary><function>XmuLookupCyrillic</function></primary>
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>
2929 <term><parameter>event</parameter></term>
2931 specifies the key event
2935 <term><parameter>buffer</parameter></term>
2937 returns the translated characters
2941 <term><parameter>nbytes</parameter></term>
2943 specifies the length of the buffer
2947 <term><parameter>keysym</parameter></term>
2949 returns the computed KeySym, or None
2953 <term><parameter>status</parameter></term>
2955 specifies or returns the compose state
2960 This function is similar to
2961 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
2962 except that it maps a key event
2963 to a Latin/Cyrillic (ISO 8859-5) string, or to an ASCII control string.
2966 <para id="XmuLookupGreek">
2967 <indexterm zone="XmuLookupGreek">
2968 <primary><function>XmuLookupGreek</function></primary>
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>
2982 <term><parameter>event</parameter></term>
2984 specifies the key event
2988 <term><parameter>buffer</parameter></term>
2990 returns the translated characters
2994 <term><parameter>nbytes</parameter></term>
2996 specifies the length of the buffer
3000 <term><parameter>keysym</parameter></term>
3002 returns the computed KeySym, or None
3006 <term><parameter>status</parameter></term>
3008 specifies or returns the compose state
3013 This function is similar to
3014 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
3015 except that it maps a key event
3016 to a Latin/Greek (ISO 8859-7) string, or to an ASCII control string.
3019 <para id="XmuLookupHebrew">
3020 <indexterm zone="XmuLookupHebrew">
3021 <primary><function>XmuLookupHebrew</function></primary>
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>
3035 <term><parameter>event</parameter></term>
3037 specifies the key event
3041 <term><parameter>buffer</parameter></term>
3043 returns the translated characters
3047 <term><parameter>nbytes</parameter></term>
3049 specifies the length of the buffer
3053 <term><parameter>keysym</parameter></term>
3055 returns the computed KeySym, or None
3059 <term><parameter>status</parameter></term>
3061 specifies or returns the compose state
3066 This function is similar to
3067 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
3068 except that it maps a key event
3069 to a Latin/Hebrew (ISO 8859-8) string, or to an ASCII control string.
3072 <para id="XmuLookupAPL">
3073 <indexterm zone="XmuLookupAPL">
3074 <primary><function>XmuLookupAPL</function></primary>
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>
3088 <term><parameter>event</parameter></term>
3090 specifies the key event
3094 <term><parameter>buffer</parameter></term>
3096 returns the translated characters
3100 <term><parameter>nbytes</parameter></term>
3102 specifies the length of the buffer
3106 <term><parameter>keysym</parameter></term>
3108 returns the computed KeySym, or None
3112 <term><parameter>status</parameter></term>
3114 specifies or returns the compose state
3119 This function is similar to
3120 <olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>,
3121 except that it maps a key event to an APL string.
3126 <sect1 id='Compound_Text_Functions'>
3127 <title>Compound Text Functions</title>
3130 The functions defined in this section are for parsing Compound Text strings,
3131 decomposing them into individual segments. Definitions needed to use these
3132 routines are in the include file
3133 <<filename class='headerfile'>X11/Xmu/Xct.h</filename>>
3135 <primary><filename class='headerfile'>X11/Xmu/Xct.h</filename></primary>
3137 and link against the libXmu library.
3141 The functions in this section are <emphasis remap='B'>deprecated</emphasis> because they shift the
3142 burden for recently introduced locale encodings to the application. The
3144 <symbol>UTF8_STRING</symbol>
3145 text encoding provides a better alternative.
3149 A Compound Text string is represented as the following type:
3152 typedef unsigned char *XctString;
3156 <para id="XctCreate">
3157 <indexterm zone="XctCreate">
3158 <primary><function>XctCreate</function></primary>
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>
3170 <term><parameter>string</parameter></term>
3172 the Compound Text string
3176 <term><parameter>length</parameter></term>
3178 the number of bytes in string
3182 <term><parameter>flags</parameter></term>
3184 parsing control flags
3189 This function creates an
3190 <type>XctData</type>
3191 structure for parsing a Compound Text
3192 string. The string need not be null terminated. The following flags are
3193 defined to control parsing of the string:
3197 <term><symbol>XctSingleSetSegments</symbol></term>
3199 This means that returned segments should contain
3200 characters from only one set (C0, C1, GL, GR). When this is requested,
3201 <symbol>XctSegment</symbol>
3202 is never returned by
3203 <function>XctNextItem</function>,
3205 <symbol>XctC0Segment</symbol>,
3206 <symbol>XctC1Segment</symbol>,
3207 <symbol>XctGlSegment</symbol>,
3209 <symbol>XctGRSegment</symbol>
3210 are returned. C0 and C1
3211 segments are always returned as singleton characters.
3216 <term><symbol>XctProvideExtensions</symbol></term>
3218 This means that if the Compound Text string is from a
3219 higher version than this code is implemented to, then syntactically correct
3220 but unknown control sequences should be returned as
3221 <symbol>XctExtension</symbol>
3223 <function>XctNextItem</function>.
3224 If this flag is not set, and the Compound Text string version
3225 indicates that extensions cannot be ignored, then each unknown control
3226 sequence will be reported as an
3227 <symbol>XctError</symbol>.
3232 <term><symbol>XctAcceptC0Extensions</symbol></term>
3234 This means that if the Compound Text string is from
3235 a higher version than this code is implemented to, then unknown C0
3236 characters should be treated as if they were legal, and returned as C0
3237 characters (regardless of how
3238 <symbol>XctProvideExtensions</symbol>
3240 <function>XctNextItem</function>.
3241 If this flag is not set, then all unknown C0 characters are treated
3243 <symbol>XctProvideExtensions</symbol>.
3248 <term><symbol>XctAcceptC1Extensions</symbol></term>
3250 This means that if the Compound Text string is from
3251 a higher version than this code is implemented to, then unknown C1
3252 characters should be treated as if they were legal, and returned as C1
3253 characters (regardless of how
3254 <symbol>XctProvideExtensions</symbol>
3256 <function>XctNextItem</function>.
3257 If this flag is not set, then all unknown C1 characters are treated
3259 <symbol>XctProvideExtensions</symbol>.
3263 <term><symbol>XctHideDirection</symbol></term>
3265 This means that horizontal direction changes should be
3267 <symbol>XctHorizontal</symbol>
3269 <function>XctNextItem</function>. If this flag is not set,
3270 then direction changes are not returned as items, but the current direction
3271 is still maintained and reported for other items. The current direction is
3272 given as an enumeration, with the values
3273 <symbol>XctUnspecified</symbol>,
3274 <symbol>XctLeftToRight</symbol>,
3276 <symbol>XctRightToLeft</symbol>.
3280 <term><symbol>XctFreeString</symbol></term>
3283 <function>XctFree</function>
3284 should free the Compound Text string that is passed to
3285 <function>XctCreate</function>.
3286 If this flag is not set, the string is not freed.
3291 <term><symbol>XctShiftMultiGRToGL</symbol></term>
3294 <function>XctNextItem</function>
3296 segments on-the-fly into GL segments for the GR sets: GB2312.1980-1,
3297 JISX0208.1983-1, and KSC5601.1987-1.
3303 <para id="XctReset">
3304 <indexterm zone="XctReset">
3305 <primary><function>XctReset</function></primary>
3309 <funcdef>void <function>XctReset</function></funcdef>
3310 <paramdef>XctData <parameter>data</parameter></paramdef>
3315 <term><parameter>data</parameter></term>
3317 specifies the Compound Text structure
3322 This function resets the
3323 <type>XctData</type>
3324 structure to reparse the Compound Text string from the beginning.
3327 <para id="XctNextItem">
3328 <indexterm zone="XctNextItem">
3329 <primary><function>XctNextItem</function></primary>
3333 <funcdef>XctResult <function>XctNextItem</function></funcdef>
3334 <paramdef>XctData <parameter>data</parameter></paramdef>
3339 <term><parameter>data</parameter></term>
3341 specifies the Compound Text structure
3346 This function parses the next “item” from the Compound Text string. The
3347 return value indicates what kind of item is returned. The item itself, its
3348 length, and the current contextual state, are reported as components of the
3349 <type>XctData</type>
3351 <type>XctResult</type>
3352 is an enumeration, with the following values:
3356 <term><symbol>XctSegment</symbol></term>
3358 the item contains some mixture of C0, GL, GR, and C1 characters.
3363 <term><symbol>XctC0Segment</symbol></term>
3365 the item contains only C0 characters.
3370 <term><symbol>XctGLSegment</symbol></term>
3372 the item contains only GL characters.
3377 <term><symbol>XctC1Segment</symbol></term>
3379 the item contains only C1 characters.
3384 <term><symbol>XctGRSegment</symbol></term>
3386 the item contains only GR characters.
3391 <term><symbol>XctExtendedSegment</symbol></term>
3393 the item contains an extended segment.
3398 <term><symbol>XctExtension</symbol></term>
3400 the item is an unknown extension control sequence.
3405 <term><symbol>XctHorizontal</symbol></term>
3407 the item indicates a change in horizontal direction or
3408 depth. The new direction and depth are recorded in the
3409 <type>XctData</type>
3415 <term><symbol>XctEndOfText</symbol></term>
3417 The end of the Compound Text string has been reached.
3422 <term><symbol>XctError</symbol></term>
3424 the string contains a syntactic or semantic error; no further
3425 parsing should be performed.
3432 <indexterm zone="XctData">
3433 <primary><type>XctData</type></primary>
3435 The following state values are stored in the
3436 <type>XctData</type>
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 */
3461 <funcdef>void <function>XctFree</function></funcdef>
3462 <paramdef>XctData <parameter>data</parameter></paramdef>
3467 <term><parameter>data</parameter></term>
3469 specifies the Compound Text structure
3474 This function frees all data associated with the
3475 <type>XctData</type>
3481 <sect1 id='CloseDisplay_Hook_Functions'>
3482 <title>CloseDisplay Hook Functions</title>
3485 To use the functions defined in this section, you should include the header
3487 <<filename class='headerfile'>X11/Xmu/CloseHook.h</filename>>
3489 <primary><filename class='headerfile'>X11/Xmu/CloseHook.h</filename></primary>
3491 and link against the libXmu library.
3494 <para id="XmuAddCloseDisplayHook">
3495 <indexterm zone="XmuAddCloseDisplayHook">
3496 <primary><function>XmuAddCloseDisplayHook</function></primary>
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>
3509 <term><parameter>dpy</parameter></term>
3511 specifies the connection to the X server
3515 <term><parameter>func</parameter></term>
3517 specifies the function to call at display close
3521 <term><parameter>arg</parameter></term>
3523 specifies arbitrary data to pass to <parameter>func</parameter>
3528 This function adds a callback for the given display. When the display is
3529 closed, the given function will be called with the given display and
3538 The function is declared to return an int even though the value is ignored,
3539 because some compilers used to have problems with functions returning void.
3543 This routine returns <symbol>NULL</symbol> if it was unable to add the
3544 callback, otherwise it
3545 returns an opaque handle that can be used to remove or lookup the callback.
3548 <para id="XmuRemoveCloseDisplayHook">
3549 <indexterm zone="XmuRemoveCloseDisplayHook">
3550 <primary><function>XmuRemoveCloseDisplayHook</function></primary>
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>
3564 <term><parameter>dpy</parameter></term>
3566 specifies the connection to the X server
3570 <term><parameter>handle</parameter></term>
3572 specifies the callback by id, or <symbol>NULL</symbol>
3576 <term><function>func</function></term>
3578 specifies the callback by function
3582 <term><parameter>arg</parameter></term>
3584 specifies the function data to match
3589 This function deletes a callback that has been added with
3590 <function>XmuAddCloseDisplayHook</function>.
3591 If handle is not <symbol>NULL</symbol>, it specifies the callback to
3592 remove, and the func and arg parameters are ignored. If handle is <symbol>NULL</symbol>, the
3593 first callback found to match the specified func and arg will be removed.
3595 <symbol>True</symbol>
3596 if a callback was removed, else returns
3597 <symbol>False</symbol>.
3600 <para id="XmuLookupCloseDisplayHook">
3601 <indexterm zone="XmuLookupCloseDisplayHook">
3602 <primary><function>XmuLookupCloseDisplayHook</function></primary>
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>
3616 <term><parameter>dpy</parameter></term>
3618 specifies the connection to the X server
3622 <term><parameter>handle</parameter></term>
3624 specifies the callback by id, or <symbol>NULL</symbol>
3628 <term><function>func</function></term>
3630 specifies the callback by function
3634 <term><parameter>arg</parameter></term>
3636 specifies the function data to match
3641 This function determines if a callback is installed. If handle is not
3642 <symbol>NULL</symbol>,
3643 it specifies the callback to look for, and the func and arg parameters are
3644 ignored. If handle is <symbol>NULL</symbol>, the function will look for
3645 any callback for the
3646 specified func and arg. Returns
3647 <symbol>True</symbol>
3648 if a matching callback exists, else returns
3649 <symbol>False</symbol>.
3655 <sect1 id='Display_Queue_Functions'>
3656 <title>Display Queue Functions</title>
3659 To use the functions and types defined in this section, you should include the
3661 <<filename class='headerfile'>X11/Xmu/DisplayQue.h</filename>>
3663 <primary><filename class='headerfile'>X11/Xmu/DisplayQue.h</filename></primary>
3665 and link against the libXmu library.
3666 <filename class='headerfile'>DisplayQue.h</filename> defines the following
3669 <indexterm zone="XmuDisplayQueue">
3670 <primary><type>XmuDisplayQueue</type></primary>
3672 <synopsis id="XmuDisplayQueue">
3673 typedef int (*XmuCloseDisplayQueueProc)(XmuDisplayQueue *queue,
3674 XmuDisplayQueueEntry *entry);
3676 typedef int (*XmuFreeDisplayQueueProc)(XmuDisplayQueue *queue);
3678 typedef struct _XmuDisplayQueueEntry {
3679 struct _XmuDisplayQueueEntry *prev, *next;
3681 CloseHook closehook;
3683 } XmuDisplayQueueEntry;
3685 typedef struct _XmuDisplayQueue {
3687 XmuDisplayQueueEntry *head, *tail;
3688 XmuCloseDisplayQueueProc closefunc;
3689 XmuFreeDisplayQueueProc freefunc;
3695 <para id="XmuDQCreate">
3696 <indexterm zone="XmuDQCreate">
3697 <primary><function>XmuDQCreate</function></primary>
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>
3709 <term><parameter>closefunc</parameter></term>
3711 specifies the close function
3715 <term><parameter>freefunc</parameter></term>
3717 specifies the free function
3721 <term><parameter>data</parameter></term>
3723 specifies private data for the functions
3728 This function creates and returns an empty
3729 <type>XmuDisplayQueue</type>
3730 (which is really just a set of displays, but is called a queue for
3731 historical reasons). The queue is initially empty, but displays
3733 <function>XmuAddDisplay</function>.
3734 The data value is simply stored in the queue for use by the closefunc
3735 and freefunc callbacks.
3736 Whenever a display in the queue is closed using
3737 <function>XCloseDisplay</function>,
3738 the <parameter>closefunc</parameter> (if non-<symbol>NULL</symbol>) is called with the queue and the display's
3739 <function>XmuDisplayQueueEntry</function>
3742 (*closefunc)(queue, entry)
3747 The <parameter>freefunc</parameter> (if non-<symbol>NULL</symbol>) is called whenever the last
3749 queue is closed, as follows:
3757 The application is responsible for actually freeing the queue, by calling
3758 <function>XmuDQDestroy</function>.
3761 <para id="XmuDQAddDisplay">
3762 <indexterm zone="XmuDQAddDisplay">
3763 <primary><function>XmuDQAddDisplay</function></primary>
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>
3776 <term><parameter>q</parameter></term>
3782 <term><parameter>dpy</parameter></term>
3784 specifies the display to add
3788 <term><parameter>data</parameter></term>
3790 specifies private data for the free function
3795 This function adds the specified display to the queue. If successful,
3796 the queue entry is returned, otherwise <symbol>NULL</symbol> is returned.
3797 The data value is simply stored in the queue entry for use by the
3798 queue's freefunc callback. This function does not attempt to prevent
3799 duplicate entries in the queue; the caller should use
3800 <function>XmuDQLookupDisplay</function>
3801 to determine if a display has already been added to a queue.
3804 <para id="XmuDQLookupDisplay">
3805 <indexterm zone="XmuDQLookupDisplay">
3806 <primary><function>XmuDQLookupDisplay</function></primary>
3810 <funcdef>XmuDisplayQueueEntry *<function>XmuDQLookupDisplay</function></funcdef>
3811 <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3812 <paramdef>Display *<parameter>dpy</parameter></paramdef>
3817 <term><parameter>q</parameter></term>
3823 <term><parameter>dpy</parameter></term>
3825 specifies the display to lookup
3830 This function returns the queue entry for the specified display, or
3831 <symbol>NULL</symbol> if
3832 the display is not in the queue.
3835 <para id="XmuDQNDisplays">
3836 <indexterm zone="XmuDQNDisplays">
3837 <primary><function>XmuDQNDisplays</function></primary>
3841 <funcdef><function>XmuDQNDisplays</function></funcdef>
3842 <paramdef><parameter>q</parameter></paramdef>
3845 This macro returns the number of displays in the specified queue.
3848 <para id="XmuDQRemoveDisplay">
3849 <indexterm zone="XmuDQRemoveDisplay">
3850 <primary><function>XmuDQRemoveDisplay</function></primary>
3854 <funcdef>Bool <function>XmuDQRemoveDisplay</function></funcdef>
3855 <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3856 <paramdef>Display *<parameter>dpy</parameter></paramdef>
3861 <term><parameter>q</parameter></term>
3867 <term><parameter>dpy</parameter></term>
3869 specifies the display to remove
3874 This function removes the specified display from the specified queue.
3875 No callbacks are performed.
3876 If the display is not found in the queue,
3877 <symbol>False</symbol>
3878 is returned, otherwise
3879 <symbol>True</symbol>
3883 <para id="XmuDQDestroy">
3884 <indexterm zone="XmuDQDestroy">
3885 <primary><function>XmuDQDestroy</function></primary>
3889 <funcdef>Bool <function>XmuDQDestroy</function></funcdef>
3890 <paramdef>XmuDisplayQueue *<parameter>q</parameter></paramdef>
3891 <paramdef>Bool <parameter>docallbacks</parameter></paramdef>
3896 <term><parameter>q</parameter></term>
3898 specifies the queue to destroy
3902 <term><parameter>docallbacks</parameter></term>
3904 specifies whether close functions should be called
3909 This function releases all memory associated with the specified queue.
3911 <symbol>True</symbol>,
3912 then the queue's closefunc callback (if non-<symbol>NULL</symbol>) is first called
3913 for each display in the queue, even though
3914 <function>XCloseDisplay</function>
3915 is not called on the display.
3920 <sect1 id='Toolkit_Convenience_Functions'>
3921 <title>Toolkit Convenience Functions</title>
3924 To use the functions defined in this section, you should include the header
3926 <<filename class='headerfile'>X11/Xmu/Initer.h</filename>>
3928 <primary><filename class='headerfile'>X11/Xmu/Initer.h</filename></primary>
3930 and link against the libXmu library.
3933 <para id="XmuAddInitializer">
3934 <indexterm zone="XmuAddInitializer">
3935 <primary><function>XmuAddInitializer</function></primary>
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>
3947 <term><parameter>func</parameter></term>
3949 specifies the procedure to register
3953 <term><parameter>data</parameter></term>
3955 specifies private data for the procedure
3960 This function registers a procedure, to be invoked the first time
3961 <function>XmuCallInitializers</function>
3962 is called on a given application context. The procedure
3963 is called with the application context and the specified data:
3966 (*func)(app_con, data)
3970 <para id="XmuCallInitializers">
3971 <indexterm zone="XmuCallInitializers">
3972 <primary><function>XmuCallInitializers</function></primary>
3976 <funcdef>void <function>XmuCallInitializers</function></funcdef>
3977 <paramdef>XtAppContext <parameter>app_con</parameter></paramdef>
3982 <term><parameter>app_con</parameter></term>
3984 specifies the application context to initialize
3989 This function calls each of the procedures that have been registered with
3990 <function>XmuAddInitializer</function>,
3991 if this is the first time the application context has been passed to
3992 <function>XmuCallInitializers</function>.
3993 Otherwise, this function does nothing.
3998 <sect1 id='Standard_Colormap_Functions'>
3999 <title>Standard Colormap Functions</title>
4002 To use the functions defined in this section, you should include the header
4004 <<filename class='headerfile'>X11/Xmu/StdCmap.h</filename>>
4006 <primary><filename class='headerfile'>X11/Xmu/StdCmap.h</filename></primary>
4008 and link against the libXmu library.
4011 <para id="XmuAllStandardColormaps">
4012 <indexterm zone="XmuAllStandardColormaps">
4013 <primary><function>XmuAllStandardColormaps</function></primary>
4017 <funcdef>Status <function>XmuAllStandardColormaps</function></funcdef>
4018 <paramdef>Display *<parameter>dpy</parameter></paramdef>
4023 <term><parameter>dpy</parameter></term>
4025 specifies the connection to the X server
4031 <primary>colormaps</primary><secondary>standard</secondary>
4033 To create all of the appropriate standard colormaps for every visual of
4034 every screen on a given display, use
4035 <function>XmuAllStandardColormaps</function>.
4039 This function defines and retains as permanent resources all standard
4040 colormaps which are meaningful for the visuals of each screen of the
4041 display. It returns 0 on failure, non-zero on success. If the property of
4042 any standard colormap is already defined, this function will redefine it.
4046 This function is intended to be used by window managers or a special client
4047 at the start of a session.
4051 The standard colormaps of a screen are defined by properties associated with
4052 the screen's root window. The property names of standard colormaps are
4053 predefined, and each property name except
4054 <property>RGB_DEFAULT_MAP</property> may describe at
4059 The standard colormaps are: <property>RGB_BEST_MAP</property>,
4060 <property>RGB_RED_MAP</property>, <property>RGB_GREEN_MAP</property>,
4061 <property>RGB_BLUE_MAP</property>, <property>RGB_DEFAULT_MAP</property>,
4062 and <property>RGB_GRAY_MAP</property>. Therefore a screen may
4063 have at most 6 standard colormap properties defined.
4067 A standard colormap is associated with a particular visual of the screen. A
4068 screen may have multiple visuals defined, including visuals of the same
4069 class at different depths. Note that a visual id might be repeated for more
4070 than one depth, so the visual id and the depth of a visual identify the
4071 visual. The characteristics of the visual will determine which standard
4072 colormaps are meaningful under that visual, and will determine how the
4073 standard colormap is defined. Because a standard colormap is associated
4074 with a specific visual, there must be a method of determining which visuals
4075 take precedence in defining standard colormaps.
4079 The method used here is: for the visual of greatest depth, define all
4080 standard colormaps meaningful to that visual class, according to this order
4081 of (descending) precedence:
4082 <symbol>DirectColor</symbol>;
4083 <symbol>PseudoColor</symbol>;
4084 <symbol>TrueColor</symbol>
4086 <symbol>GrayScale</symbol>;
4088 <symbol>StaticColor</symbol>
4090 <symbol>StaticGray</symbol>.
4093 <para>This function allows success, on a per screen basis. For example, if a map
4094 on screen 1 fails, the maps on screen 0, created earlier, will remain.
4095 However, none on screen 1 will remain. If a map on screen 0 fails, none
4101 <link linkend="XmuVisualStandardColormaps"><function>XmuVisualStandardColormaps</function></link>
4102 for which standard colormaps are meaningful under these classes of visuals.
4105 <para id="XmuVisualStandardColormaps">
4106 <indexterm zone="XmuVisualStandardColormaps">
4107 <primary><function>XmuVisualStandardColormaps</function></primary>
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>
4122 <term><parameter>dpy</parameter></term>
4124 specifies the connection to the X server
4128 <term><parameter>screen</parameter></term>
4130 specifies the screen of the display
4134 <term><parameter>visualid</parameter></term>
4136 specifies the visual type
4140 <term><parameter>depth</parameter></term>
4142 specifies the visual depth
4146 <term><parameter>replace</parameter></term>
4148 specifies whether or not to replace
4152 <term><parameter>retain</parameter></term>
4154 specifies whether or not to retain
4159 To create all of the appropriate standard colormaps for a given visual on a
4161 <function>XmuVisualStandardColormaps</function>.
4165 This function defines all appropriate standard colormap properties for the
4166 given visual. If replace is
4167 <symbol>True</symbol>,
4168 any previous definition will be removed.
4170 <symbol>True</symbol>,
4171 new properties will be retained for the duration of the
4172 server session. This function returns 0 on failure, non-zero on success.
4173 On failure, no new properties will be defined, but old ones may have been
4174 removed if replace was <symbol>True</symbol>.
4178 Not all standard colormaps are meaningful to all visual classes. This
4179 routine will check and define the following properties for the following
4180 classes, provided that the size of the colormap is not too small. For
4181 <symbol>DirectColor</symbol>
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>.
4188 <symbol>TrueColor</symbol>
4190 <symbol>StaticColor</symbol>:
4191 <property>RGB_BEST_MAP</property>. For
4192 <symbol>GrayScale</symbol>
4194 <symbol>StaticGray</symbol>:
4195 <property>RGB_GRAY_MAP</property>.
4198 <para id="XmuLookupStandardColormap">
4199 <indexterm zone="XmuLookupStandardColormap">
4200 <primary><function>XmuLookupStandardColormap</function></primary>
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>
4216 <term><parameter>dpy</parameter></term>
4218 specifies the connection to the X server
4222 <term><parameter>screen</parameter></term>
4224 specifies the screen of the display
4228 <term><parameter>visualid</parameter></term>
4230 specifies the visual type
4234 <term><parameter>depth</parameter></term>
4236 specifies the visual depth
4240 <term><parameter>property</parameter></term>
4242 specifies the standard colormap property
4246 <term><parameter>replace</parameter></term>
4248 specifies whether or not to replace
4252 <term><parameter>retain</parameter></term>
4254 specifies whether or not to retain
4259 To create a standard colormap if one does not currently exist, or replace
4260 the currently existing standard colormap, use
4261 <function>XmuLookupStandardColormap</function>.
4265 Given a screen, a visual, and a property, this function will determine the
4266 best allocation for the property under the specified visual, and determine
4267 the whether to create a new colormap or to use the default colormap of the
4272 If replace is True, any previous definition of the property will be
4273 replaced. If retain is True, the property and the colormap will be made
4274 permanent for the duration of the server session. However, pre-existing
4275 property definitions which are not replaced cannot be made permanent by a
4276 call to this function; a request to retain resources pertains to newly
4281 This function returns 0 on failure, non-zero on success. A request to
4282 create a standard colormap upon a visual which cannot support such a map is
4283 considered a failure. An example of this would be requesting any standard
4284 colormap property on a monochrome visual, or, requesting an
4285 <property>RGB_BEST_MAP</property> on
4286 a display whose colormap size is 16.
4289 <para id="XmuGetColormapAllocation">
4290 <indexterm zone="XmuGetColormapAllocation">
4291 <primary><function>XmuGetColormapAllocation</function></primary>
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>
4305 <term><parameter>vinfo</parameter></term>
4307 specifies visual information for a chosen visual
4311 <term><parameter>property</parameter></term>
4313 specifies one of the standard colormap property names
4317 <term><parameter>red_max</parameter></term>
4319 returns maximum red value</para>
4323 <term><parameter>green_max</parameter></term>
4325 returns maximum green value
4329 <term><parameter>blue_max</parameter></term>
4331 returns maximum blue value
4336 To determine the best allocation of reds, greens, and blues in a standard
4338 <function>XmuGetColormapAllocation</function>.
4342 <function>XmuGetColormapAllocation</function>
4343 returns 0 on failure, non-zero on success. It is
4344 assumed that the visual is appropriate for the colormap property.
4347 <para id="XmuStandardColormap">
4348 <indexterm zone="XmuStandardColormap">
4349 <primary><function>XmuStandardColormap</function></primary>
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>
4367 <term><parameter>dpy</parameter></term>
4369 specifies the connection to the X server
4373 <term><parameter>screen</parameter></term>
4375 specifies the screen of the display
4379 <term><parameter>visualid</parameter></term>
4381 specifies the visual type
4385 <term><parameter>depth</parameter></term>
4387 specifies the visual depth
4391 <term><parameter>property</parameter></term>
4393 specifies the standard colormap property
4397 <term><parameter>cmap</parameter></term>
4399 specifies the colormap ID, or None
4403 <term><parameter>red_max</parameter></term>
4405 specifies the red allocation
4409 <term><parameter>green_max</parameter></term>
4411 specifies the green allocation
4415 <term><parameter>blue_max</parameter></term>
4417 specifies the blue allocation
4422 To create any one standard colormap, use
4423 <function>XmuStandardColormap</function>.
4427 This function creates a standard colormap for the given screen, visualid,
4428 and visual depth, with the given red, green, and blue maximum values, with
4429 the given standard property name. Upon success, it returns a pointer to an
4430 <function>XStandardColormap</function>
4431 structure which describes the newly created colormap.
4432 Upon failure, it returns <symbol>NULL</symbol>.
4433 If cmap is the default colormap of the screen, the standard colormap
4434 will be defined on the default colormap; otherwise a new colormap is created.
4438 Resources created by this function are not made permanent; that is the
4439 caller's responsibility.
4442 <para id="XmuCreateColormap">
4443 <indexterm zone="XmuCreateColormap">
4444 <primary><function>XmuCreateColormap</function></primary>
4448 <funcdef>Status <function>XmuCreateColormap</function></funcdef>
4449 <paramdef>Display *<parameter>dpy</parameter></paramdef>
4450 <paramdef>XStandardColormap *<parameter>colormap</parameter></paramdef>
4455 <term><parameter>dpy</parameter></term>
4457 specifies the connection under which the map is created
4461 <term><parameter>colormap</parameter></term>
4463 specifies the map to be created</para></listitem>
4467 To create any one colormap which is described by an
4468 <structname>XStandardColormap</structname>
4470 <function>XmuCreateColormap</function>.
4474 This function returns 0 on failure, and non-zero on success. The base_pixel
4475 of the colormap is set on success. Resources created by this function are
4476 not made permanent. No argument error checking is provided; use at your own
4481 All colormaps are created with read-only allocations, with the exception of
4482 read-only allocations of colors which fail
4483 to return the expected pixel value, and these are individually defined as
4484 read/write allocations. This is done so that all the cells defined in the
4485 colormap are contiguous, for use in image processing. This typically
4486 happens with White and Black in the default map.
4490 Colormaps of static visuals are considered to be successfully created if the
4491 map of the static visual matches the definition given in the standard
4495 <para id="XmuDeleteStandardColormap">
4496 <indexterm zone="XmuDeleteStandardColormap">
4497 <primary><function>XmuDeleteStandardColormap</function></primary>
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>
4509 <term><parameter>dpy</parameter></term>
4511 specifies the connection to the X server
4515 <term><parameter>screen</parameter></term>
4517 specifies the screen of the display
4521 <term><parameter>property</parameter></term>
4523 specifies the standard colormap property
4528 To remove any standard colormap property, use
4529 <function>XmuDeleteStandardColormap</function>.
4530 This function will remove the specified property from the specified screen,
4531 releasing any resources used by the colormap(s) of the property, if
4537 <sect1 id='Widget_Description_Functions'>
4538 <title>Widget Description Functions</title>
4541 The functions defined in this section are for building a description of
4542 the structure of and resources associated with a hierarchy of widget classes.
4543 This package is typically used by applications that wish to manipulate the
4548 The definitions needed to use these interfaces are in the header file
4549 <<filename class='headerfile'>X11/Xmu/WidgetNode.h</filename>>
4551 <primary><filename class='headerfile'>X11/Xmu/WidgetNode.h</filename></primary>
4553 To call these functions, you need to link against the libXmu library.
4554 The following function must be called before any of the others described
4559 <funcdef>void <function>XmuWnInitializeNodes</function></funcdef>
4560 <paramdef>XmuWidgetNode *<parameter>node_array</parameter></paramdef>
4561 <paramdef>int <parameter>num_nodes</parameter></paramdef>
4566 <term><parameter>node_array</parameter></term>
4568 specifies a list of widget classes, in alphabetical order
4572 <term><parameter>num_nodes</parameter></term>
4574 specifies the number of widget classes in the node array
4581 To determine the resources provided by a widget class or classes, use
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>
4593 <term><parameter>node</parameter></term>
4595 specifies the widget class for which resources should be obtained.
4599 <term><parameter>toplevel</parameter></term>
4601 specifies the widget that should be used for creating an instance of
4602 <parameter>node</parameter>
4603 from which resources are extracted. This is typically the value returned
4604 by <olink targetdoc='libXaw' targetptr='XtAppInitialize'><function>XtAppInitialize</function></olink>.
4608 <term><parameter>top_node</parameter></term>
4610 specifies the ancestor of <parameter>node</parameter> that should be
4612 of the widget inheritance tree (used in determining which ancestor contributed
4620 Each widget class inherits the resources of its parent. To count the number
4621 of resources contributed by a particular widget class, use:
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>
4633 <term><parameter>node</parameter></term>
4635 specifies the widget class whose resources are being examined.
4639 <term><parameter>owner_node</parameter></term>
4641 specifies the widget class of the ancestor of <parameter>node</parameter>
4647 <term><parameter>constraints</parameter></term>
4649 specifies whether or not to count constraint resources or normal resources.
4654 This routine returns the number of resources contributed (or
4655 “owned”) by
4656 the specified widget class.
4659 <para id="XmuWnNameToNode">
4660 <indexterm zone="XmuWnNameToNode">
4661 <primary><function>XmuWnNameToNode</function></primary>
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>
4673 <term><parameter>node_list</parameter></term>
4675 specifies a list of widget nodes
4679 <term><parameter>num_nodes</parameter></term>
4681 specifies the number of nodes in the list
4685 <term><parameter>name</parameter></term>
4687 specifies the name of the widget class in the node list to search for
4692 This function returns the WidgetNode in the list that matches the given
4693 widget name or widget class name. If no match is found, it returns
4694 <symbol>NULL</symbol>.
4699 <sect1 id='Participation_in_the_Editres_Protocol'>
4700 <title>Participation in the Editres Protocol</title>
4704 <primary>editres</primary>
4706 To participate in the editres protocol, applications which are not based
4707 on the Athena widget set should include the header file
4708 <<filename class='headerfile'>X11/Xmu/Editres.h</filename>>
4710 <primary><filename class='headerfile'>X11/Xmu/Editres.h</filename></primary>
4712 and link against the libXmu library.
4716 To participate in the editres protocol, Xt applications which do not rely
4717 on the Athena widget set should register the editres protocol handler on
4718 each shell widget in the application, specifying an event mask of 0,
4719 nonmaskable events, and client data as <symbol>NULL</symbol>:
4722 XtAddEventHandler(shell, (EventMask) 0, True, _XEditResCheckMessages, NULL);