diff options
Diffstat (limited to 'libX11')
55 files changed, 72829 insertions, 50157 deletions
diff --git a/libX11/configure.ac b/libX11/configure.ac index dfd93605b..d54a318d5 100644 --- a/libX11/configure.ac +++ b/libX11/configure.ac @@ -16,17 +16,20 @@ AM_MAINTAINER_MODE AM_CONFIG_HEADER([src/config.h])
AC_CONFIG_HEADER([include/X11/XlibConf.h])
-# Require xorg-macros: XORG_DEFAULT_OPTIONS
-m4_ifndef([XORG_MACROS_VERSION],
- [m4_fatal([must install xorg-macros 1.6 or later before running autoconf/autogen])])
-XORG_MACROS_VERSION(1.6)
-
# Set common system defines for POSIX extensions, such as _GNU_SOURCE
# Must be called before any macros that run the compiler (like AC_PROG_LIBTOOL)
# to avoid autoconf errors.
AC_USE_SYSTEM_EXTENSIONS
+
+# Require xorg-macros minimum of 1.10 for DocBook XML documentation
+m4_ifndef([XORG_MACROS_VERSION],
+ [m4_fatal([must install xorg-macros 1.10 or later before running autoconf/autogen])])
+XORG_MACROS_VERSION(1.10)
XORG_DEFAULT_OPTIONS
XORG_ENABLE_SPECS
+XORG_WITH_XMLTO(0.0.20)
+XORG_WITH_FOP
+XORG_CHECK_SGML_DOCTOOLS(1.5)
XORG_WITH_GROFF
XORG_WITH_PS2PDF
@@ -313,15 +316,18 @@ AC_CHECK_FUNC(poll, [AC_DEFINE(USE_POLL, 1, [poll() function is available])], ) #
# Find keysymdef.h
#
-AC_MSG_CHECKING([keysymdef.h])
-dir=`$PKG_CONFIG --variable=includedir xproto`
-KEYSYMDEF="$dir/X11/keysymdef.h"
-if test -f "$KEYSYMDEF"; then
- AC_MSG_RESULT([$KEYSYMDEF])
-else
- AC_MSG_ERROR([Cannot find keysymdef.h])
-fi
-AC_SUBST(KEYSYMDEF)
+AC_MSG_CHECKING([keysym definitions])
+KEYSYMDEFDIR=`$PKG_CONFIG --variable=includedir xproto`/X11
+FILES="keysymdef.h XF86keysym.h Sunkeysym.h DECkeysym.h HPkeysym.h"
+for i in $FILES; do
+ if test -f "$KEYSYMDEFDIR/$i"; then
+ KEYSYMDEFS="$KEYSYMDEFS $KEYSYMDEFDIR/$i"
+ elif test "x$i" = "xkeysymdef.h"; then
+ AC_MSG_ERROR([Cannot find keysymdef.h])
+ fi
+done
+AC_MSG_RESULT([$KEYSYMDEFS])
+AC_SUBST(KEYSYMDEFS)
AM_CONDITIONAL(UDC, test xfalse = xtrue)
@@ -410,7 +416,7 @@ XORG_WITH_LINT XORG_LINT_LIBRARY([X11])
X11_DATADIR="${datadir}/X11"
-AC_DEFINE_DIR(X11_DATADIR, X11_DATADIR, [Location of libX11 data])
+AX_DEFINE_DIR(X11_DATADIR, X11_DATADIR, [Location of libX11 data])
AC_SUBST(X11_DATADIR)
X11_LIBDIR="${libdir}/X11"
@@ -429,25 +435,25 @@ X11_CFLAGS="$X11_CFLAGS $XTHREAD_CFLAGS" #
X11_LOCALEDATADIR="${X11_DATADIR}/locale"
-AC_DEFINE_DIR(XLOCALEDATADIR, X11_LOCALEDATADIR, [Location of libX11 locale data])
+AX_DEFINE_DIR(XLOCALEDATADIR, X11_LOCALEDATADIR, [Location of libX11 locale data])
AC_SUBST(X11_LOCALEDATADIR)
AC_ARG_WITH(locale-lib-dir, AS_HELP_STRING([--with-locale-lib-dir=DIR],
[Directory where locale libraries files are installed (default: $libdir/X11/locale)]),
[ X11_LOCALELIBDIR="$withval" ],
[ X11_LOCALELIBDIR="${X11_LIBDIR}/locale" ])
-AC_DEFINE_DIR(XLOCALELIBDIR, X11_LOCALELIBDIR, [Location of libX11 locale libraries])
+AX_DEFINE_DIR(XLOCALELIBDIR, X11_LOCALELIBDIR, [Location of libX11 locale libraries])
AC_SUBST(X11_LOCALELIBDIR)
X11_LOCALEDIR="${X11_LOCALEDATADIR}"
-AC_DEFINE_DIR(XLOCALEDIR, X11_LOCALEDIR, [Location of libX11 locale data])
+AX_DEFINE_DIR(XLOCALEDIR, X11_LOCALEDIR, [Location of libX11 locale data])
AC_SUBST(X11_LOCALEDIR)
XKEYSYMDB="${X11_DATADIR}/XKeysymDB"
-AC_DEFINE_DIR(XKEYSYMDB, XKEYSYMDB, [Location of keysym database])
+AX_DEFINE_DIR(XKEYSYMDB, XKEYSYMDB, [Location of keysym database])
XERRORDB="${X11_DATADIR}/XErrorDB"
-AC_DEFINE_DIR(XERRORDB, XERRORDB, [Location of error message database])
+AX_DEFINE_DIR(XERRORDB, XERRORDB, [Location of error message database])
XORG_CHECK_MALLOC_ZERO
diff --git a/libX11/nls/fi_FI.UTF-8/Compose.pre b/libX11/nls/fi_FI.UTF-8/Compose.pre index 76c56650e..2a43f34dc 100644 --- a/libX11/nls/fi_FI.UTF-8/Compose.pre +++ b/libX11/nls/fi_FI.UTF-8/Compose.pre @@ -80,8 +80,8 @@ XCOMM Sequences with COMBINING CARON / <dead_caron> <dead_caron> <D> : "Ď" # LATIN CAPITAL LETTER D WITH CARON
<dead_caron> <e> : "ě" # LATIN SMALL LETTER E WITH CARON
<dead_caron> <E> : "Ě" # LATIN CAPITAL LETTER E WITH CARON
-<dead_caron> <g> : "ğ" # LATIN SMALL LETTER G WITH CARON
-<dead_caron> <G> : "Ğ" # LATIN CAPITAL LETTER G WITH CARON
+<dead_caron> <g> : "ǧ" # LATIN SMALL LETTER G WITH CARON
+<dead_caron> <G> : "Ǧ" # LATIN CAPITAL LETTER G WITH CARON
<dead_caron> <h> : "ȟ" # LATIN SMALL LETTER H WITH CARON
<dead_caron> <H> : "Ȟ" # LATIN CAPITAL LETTER H WITH CARON
<dead_caron> <i> : "ǐ" # LATIN SMALL LETTER I WITH CARON
diff --git a/libX11/specs/libX11/AppA b/libX11/specs/libX11/AppA deleted file mode 100644 index 26a1ba32f..000000000 --- a/libX11/specs/libX11/AppA +++ /dev/null @@ -1,604 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBAppendix A\fP\s-1 - -\s+1\fBXlib Functions and Protocol Requests\fP\s-1 -.sp 2 -.na -.LP -.XS -Appendix A: Xlib Functions and Protocol Requests -.XE -This appendix provides two tables that relate to Xlib functions -and the X protocol. -The following table lists each Xlib function (in alphabetical order) -and the corresponding protocol request that it generates. -.LP -.TS H -lw(2.5i) lw(2.5i). -_ -.sp 6p -.B -Xlib Function Protocol Request -.sp 6p -_ -.sp 6p -.TH -.R -XActivateScreenSaver ForceScreenSaver -XAddHost ChangeHosts -XAddHosts ChangeHosts -XAddToSaveSet ChangeSaveSet -XAllocColor AllocColor -XAllocColorCells AllocColorCells -XAllocColorPlanes AllocColorPlanes -XAllocNamedColor AllocNamedColor -XAllowEvents AllowEvents -XAutoRepeatOff ChangeKeyboardControl -XAutoRepeatOn ChangeKeyboardControl -XBell Bell -XChangeActivePointerGrab ChangeActivePointerGrab -XChangeGC ChangeGC -XChangeKeyboardControl ChangeKeyboardControl -XChangeKeyboardMapping ChangeKeyboardMapping -XChangePointerControl ChangePointerControl -XChangeProperty ChangeProperty -XChangeSaveSet ChangeSaveSet -XChangeWindowAttributes ChangeWindowAttributes -XCirculateSubwindows CirculateWindow -XCirculateSubwindowsDown CirculateWindow -XCirculateSubwindowsUp CirculateWindow -XClearArea ClearArea -XClearWindow ClearArea -XConfigureWindow ConfigureWindow -XConvertSelection ConvertSelection -XCopyArea CopyArea -XCopyColormapAndFree CopyColormapAndFree -XCopyGC CopyGC -XCopyPlane CopyPlane -XCreateBitmapFromData CreateGC - CreatePixmap - FreeGC - PutImage -XCreateColormap CreateColormap -XCreateFontCursor CreateGlyphCursor -XCreateGC CreateGC -XCreateGlyphCursor CreateGlyphCursor -XCreatePixmap CreatePixmap -XCreatePixmapCursor CreateCursor -XCreatePixmapFromData CreateGC - CreatePixmap - FreeGC - PutImage -XCreateSimpleWindow CreateWindow -XCreateWindow CreateWindow -XDefineCursor ChangeWindowAttributes -XDeleteProperty DeleteProperty -XDestroySubwindows DestroySubwindows -XDestroyWindow DestroyWindow -XDisableAccessControl SetAccessControl -XDrawArc PolyArc -XDrawArcs PolyArc -XDrawImageString ImageText8 -XDrawImageString16 ImageText16 -XDrawLine PolySegment -XDrawLines PolyLine -XDrawPoint PolyPoint -XDrawPoints PolyPoint -XDrawRectangle PolyRectangle -XDrawRectangles PolyRectangle -XDrawSegments PolySegment -XDrawString PolyText8 -XDrawString16 PolyText16 -XDrawText PolyText8 -XDrawText16 PolyText16 -XEnableAccessControl SetAccessControl -XFetchBytes GetProperty -XFetchName GetProperty -XFillArc PolyFillArc -XFillArcs PolyFillArc -XFillPolygon FillPoly -XFillRectangle PolyFillRectangle -XFillRectangles PolyFillRectangle -XForceScreenSaver ForceScreenSaver -XFreeColormap FreeColormap -XFreeColors FreeColors -XFreeCursor FreeCursor -XFreeFont CloseFont -XFreeGC FreeGC -XFreePixmap FreePixmap -XGetAtomName GetAtomName -XGetClassHint GetProperty -XGetFontPath GetFontPath -XGetGeometry GetGeometry -XGetIconName GetProperty -XGetIconSizes GetProperty -XGetImage GetImage -XGetInputFocus GetInputFocus -XGetKeyboardControl GetKeyboardControl -XGetKeyboardMapping GetKeyboardMapping -XGetModifierMapping GetModifierMapping -XGetMotionEvents GetMotionEvents -XGetNormalHints GetProperty -XGetPointerControl GetPointerControl -XGetPointerMapping GetPointerMapping -XGetRGBColormaps GetProperty -XGetScreenSaver GetScreenSaver -XGetSelectionOwner GetSelectionOwner -XGetSizeHints GetProperty -XGetTextProperty GetProperty -XGetTransientForHint GetProperty -XGetWMClientMachine GetProperty -XGetWMColormapWindows GetProperty - InternAtom -XGetWMHints GetProperty -XGetWMIconName GetProperty -XGetWMName GetProperty -XGetWMNormalHints GetProperty -XGetWMProtocols GetProperty - InternAtom -XGetWMSizeHints GetProperty -XGetWindowAttributes GetWindowAttributes - GetGeometry -XGetWindowProperty GetProperty -XGetZoomHints GetProperty -XGrabButton GrabButton -XGrabKey GrabKey -XGrabKeyboard GrabKeyboard -XGrabPointer GrabPointer -XGrabServer GrabServer -XIconifyWindow InternAtom - SendEvent -XInitExtension QueryExtension -XInstallColormap InstallColormap -XInternAtom InternAtom -XKillClient KillClient -XListExtensions ListExtensions -XListFonts ListFonts -XListFontsWithInfo ListFontsWithInfo -XListHosts ListHosts -XListInstalledColormaps ListInstalledColormaps -XListProperties ListProperties -XLoadFont OpenFont -XLoadQueryFont OpenFont - QueryFont -XLookupColor LookupColor -XLowerWindow ConfigureWindow -XMapRaised ConfigureWindow - MapWindow -XMapSubwindows MapSubwindows -XMapWindow MapWindow -XMoveResizeWindow ConfigureWindow -XMoveWindow ConfigureWindow -XNoOp NoOperation -XOpenDisplay CreateGC -XParseColor LookupColor -XPutImage PutImage -XQueryBestCursor QueryBestSize -XQueryBestSize QueryBestSize -XQueryBestStipple QueryBestSize -XQueryBestTile QueryBestSize -XQueryColor QueryColors -XQueryColors QueryColors -XQueryExtension QueryExtension -XQueryFont QueryFont -XQueryKeymap QueryKeymap -XQueryPointer QueryPointer -XQueryTextExtents QueryTextExtents -XQueryTextExtents16 QueryTextExtents -XQueryTree QueryTree -XRaiseWindow ConfigureWindow -XReadBitmapFile CreateGC - CreatePixmap - FreeGC - PutImage -XRecolorCursor RecolorCursor -XReconfigureWMWindow ConfigureWindow - SendEvent -XRemoveFromSaveSet ChangeSaveSet -XRemoveHost ChangeHosts -XRemoveHosts ChangeHosts -XReparentWindow ReparentWindow -XResetScreenSaver ForceScreenSaver -XResizeWindow ConfigureWindow -XRestackWindows ConfigureWindow -XRotateBuffers RotateProperties -XRotateWindowProperties RotateProperties -XSelectInput ChangeWindowAttributes -XSendEvent SendEvent -XSetAccessControl SetAccessControl -XSetArcMode ChangeGC -XSetBackground ChangeGC -XSetClassHint ChangeProperty -XSetClipMask ChangeGC -XSetClipOrigin ChangeGC -XSetClipRectangles SetClipRectangles -XSetCloseDownMode SetCloseDownMode -XSetCommand ChangeProperty -XSetDashes SetDashes -XSetFillRule ChangeGC -XSetFillStyle ChangeGC -XSetFont ChangeGC -XSetFontPath SetFontPath -XSetForeground ChangeGC -XSetFunction ChangeGC -XSetGraphicsExposures ChangeGC -XSetIconName ChangeProperty -XSetIconSizes ChangeProperty -XSetInputFocus SetInputFocus -XSetLineAttributes ChangeGC -XSetModifierMapping SetModifierMapping -XSetNormalHints ChangeProperty -XSetPlaneMask ChangeGC -XSetPointerMapping SetPointerMapping -XSetRGBColormaps ChangeProperty -XSetScreenSaver SetScreenSaver -XSetSelectionOwner SetSelectionOwner -XSetSizeHints ChangeProperty -XSetStandardProperties ChangeProperty -XSetState ChangeGC -XSetStipple ChangeGC -XSetSubwindowMode ChangeGC -XSetTextProperty ChangeProperty -XSetTile ChangeGC -XSetTransientForHint ChangeProperty -XSetTSOrigin ChangeGC -XSetWMClientMachine ChangeProperty -XSetWMColormapWindows ChangeProperty - InternAtom -XSetWMHints ChangeProperty -XSetWMIconName ChangeProperty -XSetWMName ChangeProperty -XSetWMNormalHints ChangeProperty -XSetWMProperties ChangeProperty -XSetWMProtocols ChangeProperty - InternAtom -XSetWMSizeHints ChangeProperty -XSetWindowBackground ChangeWindowAttributes -XSetWindowBackgroundPixmap ChangeWindowAttributes -XSetWindowBorder ChangeWindowAttributes -XSetWindowBorderPixmap ChangeWindowAttributes -XSetWindowBorderWidth ConfigureWindow -XSetWindowColormap ChangeWindowAttributes -XSetZoomHints ChangeProperty -XStoreBuffer ChangeProperty -XStoreBytes ChangeProperty -XStoreColor StoreColors -XStoreColors StoreColors -XStoreName ChangeProperty -XStoreNamedColor StoreNamedColor -XSync GetInputFocus -XSynchronize GetInputFocus -XTranslateCoordinates TranslateCoordinates -XUndefineCursor ChangeWindowAttributes -XUngrabButton UngrabButton -XUngrabKey UngrabKey -XUngrabKeyboard UngrabKeyboard -XUngrabPointer UngrabPointer -XUngrabServer UngrabServer -XUninstallColormap UninstallColormap -XUnloadFont CloseFont -XUnmapSubwindows UnmapSubwindows -XUnmapWindow UnmapWindow -XWarpPointer WarpPointer -XWithdrawWindow SendEvent - UnmapWindow -.TE -.bp -.LP -The following table lists each X protocol request (in alphabetical -order) and the Xlib functions that reference it. -.TS H -lw(2.5i) lw(2.5i). -_ -.sp 6p -.B -Protocol Request Xlib Function -.sp 6p -_ -.sp 6p -.TH -.R -AllocColor XAllocColor -AllocColorCells XAllocColorCells -AllocColorPlanes XAllocColorPlanes -AllocNamedColor XAllocNamedColor -AllowEvents XAllowEvents -Bell XBell -ChangeActivePointerGrab XChangeActivePointerGrab -ChangeGC XChangeGC - XSetArcMode - XSetBackground - XSetClipMask - XSetClipOrigin - XSetFillRule - XSetFillStyle - XSetFont - XSetForeground - XSetFunction - XSetGraphicsExposures - XSetLineAttributes - XSetPlaneMask - XSetState - XSetStipple - XSetSubwindowMode - XSetTile - XSetTSOrigin -ChangeHosts XAddHost - XAddHosts - XRemoveHost - XRemoveHosts -ChangeKeyboardControl XAutoRepeatOff - XAutoRepeatOn - XChangeKeyboardControl -ChangeKeyboardMapping XChangeKeyboardMapping -ChangePointerControl XChangePointerControl -ChangeProperty XChangeProperty - XSetClassHint - XSetCommand - XSetIconName - XSetIconSizes - XSetNormalHints - XSetRGBColormaps - XSetSizeHints - XSetStandardProperties - XSetTextProperty - XSetTransientForHint - XSetWMClientMachine - XSetWMColormapWindows - XSetWMHints - XSetWMIconName - XSetWMName - XSetWMNormalHints - XSetWMProperties - XSetWMProtocols - XSetWMSizeHints - XSetZoomHints - XStoreBuffer - XStoreBytes - XStoreName -ChangeSaveSet XAddToSaveSet - XChangeSaveSet - XRemoveFromSaveSet -ChangeWindowAttributes XChangeWindowAttributes - XDefineCursor - XSelectInput - XSetWindowBackground - XSetWindowBackgroundPixmap - XSetWindowBorder - XSetWindowBorderPixmap - XSetWindowColormap - XUndefineCursor -CirculateWindow XCirculateSubwindowsDown - XCirculateSubwindowsUp - XCirculateSubwindows -ClearArea XClearArea - XClearWindow -CloseFont XFreeFont - XUnloadFont -ConfigureWindow XConfigureWindow - XLowerWindow - XMapRaised - XMoveResizeWindow - XMoveWindow - XRaiseWindow - XReconfigureWMWindow - XResizeWindow - XRestackWindows - XSetWindowBorderWidth -ConvertSelection XConvertSelection -CopyArea XCopyArea -CopyColormapAndFree XCopyColormapAndFree -CopyGC XCopyGC -CopyPlane XCopyPlane -CreateColormap XCreateColormap -CreateCursor XCreatePixmapCursor -CreateGC XCreateGC - XCreateBitmapFromData - XCreatePixmapFromData - XOpenDisplay - XReadBitmapFile -CreateGlyphCursor XCreateFontCursor - XCreateGlyphCursor -CreatePixmap XCreatePixmap - XCreateBitmapFromData - XCreatePixmapFromData - XReadBitmapFile -CreateWindow XCreateSimpleWindow - XCreateWindow -DeleteProperty XDeleteProperty -DestroySubwindows XDestroySubwindows -DestroyWindow XDestroyWindow -FillPoly XFillPolygon -ForceScreenSaver XActivateScreenSaver - XForceScreenSaver - XResetScreenSaver -FreeColormap XFreeColormap -FreeColors XFreeColors -FreeCursor XFreeCursor -FreeGC XFreeGC - XCreateBitmapFromData - XCreatePixmapFromData - XReadBitmapFile -FreePixmap XFreePixmap -GetAtomName XGetAtomName -GetFontPath XGetFontPath -GetGeometry XGetGeometry - XGetWindowAttributes -GetImage XGetImage -GetInputFocus XGetInputFocus - XSync - XSynchronize -GetKeyboardControl XGetKeyboardControl -GetKeyboardMapping XGetKeyboardMapping -GetModifierMapping XGetModifierMapping -GetMotionEvents XGetMotionEvents -GetPointerControl XGetPointerControl -GetPointerMapping XGetPointerMapping -GetProperty XFetchBytes - XFetchName - XGetClassHint - XGetIconName - XGetIconSizes - XGetNormalHints - XGetRGBColormaps - XGetSizeHints - XGetTextProperty - XGetTransientForHint - XGetWMClientMachine - XGetWMColormapWindows - XGetWMHints - XGetWMIconName - XGetWMName - XGetWMNormalHints - XGetWMProtocols - XGetWMSizeHints - XGetWindowProperty - XGetZoomHints -GetSelectionOwner XGetSelectionOwner -GetWindowAttributes XGetWindowAttributes -GrabButton XGrabButton -GrabKey XGrabKey -GrabKeyboard XGrabKeyboard -GrabPointer XGrabPointer -GrabServer XGrabServer -ImageText8 XDrawImageString -ImageText16 XDrawImageString16 -InstallColormap XInstallColormap -InternAtom XGetWMColormapWindows - XGetWMProtocols - XIconifyWindow - XInternAtom - XSetWMColormapWindows - XSetWMProtocols -KillClient XKillClient -ListExtensions XListExtensions -ListFonts XListFonts -ListFontsWithInfo XListFontsWithInfo -ListHosts XListHosts -ListInstalledColormaps XListInstalledColormaps -ListProperties XListProperties -LookupColor XLookupColor - XParseColor -MapSubwindows XMapSubwindows -MapWindow XMapRaised - XMapWindow -NoOperation XNoOp -OpenFont XLoadFont - XLoadQueryFont -PolyArc XDrawArc - XDrawArcs -PolyFillArc XFillArc - XFillArcs -PolyFillRectangle XFillRectangle - XFillRectangles -PolyLine XDrawLines -PolyPoint XDrawPoint - XDrawPoints -PolyRectangle XDrawRectangle - XDrawRectangles -PolySegment XDrawLine - XDrawSegments -PolyText8 XDrawString - XDrawText -PolyText16 XDrawString16 - XDrawText16 -PutImage XPutImage - XCreateBitmapFromData - XCreatePixmapFromData - XReadBitmapFile -QueryBestSize XQueryBestCursor - XQueryBestSize - XQueryBestStipple - XQueryBestTile -QueryColors XQueryColor - XQueryColors -QueryExtension XInitExtension - XQueryExtension -QueryFont XLoadQueryFont - XQueryFont -QueryKeymap XQueryKeymap -QueryPointer XQueryPointer -QueryTextExtents XQueryTextExtents - XQueryTextExtents16 -QueryTree XQueryTree -RecolorCursor XRecolorCursor -ReparentWindow XReparentWindow -RotateProperties XRotateBuffers - XRotateWindowProperties -SendEvent XIconifyWindow - XReconfigureWMWindow - XSendEvent - XWithdrawWindow -SetAccessControl XDisableAccessControl - XEnableAccessControl - XSetAccessControl -SetClipRectangles XSetClipRectangles -SetCloseDownMode XSetCloseDownMode -SetDashes XSetDashes -SetFontPath XSetFontPath -SetInputFocus XSetInputFocus -SetModifierMapping XSetModifierMapping -SetPointerMapping XSetPointerMapping -SetScreenSaver XGetScreenSaver - XSetScreenSaver -SetSelectionOwner XSetSelectionOwner -StoreColors XStoreColor - XStoreColors -StoreNamedColor XStoreNamedColor -TranslateCoordinates XTranslateCoordinates -UngrabButton XUngrabButton -UngrabKey XUngrabKey -UngrabKeyboard XUngrabKeyboard -UngrabPointer XUngrabPointer -UngrabServer XUngrabServer -UninstallColormap XUninstallColormap -UnmapSubwindows XUnmapSubWindows -UnmapWindow XUnmapWindow - XWithdrawWindow -WarpPointer XWarpPointer -.TE -.bp diff --git a/libX11/specs/libX11/AppA.xml b/libX11/specs/libX11/AppA.xml new file mode 100644 index 000000000..8c71b269d --- /dev/null +++ b/libX11/specs/libX11/AppA.xml @@ -0,0 +1,540 @@ +<appendix id="xlib_functions_and_protocol_requests">
+<title>Xlib Functions and Protocol Requests</title>
+<para>
+This appendix provides two tables that relate to Xlib functions
+and the X protocol.
+The following table lists each Xlib function (in alphabetical order)
+and the corresponding protocol request that it generates.
+</para>
+<literallayout class="monospaced">
+--------------------------------------------------------------------------
+Xlib Function Protocol Request
+--------------------------------------------------------------------------
+XActivateScreenSaver ForceScreenSaver
+XAddHost ChangeHosts
+XAddHosts ChangeHosts
+XAddToSaveSet ChangeSaveSet
+XAllocColor AllocColor
+XAllocColorCells AllocColorCells
+XAllocColorPlanes AllocColorPlanes
+XAllocNamedColor AllocNamedColor
+XAllowEvents AllowEvents
+XAutoRepeatOff ChangeKeyboardControl
+XAutoRepeatOn ChangeKeyboardControl
+XBell Bell
+XChangeActivePointerGrab ChangeActivePointerGrab
+XChangeGC ChangeGC
+XChangeKeyboardControl ChangeKeyboardControl
+XChangeKeyboardMapping ChangeKeyboardMapping
+XChangePointerControl ChangePointerControl
+XChangeProperty ChangeProperty
+XChangeSaveSet ChangeSaveSet
+XChangeWindowAttributes ChangeWindowAttributes
+XCirculateSubwindows CirculateWindow
+XCirculateSubwindowsDown CirculateWindow
+XCirculateSubwindowsUp CirculateWindow
+XClearArea ClearArea
+XClearWindow ClearArea
+XConfigureWindow ConfigureWindow
+XConvertSelection ConvertSelection
+XCopyArea CopyArea
+XCopyColormapAndFree CopyColormapAndFree
+XCopyGC CopyGC
+XCopyPlane CopyPlane
+XCreateBitmapFromData CreateGC
+ CreatePixmap
+ FreeGC
+ PutImage
+XCreateColormap CreateColormap
+XCreateFontCursor CreateGlyphCursor
+XCreateGC CreateGC
+XCreateGlyphCursor CreateGlyphCursor
+XCreatePixmap CreatePixmap
+XCreatePixmapCursor CreateCursor
+XCreatePixmapFromData CreateGC
+ CreatePixmap
+ FreeGC
+ PutImage
+XCreateSimpleWindow CreateWindow
+XCreateWindow CreateWindow
+XDefineCursor ChangeWindowAttributes
+XDeleteProperty DeleteProperty
+XDestroySubwindows DestroySubwindows
+XDestroyWindow DestroyWindow
+XDisableAccessControl SetAccessControl
+XDrawArc PolyArc
+XDrawArcs PolyArc
+XDrawImageString ImageText8
+XDrawImageString16 ImageText16
+XDrawLine PolySegment
+XDrawLines PolyLine
+XDrawPoint PolyPoint
+XDrawPoints PolyPoint
+XDrawRectangle PolyRectangle
+XDrawRectangles PolyRectangle
+XDrawSegments PolySegment
+XDrawString PolyText8
+XDrawString16 PolyText16
+XDrawText PolyText8
+XDrawText16 PolyText16
+XEnableAccessControl SetAccessControl
+XFetchBytes GetProperty
+XFetchName GetProperty
+XFillArc PolyFillArc
+XFillArcs PolyFillArc
+XFillPolygon FillPoly
+XFillRectangle PolyFillRectangle
+XFillRectangles PolyFillRectangle
+XForceScreenSaver ForceScreenSaver
+XFreeColormap FreeColormap
+XFreeColors FreeColors
+XFreeCursor FreeCursor
+XFreeFont CloseFont
+XFreeGC FreeGC
+XFreePixmap FreePixmap
+XGetAtomName GetAtomName
+XGetClassHint GetProperty
+XGetFontPath GetFontPath
+XGetGeometry GetGeometry
+XGetIconName GetProperty
+XGetIconSizes GetProperty
+XGetImage GetImage
+XGetInputFocus GetInputFocus
+XGetKeyboardControl GetKeyboardControl
+XGetKeyboardMapping GetKeyboardMapping
+XGetModifierMapping GetModifierMapping
+XGetMotionEvents GetMotionEvents
+XGetNormalHints GetProperty
+XGetPointerControl GetPointerControl
+XGetPointerMapping GetPointerMapping
+XGetRGBColormaps GetProperty
+XGetScreenSaver GetScreenSaver
+XGetSelectionOwner GetSelectionOwner
+XGetSizeHints GetProperty
+XGetTextProperty GetProperty
+XGetTransientForHint GetProperty
+XGetWMClientMachine GetProperty
+XGetWMColormapWindows GetProperty
+ InternAtom
+XGetWMHints GetProperty
+XGetWMIconName GetProperty
+XGetWMName GetProperty
+XGetWMNormalHints GetProperty
+XGetWMProtocols GetProperty
+ InternAtom
+XGetWMSizeHints GetProperty
+XGetWindowAttributes GetWindowAttributes
+ GetGeometry
+XGetWindowProperty GetProperty
+XGetZoomHints GetProperty
+XGrabButton GrabButton
+XGrabKey GrabKey
+XGrabKeyboard GrabKeyboard
+XGrabPointer GrabPointer
+XGrabServer GrabServer
+XIconifyWindow InternAtom
+ SendEvent
+XInitExtension QueryExtension
+XInstallColormap InstallColormap
+XInternAtom InternAtom
+XKillClient KillClient
+XListExtensions ListExtensions
+XListFonts ListFonts
+XListFontsWithInfo ListFontsWithInfo
+XListHosts ListHosts
+XListInstalledColormaps ListInstalledColormaps
+XListProperties ListProperties
+XLoadFont OpenFont
+XLoadQueryFont OpenFont
+ QueryFont
+XLookupColor LookupColor
+XLowerWindow ConfigureWindow
+XMapRaised ConfigureWindow
+ MapWindow
+XMapSubwindows MapSubwindows
+XMapWindow MapWindow
+XMoveResizeWindow ConfigureWindow
+XMoveWindow ConfigureWindow
+XNoOp NoOperation
+XOpenDisplay CreateGC
+XParseColor LookupColor
+XPutImage PutImage
+XQueryBestCursor QueryBestSize
+XQueryBestSize QueryBestSize
+XQueryBestStipple QueryBestSize
+XQueryBestTile QueryBestSize
+XQueryColor QueryColors
+XQueryColors QueryColors
+XQueryExtension QueryExtension
+XQueryFont QueryFont
+XQueryKeymap QueryKeymap
+XQueryPointer QueryPointer
+XQueryTextExtents QueryTextExtents
+XQueryTextExtents16 QueryTextExtents
+XQueryTree QueryTree
+XRaiseWindow ConfigureWindow
+XReadBitmapFile CreateGC
+ CreatePixmap
+ FreeGC
+ PutImage
+XRecolorCursor RecolorCursor
+XReconfigureWMWindow ConfigureWindow
+ SendEvent
+XRemoveFromSaveSet ChangeSaveSet
+XRemoveHost ChangeHosts
+XRemoveHosts ChangeHosts
+XReparentWindow ReparentWindow
+XResetScreenSaver ForceScreenSaver
+XResizeWindow ConfigureWindow
+XRestackWindows ConfigureWindow
+XRotateBuffers RotateProperties
+XRotateWindowProperties RotateProperties
+XSelectInput ChangeWindowAttributes
+XSendEvent SendEvent
+XSetAccessControl SetAccessControl
+XSetArcMode ChangeGC
+XSetBackground ChangeGC
+XSetClassHint ChangeProperty
+XSetClipMask ChangeGC
+XSetClipOrigin ChangeGC
+XSetClipRectangles SetClipRectangles
+XSetCloseDownMode SetCloseDownMode
+XSetCommand ChangeProperty
+XSetDashes SetDashes
+XSetFillRule ChangeGC
+XSetFillStyle ChangeGC
+XSetFont ChangeGC
+XSetFontPath SetFontPath
+XSetForeground ChangeGC
+XSetFunction ChangeGC
+XSetGraphicsExposures ChangeGC
+XSetIconName ChangeProperty
+XSetIconSizes ChangeProperty
+XSetInputFocus SetInputFocus
+XSetLineAttributes ChangeGC
+XSetModifierMapping SetModifierMapping
+XSetNormalHints ChangeProperty
+XSetPlaneMask ChangeGC
+XSetPointerMapping SetPointerMapping
+XSetRGBColormaps ChangeProperty
+XSetScreenSaver SetScreenSaver
+XSetSelectionOwner SetSelectionOwner
+XSetSizeHints ChangeProperty
+XSetStandardProperties ChangeProperty
+XSetState ChangeGC
+XSetStipple ChangeGC
+XSetSubwindowMode ChangeGC
+XSetTextProperty ChangeProperty
+XSetTile ChangeGC
+XSetTransientForHint ChangeProperty
+XSetTSOrigin ChangeGC
+XSetWMClientMachine ChangeProperty
+XSetWMColormapWindows ChangeProperty
+ InternAtom
+XSetWMHints ChangeProperty
+XSetWMIconName ChangeProperty
+XSetWMName ChangeProperty
+XSetWMNormalHints ChangeProperty
+XSetWMProperties ChangeProperty
+XSetWMProtocols ChangeProperty
+ InternAtom
+XSetWMSizeHints ChangeProperty
+XSetWindowBackground ChangeWindowAttributes
+XSetWindowBackgroundPixmap ChangeWindowAttributes
+XSetWindowBorder ChangeWindowAttributes
+XSetWindowBorderPixmap ChangeWindowAttributes
+XSetWindowBorderWidth ConfigureWindow
+XSetWindowColormap ChangeWindowAttributes
+XSetZoomHints ChangeProperty
+XStoreBuffer ChangeProperty
+XStoreBytes ChangeProperty
+XStoreColor StoreColors
+XStoreColors StoreColors
+XStoreName ChangeProperty
+XStoreNamedColor StoreNamedColor
+XSync GetInputFocus
+XSynchronize GetInputFocus
+XTranslateCoordinates TranslateCoordinates
+XUndefineCursor ChangeWindowAttributes
+XUngrabButton UngrabButton
+XUngrabKey UngrabKey
+XUngrabKeyboard UngrabKeyboard
+XUngrabPointer UngrabPointer
+XUngrabServer UngrabServer
+XUninstallColormap UninstallColormap
+XUnloadFont CloseFont
+XUnmapSubwindows UnmapSubwindows
+XUnmapWindow UnmapWindow
+XWarpPointer WarpPointer
+XWithdrawWindow SendEvent
+ UnmapWindow
+</literallayout>
+<para>
+The following table lists each X protocol request (in alphabetical
+order) and the Xlib functions that reference it.
+</para>
+<literallayout class="monospaced">
+--------------------------------------------------------------------------
+Protocol Request Xlib Function
+--------------------------------------------------------------------------
+AllocColor XAllocColor
+AllocColorCells XAllocColorCells
+AllocColorPlanes XAllocColorPlanes
+AllocNamedColor XAllocNamedColor
+AllowEvents XAllowEvents
+Bell XBell
+ChangeActivePointerGrab XChangeActivePointerGrab
+ChangeGC XChangeGC
+ XSetArcMode
+ XSetBackground
+ XSetClipMask
+ XSetClipOrigin
+ XSetFillRule
+ XSetFillStyle
+ XSetFont
+ XSetForeground
+ XSetFunction
+ XSetGraphicsExposures
+ XSetLineAttributes
+ XSetPlaneMask
+ XSetState
+ XSetStipple
+ XSetSubwindowMode
+ XSetTile
+ XSetTSOrigin
+ChangeHosts XAddHost
+ XAddHosts
+ XRemoveHost
+ XRemoveHosts
+ChangeKeyboardControl XAutoRepeatOff
+ XAutoRepeatOn
+ XChangeKeyboardControl
+ChangeKeyboardMapping XChangeKeyboardMapping
+ChangePointerControl XChangePointerControl
+ChangeProperty XChangeProperty
+ XSetClassHint
+ XSetCommand
+ XSetIconName
+ XSetIconSizes
+ XSetNormalHints
+ XSetRGBColormaps
+ XSetSizeHints
+ XSetStandardProperties
+ XSetTextProperty
+ XSetTransientForHint
+ XSetWMClientMachine
+ XSetWMColormapWindows
+ XSetWMHints
+ XSetWMIconName
+ XSetWMName
+ XSetWMNormalHints
+ XSetWMProperties
+ XSetWMProtocols
+ XSetWMSizeHints
+ XSetZoomHints
+ XStoreBuffer
+ XStoreBytes
+ XStoreName
+ChangeSaveSet XAddToSaveSet
+ XChangeSaveSet
+ XRemoveFromSaveSet
+ChangeWindowAttributes XChangeWindowAttributes
+ XDefineCursor
+ XSelectInput
+ XSetWindowBackground
+ XSetWindowBackgroundPixmap
+ XSetWindowBorder
+ XSetWindowBorderPixmap
+ XSetWindowColormap
+ XUndefineCursor
+CirculateWindow XCirculateSubwindowsDown
+ XCirculateSubwindowsUp
+ XCirculateSubwindows
+ClearArea XClearArea
+ XClearWindow
+CloseFont XFreeFont
+ XUnloadFont
+ConfigureWindow XConfigureWindow
+ XLowerWindow
+ XMapRaised
+ XMoveResizeWindow
+ XMoveWindow
+ XRaiseWindow
+ XReconfigureWMWindow
+ XResizeWindow
+ XRestackWindows
+ XSetWindowBorderWidth
+ConvertSelection XConvertSelection
+CopyArea XCopyArea
+CopyColormapAndFree XCopyColormapAndFree
+CopyGC XCopyGC
+CopyPlane XCopyPlane
+CreateColormap XCreateColormap
+CreateCursor XCreatePixmapCursor
+CreateGC XCreateGC
+ XCreateBitmapFromData
+ XCreatePixmapFromData
+ XOpenDisplay
+ XReadBitmapFile
+CreateGlyphCursor XCreateFontCursor
+ XCreateGlyphCursor
+CreatePixmap XCreatePixmap
+ XCreateBitmapFromData
+ XCreatePixmapFromData
+ XReadBitmapFile
+CreateWindow XCreateSimpleWindow
+ XCreateWindow
+DeleteProperty XDeleteProperty
+DestroySubwindows XDestroySubwindows
+DestroyWindow XDestroyWindow
+FillPoly XFillPolygon
+ForceScreenSaver XActivateScreenSaver
+ XForceScreenSaver
+ XResetScreenSaver
+FreeColormap XFreeColormap
+FreeColors XFreeColors
+FreeCursor XFreeCursor
+FreeGC XFreeGC
+ XCreateBitmapFromData
+ XCreatePixmapFromData
+ XReadBitmapFile
+FreePixmap XFreePixmap
+GetAtomName XGetAtomName
+GetFontPath XGetFontPath
+GetGeometry XGetGeometry
+ XGetWindowAttributes
+GetImage XGetImage
+GetInputFocus XGetInputFocus
+ XSync
+ XSynchronize
+GetKeyboardControl XGetKeyboardControl
+GetKeyboardMapping XGetKeyboardMapping
+GetModifierMapping XGetModifierMapping
+GetMotionEvents XGetMotionEvents
+GetPointerControl XGetPointerControl
+GetPointerMapping XGetPointerMapping
+GetProperty XFetchBytes
+ XFetchName
+ XGetClassHint
+ XGetIconName
+ XGetIconSizes
+ XGetNormalHints
+ XGetRGBColormaps
+ XGetSizeHints
+ XGetTextProperty
+ XGetTransientForHint
+ XGetWMClientMachine
+ XGetWMColormapWindows
+ XGetWMHints
+ XGetWMIconName
+ XGetWMName
+ XGetWMNormalHints
+ XGetWMProtocols
+ XGetWMSizeHints
+ XGetWindowProperty
+ XGetZoomHints
+GetSelectionOwner XGetSelectionOwner
+GetWindowAttributes XGetWindowAttributes
+GrabButton XGrabButton
+GrabKey XGrabKey
+GrabKeyboard XGrabKeyboard
+GrabPointer XGrabPointer
+GrabServer XGrabServer
+ImageText8 XDrawImageString
+ImageText16 XDrawImageString16
+InstallColormap XInstallColormap
+InternAtom XGetWMColormapWindows
+ XGetWMProtocols
+ XIconifyWindow
+ XInternAtom
+ XSetWMColormapWindows
+ XSetWMProtocols
+KillClient XKillClient
+ListExtensions XListExtensions
+ListFonts XListFonts
+ListFontsWithInfo XListFontsWithInfo
+ListHosts XListHosts
+ListInstalledColormaps XListInstalledColormaps
+ListProperties XListProperties
+LookupColor XLookupColor
+ XParseColor
+MapSubwindows XMapSubwindows
+MapWindow XMapRaised
+ XMapWindow
+NoOperation XNoOp
+OpenFont XLoadFont
+ XLoadQueryFont
+PolyArc XDrawArc
+ XDrawArcs
+PolyFillArc XFillArc
+ XFillArcs
+PolyFillRectangle XFillRectangle
+ XFillRectangles
+PolyLine XDrawLines
+PolyPoint XDrawPoint
+ XDrawPoints
+PolyRectangle XDrawRectangle
+ XDrawRectangles
+PolySegment XDrawLine
+ XDrawSegments
+PolyText8 XDrawString
+ XDrawText
+PolyText16 XDrawString16
+ XDrawText16
+PutImage XPutImage
+ XCreateBitmapFromData
+ XCreatePixmapFromData
+ XReadBitmapFile
+QueryBestSize XQueryBestCursor
+ XQueryBestSize
+ XQueryBestStipple
+ XQueryBestTile
+QueryColors XQueryColor
+ XQueryColors
+QueryExtension XInitExtension
+ XQueryExtension
+QueryFont XLoadQueryFont
+ XQueryFont
+QueryKeymap XQueryKeymap
+QueryPointer XQueryPointer
+QueryTextExtents XQueryTextExtents
+ XQueryTextExtents16
+QueryTree XQueryTree
+RecolorCursor XRecolorCursor
+ReparentWindow XReparentWindow
+RotateProperties XRotateBuffers
+ XRotateWindowProperties
+SendEvent XIconifyWindow
+ XReconfigureWMWindow
+ XSendEvent
+ XWithdrawWindow
+SetAccessControl XDisableAccessControl
+ XEnableAccessControl
+ XSetAccessControl
+SetClipRectangles XSetClipRectangles
+SetCloseDownMode XSetCloseDownMode
+SetDashes XSetDashes
+SetFontPath XSetFontPath
+SetInputFocus XSetInputFocus
+SetModifierMapping XSetModifierMapping
+SetPointerMapping XSetPointerMapping
+SetScreenSaver XGetScreenSaver
+ XSetScreenSaver
+SetSelectionOwner XSetSelectionOwner
+StoreColors XStoreColor
+ XStoreColors
+StoreNamedColor XStoreNamedColor
+TranslateCoordinates XTranslateCoordinates
+UngrabButton XUngrabButton
+UngrabKey XUngrabKey
+UngrabKeyboard XUngrabKeyboard
+UngrabPointer XUngrabPointer
+UngrabServer XUngrabServer
+UninstallColormap XUninstallColormap
+UnmapSubwindows XUnmapSubWindows
+UnmapWindow XUnmapWindow
+ XWithdrawWindow
+WarpPointer XWarpPointer
+
+</literallayout>
+</appendix>
diff --git a/libX11/specs/libX11/AppB b/libX11/specs/libX11/AppB deleted file mode 100644 index 2e57ede86..000000000 --- a/libX11/specs/libX11/AppB +++ /dev/null @@ -1,101 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBAppendix B\fP\s-1 - -\s+1\fBX Font Cursors\fP\s-1 -.sp 2 -.na -.LP -.XS -Appendix B: X Font Cursors -.XE -The following are the available cursors that can be used with -.PN XCreateFontCursor . -.LP -.Ds 0 -.TA 3i -.ta 3i -#define XC_X_cursor 0 #define XC_ll_angle 76 -#define XC_arrow 2 #define XC_lr_angle 78 -#define XC_based_arrow_down 4 #define XC_man 80 -#define XC_based_arrow_up 6 #define XC_middlebutton 82 -#define XC_boat 8 #define XC_mouse 84 -#define XC_bogosity 10 #define XC_pencil 86 -#define XC_bottom_left_corner 12 #define XC_pirate 88 -#define XC_bottom_right_corner 14 #define XC_plus 90 -#define XC_bottom_side 16 #define XC_question_arrow 92 -#define XC_bottom_tee 18 #define XC_right_ptr 94 -#define XC_box_spiral 20 #define XC_right_side 96 -#define XC_center_ptr 22 #define XC_right_tee 98 -#define XC_circle 24 #define XC_rightbutton 100 -#define XC_clock 26 #define XC_rtl_logo 102 -#define XC_coffee_mug 28 #define XC_sailboat 104 -#define XC_cross 30 #define XC_sb_down_arrow 106 -#define XC_cross_reverse 32 #define XC_sb_h_double_arrow 108 -#define XC_crosshair 34 #define XC_sb_left_arrow 110 -#define XC_diamond_cross 36 #define XC_sb_right_arrow 112 -#define XC_dot 38 #define XC_sb_up_arrow 114 -#define XC_dot_box_mask 40 #define XC_sb_v_double_arrow 116 -#define XC_double_arrow 42 #define XC_shuttle 118 -#define XC_draft_large 44 #define XC_sizing 120 -#define XC_draft_small 46 #define XC_spider 122 -#define XC_draped_box 48 #define XC_spraycan 124 -#define XC_exchange 50 #define XC_star 126 -#define XC_fleur 52 #define XC_target 128 -#define XC_gobbler 54 #define XC_tcross 130 -#define XC_gumby 56 #define XC_top_left_arrow 132 -#define XC_hand1 58 #define XC_top_left_corner 134 -#define XC_hand2 60 #define XC_top_right_corner 136 -#define XC_heart 62 #define XC_top_side 138 -#define XC_icon 64 #define XC_top_tee 140 -#define XC_iron_cross 66 #define XC_trek 142 -#define XC_left_ptr 68 #define XC_ul_angle 144 -#define XC_left_side 70 #define XC_umbrella 146 -#define XC_left_tee 72 #define XC_ur_angle 148 -#define XC_leftbutton 74 #define XC_watch 150 - #define XC_xterm 152 -.De -.bp diff --git a/libX11/specs/libX11/AppB.xml b/libX11/specs/libX11/AppB.xml new file mode 100644 index 000000000..8d9886aac --- /dev/null +++ b/libX11/specs/libX11/AppB.xml @@ -0,0 +1,49 @@ +<appendix id="x_font_cursors">
+<title>X Font Cursors</title>
+<para>
+The following are the available cursors that can be used with
+<function>XCreateFontCursor</function>.
+</para>
+<literallayout class="monospaced">
+#define XC_X_cursor 0 #define XC_ll_angle 76
+#define XC_arrow 2 #define XC_lr_angle 78
+#define XC_based_arrow_down 4 #define XC_man 80
+#define XC_based_arrow_up 6 #define XC_middlebutton 82
+#define XC_boat 8 #define XC_mouse 84
+#define XC_bogosity 10 #define XC_pencil 86
+#define XC_bottom_left_corner 12 #define XC_pirate 88
+#define XC_bottom_right_corner 14 #define XC_plus 90
+#define XC_bottom_side 16 #define XC_question_arrow 92
+#define XC_bottom_tee 18 #define XC_right_ptr 94
+#define XC_box_spiral 20 #define XC_right_side 96
+#define XC_center_ptr 22 #define XC_right_tee 98
+#define XC_circle 24 #define XC_rightbutton 100
+#define XC_clock 26 #define XC_rtl_logo 102
+#define XC_coffee_mug 28 #define XC_sailboat 104
+#define XC_cross 30 #define XC_sb_down_arrow 106
+#define XC_cross_reverse 32 #define XC_sb_h_double_arrow 108
+#define XC_crosshair 34 #define XC_sb_left_arrow 110
+#define XC_diamond_cross 36 #define XC_sb_right_arrow 112
+#define XC_dot 38 #define XC_sb_up_arrow 114
+#define XC_dot_box_mask 40 #define XC_sb_v_double_arrow 116
+#define XC_double_arrow 42 #define XC_shuttle 118
+#define XC_draft_large 44 #define XC_sizing 120
+#define XC_draft_small 46 #define XC_spider 122
+#define XC_draped_box 48 #define XC_spraycan 124
+#define XC_exchange 50 #define XC_star 126
+#define XC_fleur 52 #define XC_target 128
+#define XC_gobbler 54 #define XC_tcross 130
+#define XC_gumby 56 #define XC_top_left_arrow 132
+#define XC_hand1 58 #define XC_top_left_corner 134
+#define XC_hand2 60 #define XC_top_right_corner 136
+#define XC_heart 62 #define XC_top_side 138
+#define XC_icon 64 #define XC_top_tee 140
+#define XC_iron_cross 66 #define XC_trek 142
+#define XC_left_ptr 68 #define XC_ul_angle 144
+#define XC_left_side 70 #define XC_umbrella 146
+#define XC_left_tee 72 #define XC_ur_angle 148
+#define XC_leftbutton 74 #define XC_watch 150
+ #define XC_xterm 152
+</literallayout>
+</appendix>
+
diff --git a/libX11/specs/libX11/AppC b/libX11/specs/libX11/AppC deleted file mode 100644 index 43261ba83..000000000 --- a/libX11/specs/libX11/AppC +++ /dev/null @@ -1,2230 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBAppendix C\fP\s-1 - -\s+1\fBExtensions\fP\s-1 -.sp 2 -.na -.LP -.XS -Appendix C: Extensions -.XE -Because X can evolve by extensions to the core protocol, -it is important that extensions not be perceived as second-class citizens. -At some point, -your favorite extensions may be adopted as additional parts of the -X Standard. -.LP -Therefore, there should be little to distinguish the use of an extension from -that of the core protocol. -To avoid having to initialize extensions explicitly in application programs, -it is also important that extensions perform lazy evaluations, -automatically initializing themselves when called for the first time. -.LP -This appendix describes techniques for writing extensions to Xlib that will -run at essentially the same performance as the core protocol requests. -.NT -It is expected that a given extension to X consists of multiple -requests. -Defining 10 new features as 10 separate extensions is a bad practice. -Rather, they should be packaged into a single extension -and should use minor opcodes to distinguish the requests. -.NE -.LP -The symbols and macros used for writing stubs to Xlib are listed in -.hN X11/Xlibint.h . -.SH -Basic Protocol Support Routines -.LP -The basic protocol requests for extensions are -.PN XQueryExtension -and -.PN XListExtensions . -.IN "XQueryExtension" "" "@DEF@" -.sM -.FD 0 -Bool XQueryExtension(\^\fIdisplay\fP, \fIname\fP, \fImajor_opcode_return\fP, \ -\fIfirst_event_return\fP, \fIfirst_error_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIname;\fP\^ -.br - int *\fImajor_opcode_return\fP\^; -.br - int *\fIfirst_event_return\fP\^; -.br - int *\fIfirst_error_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIname\fP 1i -Specifies the extension name. -.IP \fImajor_opcode_return\fP 1i -Returns the major opcode. -.IP \fIfirst_event_return\fP 1i -Returns the first event code, if any. -.IP \fIfirst_error_return\fP 1i -Returns the first error code, if any. -.LP -.eM -The -.PN XQueryExtension -function determines if the named extension is present. -If the extension is not present, -.PN XQueryExtension -returns -.PN False ; -otherwise, it returns -.PN True . -If the extension is present, -.PN XQueryExtension -returns the major opcode for the extension to major_opcode_return; -otherwise, -it returns zero. -Any minor opcode and the request formats are specific to the -extension. -If the extension involves additional event types, -.PN XQueryExtension -returns the base event type code to first_event_return; -otherwise, -it returns zero. -The format of the events is specific to the extension. -If the extension involves additional error codes, -.PN XQueryExtension -returns the base error code to first_error_return; -otherwise, -it returns zero. -The format of additional data in the errors is specific to the extension. -.LP -If the extension name is not in the Host Portable Character Encoding -the result is implementation-dependent. -Uppercase and lowercase matter; -the strings ``thing'', ``Thing'', and ``thinG'' -are all considered different names. -.IN "XListExtensions" "" "@DEF@" -.sM -.FD 0 -char **XListExtensions(\^\fIdisplay\fP, \fInextensions_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInextensions_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInextensions_return\fP 1i -Returns the number of extensions listed. -.LP -.eM -The -.PN XListExtensions -function returns a list of all extensions supported by the server. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned strings are in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -.IN "XFreeExtensionList" "" "@DEF@" -.sM -.FD 0 -XFreeExtensionList(\^\fIlist\fP\^) -.br - char **\fIlist\fP\^; -.FN -.IP \fIlist\fP 1i -Specifies the list of extension names. -.LP -.eM -The -.PN XFreeExtensionList -function frees the memory allocated by -.PN XListExtensions . -.SH -Hooking into Xlib -.LP -These functions allow you to hook into the library. -They are not normally used by application programmers but are used -by people who need to extend the core X protocol and -the X library interface. -The functions, which generate protocol requests for X, are typically -called stubs. -.LP -In extensions, stubs first should check to see if they have initialized -themselves on a connection. -If they have not, they then should call -.PN XInitExtension -to attempt to initialize themselves on the connection. -.LP -If the extension needs to be informed of GC/font allocation or -deallocation or if the extension defines new event types, -the functions described here allow the extension to be -called when these events occur. -.LP -The -.PN XExtCodes -structure returns the information from -.PN XInitExtension -and is defined in -.hN X11/Xlib.h : -.LP -.IN "XExtCodes" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct _XExtCodes { /* public to extension, cannot be changed */ - int extension; /* extension number */ - int major_opcode; /* major op-code assigned by server */ - int first_event; /* first event number for the extension */ - int first_error; /* first error number for the extension */ -} XExtCodes; -.De -.LP -.eM -.IN "XInitExtension" "" "@DEF@" -.sM -.FD 0 -XExtCodes *XInitExtension(\^\fIdisplay\fP, \fIname\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIname\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIname\fP 1i -Specifies the extension name. -.LP -.eM -The -.PN XInitExtension -function determines if the named extension exists. -Then, it allocates storage for maintaining the -information about the extension on the connection, -chains this onto the extension list for the connection, -and returns the information the stub implementor will need to access -the extension. -If the extension does not exist, -.PN XInitExtension -returns NULL. -.LP -If the extension name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Uppercase and lowercase matter; -the strings ``thing'', ``Thing'', and ``thinG'' -are all considered different names. -.LP -The extension number in the -.PN XExtCodes -structure is -needed in the other calls that follow. -This extension number is unique only to a single connection. -.LP -.IN "XAddExtension" "" "@DEF@" -.sM -.FD 0 -XExtCodes *XAddExtension\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -For local Xlib extensions, the -.PN XAddExtension -function allocates the -.PN XExtCodes -structure, bumps the extension number count, -and chains the extension onto the extension list. -(This permits extensions to Xlib without requiring server extensions.) -.SH -Hooks into the Library -.LP -These functions allow you to define procedures that are to be -called when various circumstances occur. -The procedures include the creation of a new GC for a connection, -the copying of a GC, the freeing of a GC, the creating and freeing of fonts, -the conversion of events defined by extensions to and from wire -format, and the handling of errors. -.LP -All of these functions return the previous procedure defined for this -extension. -.IN "XESetCloseDisplay" "" "@DEF@" -.sM -.FD 0 -int (*XESetCloseDisplay(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when the display is closed. -.LP -.eM -The -.PN XESetCloseDisplay -function defines a procedure to be called whenever -.PN XCloseDisplay -is called. -It returns any previously defined procedure, usually NULL. -.LP -When -.PN XCloseDisplay -is called, -your procedure is called -with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP\^) - Display *\fIdisplay\fP\^; - XExtCodes *\fIcodes\fP\^; -.De -.LP -.eM -.IN "XESetCreateGC" "" "@DEF@" -.sM -.FD 0 -int (*XESetCreateGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when a GC is closed. -.LP -.eM -The -.PN XESetCreateGC -function defines a procedure to be called whenever -a new GC is created. -It returns any previously defined procedure, usually NULL. -.LP -When a GC is created, -your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) - Display *\fIdisplay\fP\^; - GC \fIgc\fP\^; - XExtCodes *\fIcodes\fP\^; -.De -.LP -.eM -.IN "XESetCopyGC" "" "@DEF@" -.sM -.FD 0 -int (*XESetCopyGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when GC components are copied. -.LP -.eM -The -.PN XESetCopyGC -function defines a procedure to be called whenever -a GC is copied. -It returns any previously defined procedure, usually NULL. -.LP -When a GC is copied, -your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) - Display *\fIdisplay\fP\^; - GC \fIgc\fP\^; - XExtCodes *\fIcodes\fP\^; -.De -.LP -.eM -.IN "XESetFreeGC" "" "@DEF@" -.sM -.FD 0 -int (*XESetFreeGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc)\fP\^)(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when a GC is freed. -.LP -.eM -The -.PN XESetFreeGC -function defines a procedure to be called whenever -a GC is freed. -It returns any previously defined procedure, usually NULL. -.LP -When a GC is freed, -your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) - Display *\fIdisplay\fP\^; - GC \fIgc\fP\^; - XExtCodes *\fIcodes\fP\^; -.De -.LP -.eM -.IN "XESetCreateFont" "" "@DEF@" -.sM -.FD 0 -int (*XESetCreateFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when a font is created. -.LP -.eM -The -.PN XESetCreateFont -function defines a procedure to be called whenever -.PN XLoadQueryFont -and -.PN XQueryFont -are called. -It returns any previously defined procedure, usually NULL. -.LP -When -.PN XLoadQueryFont -or -.PN XQueryFont -is called, -your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^) - Display *\fIdisplay\fP\^; - XFontStruct *\fIfs\fP\^; - XExtCodes *\fIcodes\fP\^; -.De -.LP -.eM -.IN "XESetFreeFont" "" "@DEF@" -.sM -.FD 0 -int (*XESetFreeFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when a font is freed. -.LP -.eM -The -.PN XESetFreeFont -function defines a procedure to be called whenever -.PN XFreeFont -is called. -It returns any previously defined procedure, usually NULL. -.LP -When -.PN XFreeFont -is called, your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^) - Display *\fIdisplay\fP\^; - XFontStruct *\fIfs\fP\^; - XExtCodes *\fIcodes\fP\^; -.De -.LP -.eM -The -.PN XESetWireToEvent -and -.PN XESetEventToWire -functions allow you to define new events to the library. -An -.PN XEvent -structure always has a type code (type -.PN int ) -as the first component. -This uniquely identifies what kind of event it is. -The second component is always the serial number (type -.PN unsigned -.PN long ) -of the last request processed by the server. -The third component is always a Boolean (type -.PN Bool ) -indicating whether the event came from a -.PN SendEvent -protocol request. -The fourth component is always a pointer to the display -the event was read from. -The fifth component is always a resource ID of one kind or another, -usually a window, carefully selected to be useful to toolkit dispatchers. -The fifth component should always exist, even if -the event does not have a natural destination; -if there is no value -from the protocol to put in this component, initialize it to zero. -.NT -There is an implementation limit such that your host event -structure size cannot be bigger than the size of the -.PN XEvent -union of structures. -There also is no way to guarantee that more than 24 elements or 96 characters -in the structure will be fully portable between machines. -.NE -.IN "XESetWireToEvent" "" "@DEF@" -.sM -.FD 0 -int (*XESetWireToEvent(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIevent_number\fP\^; -.br - Status (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_number\fP 1i -Specifies the event code. -.IP \fIproc\fP 1i -Specifies the procedure to call when converting an event. -.LP -.eM -The -.PN XESetWireToEvent -function defines a procedure to be called when an event -needs to be converted from wire format -.Pn ( xEvent ) -to host format -.Pn ( XEvent ). -The event number defines which protocol event number to install a -conversion procedure for. -.PN XESetWireToEvent -returns any previously defined procedure. -.NT -You can replace a core event conversion function with one -of your own, although this is not encouraged. -It would, however, allow you to intercept a core event -and modify it before being placed in the queue or otherwise examined. -.NE -When Xlib needs to convert an event from wire format to host -format, your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -Status (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^) - Display *\fIdisplay\fP\^; - XEvent *\fIre\fP\^; - xEvent *\fIevent\fP\^; -.De -.LP -.eM -Your procedure must return status to indicate if the conversion succeeded. -The re argument is a pointer to where the host format event should be stored, -and the event argument is the 32-byte wire event structure. -In the -.PN XEvent -structure you are creating, -you must fill in the five required members of the event structure. -You should fill in the type member with the type specified for the -.PN xEvent -structure. -You should copy all other members from the -.PN xEvent -structure (wire format) to the -.PN XEvent -structure (host format). -Your conversion procedure should return -.PN True -if the event should be placed in the queue or -.PN False -if it should not be placed in the queue. -.LP -To initialize the serial number component of the event, call -.PN _XSetLastRequestRead -with the event and use the return value. -.LP -.IN "_XSetLastRequestRead" "" "@DEF@" -.sM -.FD 0 -unsigned long _XSetLastRequestRead(\^\fIdisplay\fP, \fIrep\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - xGenericReply *\fIrep\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIrep\fP 1i -Specifies the wire event structure. -.LP -.eM -The -.PN _XSetLastRequestRead -function computes and returns a complete serial number from the partial -serial number in the event. -.sp -.LP -.IN "XESetEventToWire" "" "@DEF@" -.sM -.FD 0 -Status (*XESetEventToWire(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIevent_number\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_number\fP 1i -Specifies the event code. -.IP \fIproc\fP 1i -Specifies the procedure to call when converting an event. -.LP -.eM -The -.PN XESetEventToWire -function defines a procedure to be called when an event -needs to be converted from host format -.Pn ( XEvent ) -to wire format -.Pn ( xEvent ) -form. -The event number defines which protocol event number to install a -conversion procedure for. -.PN XESetEventToWire -returns any previously defined procedure. -It returns zero if the conversion fails or nonzero otherwise. -.NT -You can replace a core event conversion function with one -of your own, although this is not encouraged. -It would, however, allow you to intercept a core event -and modify it before being sent to another client. -.NE -When Xlib needs to convert an event from host format to wire format, -your procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^) - Display *\fIdisplay\fP\^; - XEvent *\fIre\fP\^; - xEvent *\fIevent\fP\^; -.De -.LP -.eM -The re argument is a pointer to the host format event, -and the event argument is a pointer to where the 32-byte wire event -structure should be stored. -You should fill in the type with the type from the -.PN XEvent -structure. -All other members then should be copied from the host format to the -.PN xEvent -structure. -.IN "XESetWireToError" "" "@DEF@" -.sM -.FD 0 -Bool (*XESetWireToError(\^\fIdisplay\fP, \fIerror_number\fP, \fIproc\fP\^)(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIerror_number\fP\^; -.br - Bool (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIerror_number\fP 1i -Specifies the error code. -.IP \fIproc\fP 1i -Specifies the procedure to call when an error is received. -.LP -.eM -The -.PN XESetWireToError -function defines a procedure to be called when an extension -error needs to be converted from wire format to host format. -The error number defines which protocol error code to install -the conversion procedure for. -.PN XESetWireToError -returns any previously defined procedure. -.LP -Use this function for extension errors that contain additional error values -beyond those in a core X error, when multiple wire errors must be combined -into a single Xlib error, or when it is necessary to intercept an -X error before it is otherwise examined. -.LP -When Xlib needs to convert an error from wire format to host format, -the procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -Bool (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIhe\fP, \fIwe\fP\^) - Display *\fIdisplay\fP\^; - XErrorEvent *\fIhe\fP\^; - xError *\fIwe\fP\^; -.De -.LP -.eM -The he argument is a pointer to where the host format error should be stored. -The structure pointed at by he is guaranteed to be as large as an -.PN XEvent -structure and so can be cast to a type larger than an -.PN XErrorEvent -to store additional values. -If the error is to be completely ignored by Xlib -(for example, several protocol error structures will be combined into -one Xlib error), -then the function should return -.PN False ; -otherwise, it should return -.PN True . -.IN "XESetError" "" "@DEF@" -.sM -.FD 0 -int (*XESetError(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when an error is received. -.LP -.eM -Inside Xlib, there are times that you may want to suppress the -calling of the external error handling when an error occurs. -This allows status to be returned on a call at the cost of the call -being synchronous (though most such functions are query operations, in any -case, and are typically programmed to be synchronous). -.LP -When Xlib detects a protocol error in -.PN _XReply , -it calls your procedure with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -int (*\fIproc\fP\^)(\fIdisplay\fP, \fIerr\fP, \fIcodes\fP, \fIret_code\fP\^) - Display *\fIdisplay\fP\^; - xError *\fIerr\fP\^; - XExtCodes *\fIcodes\fP\^; - int *\fIret_code\fP\^; -.De -.LP -.eM -The err argument is a pointer to the 32-byte wire format error. -The codes argument is a pointer to the extension codes structure. -The ret_code argument is the return code you may want -.PN _XReply -returned to. -.LP -If your procedure returns a zero value, -the error is not suppressed, and -the client's error handler is called. -(For further information, see section 11.8.2.) -If your procedure returns nonzero, -the error is suppressed, and -.PN _XReply -returns the value of ret_code. -.IN "XESetErrorString" "" "@DEF@" -.sM -.FD 0 -char *(*XESetErrorString(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - char *(\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call to obtain an error string. -.LP -.eM -The -.PN XGetErrorText -function returns a string to the user for an error. -.PN XESetErrorString -allows you to define a procedure to be called that -should return a pointer to the error message. -The following is an example. -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcode\fP, \fIcodes\fP, \fIbuffer\fP, \fInbytes\fP\^) - Display *\fIdisplay\fP\^; - int \fIcode\fP\^; - XExtCodes *\fIcodes\fP\^; - char *\fIbuffer\fP\^; - int \fInbytes\fP\^; -.De -.LP -.eM -Your procedure is called with the error code for every error detected. -You should copy nbytes of a null-terminated string containing the -error message into buffer. -.IN "XESetPrintErrorValues" "" "@DEF@" -.sM -.FD 0 -void (*XESetPrintErrorValues(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - void (\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when an error is printed. -.LP -.eM -The -.PN XESetPrintErrorValues -function defines a procedure to be called when an extension -error is printed, to print the error values. -Use this function for extension errors that contain additional error values -beyond those in a core X error. -It returns any previously defined procedure. -.LP -When Xlib needs to print an error, -the procedure is called with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIev\fP, \fIfp\fP\^) - Display *\fIdisplay\fP\^; - XErrorEvent *\fIev\fP\^; - void *\fIfp\fP\^; -.De -.LP -.eM -The structure pointed at by ev is guaranteed to be as large as an -.PN XEvent -structure and so can be cast to a type larger than an -.PN XErrorEvent -to obtain additional values set by using -.PN XESetWireToError . -The underlying type of the fp argument is system dependent; -on a POSIX-compliant system, fp should be cast to type FILE*. -.IN "XESetFlushGC" "" "@DEF@" -.sM -.FD 0 -int (*XESetFlushGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int *(\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when a GC is flushed. -.LP -.eM -The procedure set by the -.PN XESetFlushGC -function has the same interface as the procedure set by the -.PN XESetCopyGC -function, but is called when a GC cache needs to be updated in the server. -.IN "XESetBeforeFlush" "" "@DEF@" -.sM -.FD 0 -int (*XESetBeforeFlush(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIextension\fP\^; -.br - int *(\^*\fIproc\fP\^)(\^); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIextension\fP 1i -Specifies the extension number. -.IP \fIproc\fP 1i -Specifies the procedure to call when a buffer is flushed. -.LP -.eM -The -.PN XESetBeforeFlush -function defines a procedure to be called when data is about to be -sent to the server. When data is about to be sent, your procedure is -called one or more times with these arguments: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -.R -void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP, \fIdata\fP, \fIlen\fP\^) - Display *\fIdisplay\fP\^; - XExtCodes *\fIcodes\fP\^; - char *\fIdata\fP\^; - long \fIlen\fP\^; -.De -.LP -.eM -The data argument specifies a portion of the outgoing data buffer, -and its length in bytes is specified by the len argument. -Your procedure must not alter the contents of the data and must not -do additional protocol requests to the same display. -.SH -Hooks onto Xlib Data Structures -.LP -Various Xlib data structures have provisions for extension procedures -to chain extension supplied data onto a list. -These structures are -.PN GC , -.PN Visual , -.PN Screen , -.PN ScreenFormat , -.PN Display , -and -.PN XFontStruct . -Because the list pointer is always the first member in the structure, -a single set of procedures can be used to manipulate the data -on these lists. -.LP -The following structure is used in the functions in this section -and is defined in -.hN X11/Xlib.h : -.LP -.IN "XExtData" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct _XExtData { - int number; /* number returned by XInitExtension */ - struct _XExtData *next; /* next item on list of data for structure */ - int (*free_private)(); /* if defined, called to free private */ - XPointer private_data; /* data private to this extension. */ -} XExtData; -.De -.LP -.eM -When any of the data structures listed above are freed, -the list is walked, and the structure's free procedure (if any) is called. -If free is NULL, -then the library frees both the data pointed to by the private_data member -and the structure itself. -.LP -.sM -.Ds 0 -.TA .5i -.ta .5i -union { Display *display; - GC gc; - Visual *visual; - Screen *screen; - ScreenFormat *pixmap_format; - XFontStruct *font } XEDataObject; -.De -.LP -.eM -.IN "XEHeadOfExtensionList" "" "@DEF@" -.sM -.FD 0 -XExtData **XEHeadOfExtensionList(\^\fIobject\fP\^) - XEDataObject \fIobject\fP\^; -.FN -.IP \fIobject\fP 1i -Specifies the object. -.LP -.eM -The -.PN XEHeadOfExtensionList -function returns a pointer to the list of extension structures attached -to the specified object. -In concert with -.PN XAddToExtensionList , -.PN XEHeadOfExtensionList -allows an extension to attach arbitrary data to any of the structures -of types contained in -.PN XEDataObject . -.LP -.IN "XAddToExtensionList" "" "@DEF@" -.sM -.FD 0 -XAddToExtensionList(\^\fIstructure\fP, \fIext_data\fP\^) -.br - XExtData **\fIstructure\fP\^; -.br - XExtData *\fIext_data\fP\^; -.FN -.IP \fIstructure\fP 1i -Specifies the extension list. -.IP \fIext_data\fP 1i -Specifies the extension data structure to add. -.LP -.eM -The structure argument is a pointer to one of the data structures -enumerated above. -You must initialize ext_data->number with the extension number -before calling this function. -.IN "XFindOnExtensionList" "" "@DEF@" -.sM -.FD 0 -XExtData *XFindOnExtensionList(\^\fIstructure\fP, \fInumber\fP\^) -.br - struct _XExtData **\fIstructure\fP\^; -.br - int \fInumber\fP\^; -.FN -.IP \fIstructure\fP 1i -Specifies the extension list. -.IP \fInumber\fP 1i -Specifies the extension number from -.PN XInitExtension . -.LP -.eM -The -.PN XFindOnExtensionList -function returns the first extension data structure -for the extension numbered number. -It is expected that an extension will add at most one extension -data structure to any single data structure's extension data list. -There is no way to find additional structures. -.LP -The -.PN XAllocID -macro, which allocates and returns a resource ID, is defined in -.hN X11/Xlib.h . -.IN "XAllocID" "" "@DEF@" -.sM -.FD 0 -XAllocID\^(\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -This macro is a call through the -.PN Display -structure to an internal resource ID allocator. -It returns a resource ID that you can use when creating new resources. -.LP -The -.PN XAllocIDs -macro allocates and returns an array of resource ID. -.IN "XAllocIDs" "" "@DEF@" -.sM -.FD 0 -XAllocIDs\^(\fIdisplay\fP, \fIids_return\fP, \fIcount\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID *\fIids_return\fP\^; -.br - int \fIcount\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIids_return\fP 1i -Returns the resource IDs. -.IP \fIrep\fP 1i -Specifies the number of resource IDs requested. -.LP -.eM -This macro is a call through the -.PN Display -structure to an internal resource ID allocator. -It returns resource IDs to the array supplied by the caller. -To correctly handle automatic reuse of resource IDs, you must call -.PN XAllocIDs -when requesting multiple resource IDs. This call might generate -protocol requests. -.SH -GC Caching -.LP -GCs are cached by the library to allow merging of independent change -requests to the same GC into single protocol requests. -This is typically called a write-back cache. -Any extension procedure whose behavior depends on the contents of a GC -must flush the GC cache to make sure the server has up-to-date contents -in its GC. -.LP -The -.PN FlushGC -macro checks the dirty bits in the library's GC structure and calls -.PN _XFlushGCCache -if any elements have changed. -The -.PN FlushGC -macro is defined as follows: -.IN "FlushGC" "" "@DEF@" -.sM -.FD 0 -FlushGC\^(\^\fIdisplay\fP\^, \fIgc\fP\^) -.br - Display *\^\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.LP -.eM -Note that if you extend the GC to add additional resource ID components, -you should ensure that the library stub sends the change request immediately. -This is because a client can free a resource immediately after -using it, so if you only stored the value in the cache without -forcing a protocol request, the resource might be destroyed before being -set into the GC. -You can use the -.PN _XFlushGCCache -procedure -to force the cache to be flushed. -The -.PN _XFlushGCCache -procedure -is defined as follows: -.IN "_XFlushGCCache" "" "@DEF@" -.sM -.FD 0 -_XFlushGCCache\^(\^\fIdisplay\fP\^, \fIgc\fP\^) -.br - Display *\^\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.LP -.eM -.SH -Graphics Batching -.LP -If you extend X to add more poly graphics primitives, you may be able to -take advantage of facilities in the library to allow back-to-back -single calls to be transformed into poly requests. -This may dramatically improve performance of programs that are not -written using poly requests. -A pointer to an -.PN xReq , -called last_req in the display structure, is the last request being processed. -By checking that the last request -type, drawable, gc, and other options are the same as the new one -and that there is enough space left in the buffer, you may be able -to just extend the previous graphics request by extending the length -field of the request and appending the data to the buffer. -This can improve performance by five times or more in naive programs. -For example, here is the source for the -.PN XDrawPoint -stub. -(Writing extension stubs is discussed in the next section.) -.IP -.sM -.nf - -#include <X11/Xlibint.h> - -/* precompute the maximum size of batching request allowed */ - -static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint); - -XDrawPoint(dpy, d, gc, x, y) - register Display *dpy; - Drawable d; - GC gc; - int x, y; /* INT16 */ -{ - xPoint *point; - LockDisplay(dpy); - FlushGC(dpy, gc); - { - register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req; - /* if same as previous request, with same drawable, batch requests */ - if ( - (req->reqType == X_PolyPoint) - && (req->drawable == d) - && (req->gc == gc->gid) - && (req->coordMode == CoordModeOrigin) - && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax) - && (((char *)dpy->bufptr - (char *)req) < size) ) { - point = (xPoint *) dpy->bufptr; - req->length += sizeof (xPoint) >> 2; - dpy->bufptr += sizeof (xPoint); - } - - else { - GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */ - req->drawable = d; - req->gc = gc->gid; - req->coordMode = CoordModeOrigin; - point = (xPoint *) (req + 1); - } - point->x = x; - point->y = y; - } - UnlockDisplay(dpy); - SyncHandle(); -} -.fi -.LP -.eM -To keep clients from generating very long requests that may monopolize the -server, -there is a symbol defined in -.hN X11/Xlibint.h -of EPERBATCH on the number of requests batched. -Most of the performance benefit occurs in the first few merged requests. -Note that -.PN FlushGC -is called \fIbefore\fP picking up the value of last_req, -because it may modify this field. -.SH -Writing Extension Stubs -.LP -All X requests always contain the length of the request, -expressed as a 16-bit quantity of 32 bits. -This means that a single request can be no more than 256K bytes in -length. -Some servers may not support single requests of such a length. -The value of dpy->max_request_size contains the maximum length as -defined by the server implementation. -For further information, -see ``X Window System Protocol.'' -.SH -Requests, Replies, and Xproto.h -.LP -The -.hN X11/Xproto.h -file contains three sets of definitions that -are of interest to the stub implementor: -request names, request structures, and reply structures. -.LP -You need to generate a file equivalent to -.hN X11/Xproto.h -for your extension and need to include it in your stub procedure. -Each stub procedure also must include -.hN X11/Xlibint.h . -.LP -The identifiers are deliberately chosen in such a way that, if the -request is called X_DoSomething, then its request structure is -xDoSomethingReq, and its reply is xDoSomethingReply. -The GetReq family of macros, defined in -.hN X11/Xlibint.h , -takes advantage of this naming scheme. -.LP -For each X request, -there is a definition in -.hN X11/Xproto.h -that looks similar to this: -.LP -.Ds -.R -#define X_DoSomething 42 -.De -In your extension header file, -this will be a minor opcode, -instead of a major opcode. -.SH -Request Format -.LP -Every request contains an 8-bit major opcode and a 16-bit length field -expressed in units of 4 bytes. -Every request consists of 4 bytes of header -(containing the major opcode, the length field, and a data byte) followed by -zero or more additional bytes of data. -The length field defines the total length of the request, including the header. -The length field in a request must equal the minimum length required to contain -the request. -If the specified length is smaller or larger than the required length, -the server should generate a -.PN BadLength -error. -Unused bytes in a request are not required to be zero. -Extensions should be designed in such a way that long protocol requests -can be split up into smaller requests, -if it is possible to exceed the maximum request size of the server. -The protocol guarantees the maximum request size to be no smaller than -4096 units (16384 bytes). -.LP -Major opcodes 128 through 255 are reserved for extensions. -Extensions are intended to contain multiple requests, -so extension requests typically have an additional minor opcode encoded -in the second data byte in the request header, -but the placement and interpretation of this minor opcode as well as all -other fields in extension requests are not defined by the core protocol. -Every request is implicitly assigned a sequence number (starting with one) -used in replies, errors, and events. -.LP -To help but not cure portability problems to certain machines, the -.PN B16 -and -.PN B32 -macros have been defined so that they can become bitfield specifications -on some machines. -For example, on a Cray, -these should be used for all 16-bit and 32-bit quantities, as discussed below. -.LP -Most protocol requests have a corresponding structure typedef in -.hN X11/Xproto.h , -which looks like: -.LP -.IN "xDoSomethingReq" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct _DoSomethingReq { - CARD8 reqType; /* X_DoSomething */ - CARD8 someDatum; /* used differently in different requests */ - CARD16 length B16; /* total # of bytes in request, divided by 4 */ - ... - /* request-specific data */ - ... -} xDoSomethingReq; -.De -.LP -.eM -If a core protocol request has a single 32-bit argument, -you need not declare a request structure in your extension header file. -Instead, such requests use the -.PN xResourceReq -structure in -.hN X11/Xproto.h . -This structure is used for any request whose single argument is a -.PN Window , -.PN Pixmap , -.PN Drawable , -.PN GContext , -.PN Font , -.PN Cursor , -.PN Colormap , -.PN Atom , -or -.PN VisualID . -.LP -.IN "xResourceReq" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct _ResourceReq { - CARD8 reqType; /* the request type, e.g. X_DoSomething */ - BYTE pad; /* not used */ - CARD16 length B16; /* 2 (= total # of bytes in request, divided by 4) */ - CARD32 id B32; /* the Window, Drawable, Font, GContext, etc. */ -} xResourceReq; -.De -.LP -.eM -If convenient, -you can do something similar in your extension header file. -.LP -In both of these structures, -the reqType field identifies the type of the request (for example, -X_MapWindow or X_CreatePixmap). -The length field tells how long the request is -in units of 4-byte longwords. -This length includes both the request structure itself and any -variable-length data, such as strings or lists, that follow the -request structure. -Request structures come in different sizes, -but all requests are padded to be multiples of four bytes long. -.LP -A few protocol requests take no arguments at all. -Instead, they use the -.PN xReq -structure in -.hN X11/Xproto.h , -which contains only a reqType and a length (and a pad byte). -.LP -If the protocol request requires a reply, -then -.hN X11/Xproto.h -also contains a reply structure typedef: -.LP -.IN "xDoSomethingReply" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct _DoSomethingReply { - BYTE type; /* always X_Reply */ - BYTE someDatum; /* used differently in different requests */ - CARD16 sequenceNumber B16; /* # of requests sent so far */ - CARD32 length B32; /* # of additional bytes, divided by 4 */ - ... - /* request-specific data */ - ... -} xDoSomethingReply; -.De -.LP -.eM -Most of these reply structures are 32 bytes long. -If there are not that many reply values, -then they contain a sufficient number of pad fields -to bring them up to 32 bytes. -The length field is the total number of bytes in the request minus 32, -divided by 4. -This length will be nonzero only if: -.IP \(bu 5 -The reply structure is followed by variable-length data, -such as a list or string. -.IP \(bu 5 -The reply structure is longer than 32 bytes. -.LP -Only -.PN GetWindowAttributes , -.PN QueryFont , -.PN QueryKeymap , -and -.PN GetKeyboardControl -have reply structures longer than 32 bytes in the core protocol. -.LP -A few protocol requests return replies that contain no data. -.hN X11/Xproto.h -does not define reply structures for these. -Instead, they use the -.PN xGenericReply -structure, which contains only a type, length, -and sequence number (and sufficient padding to make it 32 bytes long). -.SH -Starting to Write a Stub Procedure -.LP -An Xlib stub procedure should start like this: -.LP -.Ds -.R -#include "<X11/Xlibint.h> - -XDoSomething (arguments, ... ) -/* argument declarations */ -{ - -register XDoSomethingReq *req; -\^... -.De -If the protocol request has a reply, -then the variable declarations should include the reply structure for the request. -The following is an example: -.LP -.Ds -.R -xDoSomethingReply rep; -.De -.SH -Locking Data Structures -.LP -To lock the display structure for systems that -want to support multithreaded access to a single display connection, -each stub will need to lock its critical section. -Generally, this section is the point from just before the appropriate GetReq -call until all arguments to the call have been stored into the buffer. -The precise instructions needed for this locking depend upon the machine -architecture. -Two calls, which are generally implemented as macros, have been provided. -.IN "LockDisplay" "" "@DEF@" -.sM -.FD 0 -LockDisplay(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.LP -.IN "UnlockDisplay" "" "@DEF@" -.FD 0 -UnlockDisplay(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.SH -Sending the Protocol Request and Arguments -.LP -After the variable declarations, -a stub procedure should call one of four macros defined in -.hN X11/Xlibint.h : -.PN GetReq , -.PN GetReqExtra , -.PN GetResReq , -or -.PN GetEmptyReq . -All of these macros take, as their first argument, -the name of the protocol request as declared in -.hN X11/Xproto.h -except with X_ removed. -Each one declares a -.PN Display -structure pointer, -called dpy, and a pointer to a request structure, called req, -which is of the appropriate type. -The macro then appends the request structure to the output buffer, -fills in its type and length field, and sets req to point to it. -.LP -If the protocol request has no arguments (for instance, X_GrabServer), -then use -.PN GetEmptyReq . -.LP -.Ds -.R -GetEmptyReq (DoSomething, req); -.De -If the protocol request has a single 32-bit argument (such as a -.PN Pixmap , -.PN Window , -.PN Drawable , -.PN Atom , -and so on), -then use -.PN GetResReq . -The second argument to the macro is the 32-bit object. -.PN X_MapWindow -is a good example. -.LP -.Ds -.R -GetResReq (DoSomething, rid, req); -.De -The rid argument is the -.PN Pixmap , -.PN Window , -or other resource ID. -.LP -If the protocol request takes any other argument list, -then call -.PN GetReq . -After the -.PN GetReq , -you need to set all the other fields in the request structure, -usually from arguments to the stub procedure. -.LP -.Ds -.R -GetReq (DoSomething, req); -/* fill in arguments here */ -req->arg1 = arg1; -req->arg2 = arg2; -\^... -.De -A few stub procedures (such as -.PN XCreateGC -and -.PN XCreatePixmap ) -return a resource ID to the caller but pass a resource ID as an argument -to the protocol request. -Such procedures use the macro -.PN XAllocID -to allocate a resource ID from the range of IDs -that were assigned to this client when it opened the connection. -.LP -.Ds -.R -rid = req->rid = XAllocID(); -\^... -return (rid); -.De -Finally, some stub procedures transmit a fixed amount of variable-length -data after the request. -Typically, these procedures (such as -.PN XMoveWindow -and -.PN XSetBackground ) -are special cases of more general functions like -.PN XMoveResizeWindow -and -.PN XChangeGC . -These procedures use -.PN GetReqExtra , -which is the same as -.PN GetReq -except that it takes an additional argument (the number of -extra bytes to allocate in the output buffer after the request structure). -This number should always be a multiple of four. -.SH -Variable Length Arguments -.LP -Some protocol requests take additional variable-length data that -follow the -.PN xDoSomethingReq -structure. -The format of this data varies from request to request. -Some requests require a sequence of 8-bit bytes, -others a sequence of 16-bit or 32-bit entities, -and still others a sequence of structures. -.LP -It is necessary to add the length of any variable-length data to the -length field of the request structure. -That length field is in units of 32-bit longwords. -If the data is a string or other sequence of 8-bit bytes, -then you must round the length up and shift it before adding: -.LP -.Ds -.R -req->length += (nbytes+3)>>2; -.De -To transmit variable-length data, use the -.PN Data -macros. -If the data fits into the output buffer, -then this macro copies it to the buffer. -If it does not fit, however, -the -.PN Data -macro calls -.PN _XSend , -which transmits first the contents of the buffer and then your data. -The -.PN Data -macros take three arguments: -the display, a pointer to the beginning of the data, -and the number of bytes to be sent. -.sM -.FD 0 -Data(\^\fIdisplay\fP, (char *) \fIdata\fP, \fInbytes\fP\^); -.sp -Data16(\^\fIdisplay\fP, (short *) \fIdata\fP, \fInbytes\fP\^); -.sp -Data32(\^\fIdisplay\fP, (long *) \fIdata\fP, \fInbytes\fP\^); -.FN -.LP -.eM -.PN Data , -.PN Data16 , -and -.PN Data32 -are macros that may use their last argument -more than once, so that argument should be a variable rather than -an expression such as ``nitems*sizeof(item)''. -You should do that kind of computation in a separate statement before calling -them. -Use the appropriate macro when sending byte, short, or long data. -.LP -If the protocol request requires a reply, -then call the procedure -.PN _XSend -instead of the -.PN Data -macro. -.PN _XSend -takes the same arguments, but because it sends your data immediately instead of -copying it into the output buffer (which would later be flushed -anyway by the following call on -.PN _XReply ), -it is faster. -.SH -Replies -.LP -If the protocol request has a reply, -then call -.PN _XReply -after you have finished dealing with -all the fixed-length and variable-length arguments. -.PN _XReply -flushes the output buffer and waits for an -.PN xReply -packet to arrive. -If any events arrive in the meantime, -.PN _XReply -places them in the queue for later use. -.IN "_XReply" "" "@DEF@" -.sM -.FD 0 -Status _XReply(\^\fIdisplay\fP, \fIrep\fP, \fIextra\fP, \fIdiscard\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - xReply *\fIrep\fP\^; -.br - int \fIextra\fP\^; -.br - Bool \fIdiscard\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIrep\fP 1i -Specifies the reply structure. -.IP \fIextra\fP 1i -Specifies the number of 32-bit words expected after the replay. -.IP \fIdiscard\fP 1i -Specifies if any data beyond that specified in the extra argument -should be discarded. -.LP -.eM -The -.PN _XReply -function waits for a reply packet and copies its contents into the -specified rep. -.PN _XReply -handles error and event packets that occur before the reply is received. -.PN _XReply -takes four arguments: -.IP \(bu 5 -A -.PN Display -* structure -.IP \(bu 5 -A pointer to a reply structure (which must be cast to an -.PN xReply -*) -.IP \(bu 5 -The number of additional 32-bit words (beyond -.Pn sizeof( xReply ) -= 32 bytes) -in the reply structure -.IP \(bu 5 -A Boolean that indicates whether -.PN _XReply -is to discard any additional bytes -beyond those it was told to read -.LP -Because most reply structures are 32 bytes long, -the third argument is usually 0. -The only core protocol exceptions are the replies to -.PN GetWindowAttributes , -.PN QueryFont , -.PN QueryKeymap , -and -.PN GetKeyboardControl , -which have longer replies. -.LP -The last argument should be -.PN False -if the reply structure is followed -by additional variable-length data (such as a list or string). -It should be -.PN True -if there is not any variable-length data. -.NT -This last argument is provided for upward-compatibility reasons -to allow a client to communicate properly with a hypothetical later -version of the server that sends more data than the client expected. -For example, some later version of -.PN GetWindowAttributes -might use a -larger, but compatible, -.PN xGetWindowAttributesReply -that contains additional attribute data at the end. -.NE -.PN _XReply -returns -.PN True -if it received a reply successfully or -.PN False -if it received any sort of error. -.LP -For a request with a reply that is not followed by variable-length -data, you write something like: -.LP -.Ds -.R -_XReply(display, (xReply *)&rep, 0, True); -*ret1 = rep.ret1; -*ret2 = rep.ret2; -*ret3 = rep.ret3; -\^... -UnlockDisplay(dpy); -SyncHandle(); -return (rep.ret4); -} -.De -If there is variable-length data after the reply, -change the -.PN True -to -.PN False , -and use the appropriate -.PN _XRead -function to read the variable-length data. -.LP -.sM -.FD 0 -_XRead(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) - Display *\fIdisplay\fP\^; - char *\fIdata_return\fP\^; - long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdata_return\fP 1i -Specifies the buffer. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -The -.PN _XRead -function reads the specified number of bytes into data_return. -.LP -.sM -.FD 0 -_XRead16(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) - Display *\fIdisplay\fP\^; - short *\fIdata_return\fP\^; - long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdata_return\fP 1i -Specifies the buffer. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -The -.PN _XRead16 -function reads the specified number of bytes, -unpacking them as 16-bit quantities, -into the specified array as shorts. -.LP -.sM -.FD 0 -_XRead32(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) - Display *\fIdisplay\fP\^; - long *\fIdata_return\fP\^; - long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdata_return\fP 1i -Specifies the buffer. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -The -.PN _XRead32 -function reads the specified number of bytes, -unpacking them as 32-bit quantities, -into the specified array as longs. -.LP -.sM -.FD 0 -_XRead16Pad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) - Display *\fIdisplay\fP\^; - short *\fIdata_return\fP\^; - long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdata_return\fP 1i -Specifies the buffer. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -The -.PN _XRead16Pad -function reads the specified number of bytes, -unpacking them as 16-bit quantities, -into the specified array as shorts. -If the number of bytes is not a multiple of four, -.PN _XRead16Pad -reads and discards up to two additional pad bytes. -.LP -.sM -.FD 0 -_XReadPad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) - Display *\fIdisplay\fP\^; - char *\fIdata_return\fP\^; - long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdata_return\fP 1i -Specifies the buffer. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -The -.PN _XReadPad -function reads the specified number of bytes into data_return. -If the number of bytes is not a multiple of four, -.PN _XReadPad -reads and discards up to three additional pad bytes. -.LP -Each protocol request is a little different. -For further information, -see the Xlib sources for examples. -.SH -Synchronous Calling -.LP -Each procedure should have a call, just before returning to the user, -to a macro called -.PN SyncHandle . -If synchronous mode is enabled (see -.PN XSynchronize ), -the request is sent immediately. -The library, however, waits until any error the procedure could generate -at the server has been handled. -.SH -Allocating and Deallocating Memory -.LP -To support the possible reentry of these procedures, -you must observe several conventions when allocating and deallocating memory, -most often done when returning data to the user from the window -system of a size the caller could not know in advance -(for example, a list of fonts or a list of extensions). -The standard C library functions on many systems -are not protected against signals or other multithreaded uses. -The following analogies to standard I/O library functions -have been defined: -.TS -l l. -T{ -.PN Xmalloc () -T} T{ -Replaces -.PN malloc () -T} -T{ -.PN XFree () -T} T{ -Replaces -.PN free () -T} -T{ -.PN Xcalloc () -T} T{ -Replaces -.PN calloc () -T} -.TE -.LP -These should be used in place of any calls you would make to the normal -C library functions. -.LP -If you need a single scratch buffer inside a critical section -(for example, to pack and unpack data to and from the wire protocol), -the general memory allocators may be too expensive to use -(particularly in output functions, which are performance critical). -The following function returns a scratch buffer for use within a -critical section: -.IN "_XAllocScratch" "" "@DEF@" -.sM -.FD 0 -char *_XAllocScratch(\^\fIdisplay\fP, \fInbytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -This storage must only be used inside of a critical section of your -stub. The returned pointer cannot be assumed valid after any call -that might permit another thread to execute inside Xlib. For example, -the pointer cannot be assumed valid after any use of the -.PN GetReq -or -.PN Data -families of macros, -after any use of -.PN _XReply , -or after any use of the -.PN _XSend -or -.PN _XRead -families of functions. -.LP -.sp -The following function returns a scratch buffer for use across -critical sections: -.IN "_XAllocTemp" "" "@DEF@" -.sM -.FD 0 -char *_XAllocTemp(\^\fIdisplay\fP, \fInbytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInbytes\fP 1i -Specifies the number of bytes required. -.LP -.eM -This storage can be used across calls that might permit another thread to -execute inside Xlib. The storage must be explicitly returned to Xlib. -The following function returns the storage: -.IN "_XFreeTemp" "" "@DEF@" -.sM -.FD 0 -void _XFreeTemp(\^\fIdisplay\fP, \fIbuf\fP, \fInbytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIbuf\fP\^; -.br - unsigned long \fInbytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIbuf\fP 1i -Specifies the buffer to return. -.IP \fInbytes\fP 1i -Specifies the size of the buffer. -.LP -.eM -You must pass back the same pointer and size that were returned by -.PN _XAllocTemp . -.SH -Portability Considerations -.LP -Many machine architectures, -including many of the more recent RISC architectures, -do not correctly access data at unaligned locations; -their compilers pad out structures to preserve this characteristic. -Many other machines capable of unaligned references pad inside of structures -as well to preserve alignment, because accessing aligned data is -usually much faster. -Because the library and the server use structures to access data at -arbitrary points in a byte stream, -all data in request and reply packets \fImust\fP be naturally aligned; -that is, 16-bit data starts on 16-bit boundaries in the request -and 32-bit data on 32-bit boundaries. -All requests \fImust\fP be a multiple of 32 bits in length to preserve -the natural alignment in the data stream. -You must pad structures out to 32-bit boundaries. -Pad information does not have to be zeroed unless you want to -preserve such fields for future use in your protocol requests. -Floating point varies radically between machines and should be -avoided completely if at all possible. -.LP -This code may run on machines with 16-bit ints. -So, if any integer argument, variable, or return value either can take -only nonnegative values or is declared as a -.PN CARD16 -in the protocol, be sure to declare it as -.PN unsigned -.PN int -and not as -.PN int . -(This, of course, does not apply to Booleans or enumerations.) -.LP -Similarly, -if any integer argument or return value is declared -.PN CARD32 -in the protocol, -declare it as an -.PN unsigned -.PN long -and not as -.PN int -or -.PN long . -This also goes for any internal variables that may -take on values larger than the maximum 16-bit -.PN unsigned -.PN int . -.LP -The library currently assumes that a -.PN char -is 8 bits, a -.PN short -is 16 bits, an -.PN int -is 16 or 32 bits, and a -.PN long -is 32 bits. -The -.PN PackData -macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. -However, much more work is needed to make this work properly. -.SH -Deriving the Correct Extension Opcode -.LP -The remaining problem a writer of an extension stub procedure faces that -the core protocol does not face is to map from the call to the proper -major and minor opcodes. -While there are a number of strategies, -the simplest and fastest is outlined below. -.IP 1. 5 -Declare an array of pointers, _NFILE long (this is normally found -in -.hN stdio.h -and is the number of file descriptors supported on the system) -of type -.PN XExtCodes . -Make sure these are all initialized to NULL. -.IP 2. 5 -When your stub is entered, your initialization test is just to use -the display pointer passed in to access the file descriptor and an index -into the array. -If the entry is NULL, then this is the first time you -are entering the procedure for this display. -Call your initialization procedure and pass to it the display pointer. -.IP 3. 5 -Once in your initialization procedure, call -.PN XInitExtension ; -if it succeeds, store the pointer returned into this array. -Make sure to establish a close display handler to allow you to zero the entry. -Do whatever other initialization your extension requires. -(For example, install event handlers and so on.) -Your initialization procedure would normally return a pointer to the -.PN XExtCodes -structure for this extension, which is what would normally -be found in your array of pointers. -.IP 4. 5 -After returning from your initialization procedure, -the stub can now continue normally, because it has its major opcode safely -in its hand in the -.PN XExtCodes -structure. -.bp diff --git a/libX11/specs/libX11/AppC.xml b/libX11/specs/libX11/AppC.xml new file mode 100644 index 000000000..4af2de3fd --- /dev/null +++ b/libX11/specs/libX11/AppC.xml @@ -0,0 +1,3352 @@ +<appendix id="extensions">
+<title>Extensions</title>
+<para>
+<!-- .XE -->
+Because X can evolve by extensions to the core protocol,
+it is important that extensions not be perceived as second-class citizens.
+At some point,
+your favorite extensions may be adopted as additional parts of the
+X Standard.
+</para>
+<para>
+<!-- .LP -->
+Therefore, there should be little to distinguish the use of an extension from
+that of the core protocol.
+To avoid having to initialize extensions explicitly in application programs,
+it is also important that extensions perform lazy evaluations,
+automatically initializing themselves when called for the first time.
+</para>
+<para>
+<!-- .LP -->
+This appendix describes techniques for writing extensions to Xlib that will
+run at essentially the same performance as the core protocol requests.
+</para>
+<!-- .NT -->
+<note><para>
+It is expected that a given extension to X consists of multiple
+requests.
+Defining 10 new features as 10 separate extensions is a bad practice.
+Rather, they should be packaged into a single extension
+and should use minor opcodes to distinguish the requests.
+</para></note>
+<!-- .NE -->
+<para>
+<!-- .LP -->
+The symbols and macros used for writing stubs to Xlib are listed in
+<X11/Xlibint.h> .
+<!-- .SH -->
+Basic Protocol Support Routines
+</para>
+<para>
+The basic protocol requests for extensions are
+<function>XQueryExtension</function>
+and
+<function>XListExtensions</function>.
+</para>
+<indexterm significance="preferred"><primary>XQueryExtension</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XQueryExtension</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *name</parameter></paramdef>
+ <paramdef>int<parameter> *major_opcode_return</parameter></paramdef>
+ <paramdef>int<parameter> *first_event_return</parameter></paramdef>
+ <paramdef>int<parameter> *first_error_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>display</term>
+ <listitem>
+ <para>Specifies the connection to the X server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>name</term>
+ <listitem>
+ <para>Specifies the extension name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>major_opcode_return</term>
+ <listitem>
+ <para>Returns the major opcode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>first_event_return</term>
+ <listitem>
+ <para>Returns the first event code, if any.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>first_error_return</term>
+ <listitem>
+ <para>Returns the first error code, if any.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryExtension</function>
+function determines if the named extension is present.
+If the extension is not present,
+<function>XQueryExtension</function>
+returns
+<function>False</function>;
+otherwise, it returns
+<function>True</function>.
+If the extension is present,
+<function>XQueryExtension</function>
+returns the major opcode for the extension to major_opcode_return;
+otherwise,
+it returns zero.
+Any minor opcode and the request formats are specific to the
+extension.
+If the extension involves additional event types,
+<function>XQueryExtension</function>
+returns the base event type code to first_event_return;
+otherwise,
+it returns zero.
+The format of the events is specific to the extension.
+If the extension involves additional error codes,
+<function>XQueryExtension</function>
+returns the base error code to first_error_return;
+otherwise,
+it returns zero.
+The format of additional data in the errors is specific to the extension.
+</para>
+<para>
+<!-- .LP -->
+If the extension name is not in the Host Portable Character Encoding
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG''
+are all considered different names.
+<indexterm significance="preferred"><primary>XListExtensions</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> **XListExtensions</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *nextensions_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nextensions_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of extensions listed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListExtensions </function>
+function returns a list of all extensions supported by the server.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+<indexterm significance="preferred"><primary>XFreeExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeExtensionList</function></funcdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of extension names.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeExtensionList</function>
+function frees the memory allocated by
+<function>XListExtensions</function>.
+<!-- .SH -->
+Hooking into Xlib
+</para>
+<para>
+<!-- .LP -->
+These functions allow you to hook into the library.
+They are not normally used by application programmers but are used
+by people who need to extend the core X protocol and
+the X library interface.
+The functions, which generate protocol requests for X, are typically
+called stubs.
+</para>
+<para>
+<!-- .LP -->
+In extensions, stubs first should check to see if they have initialized
+themselves on a connection.
+If they have not, they then should call
+<function>XInitExtension </function>
+to attempt to initialize themselves on the connection.
+</para>
+<para>
+<!-- .LP -->
+If the extension needs to be informed of GC/font allocation or
+deallocation or if the extension defines new event types,
+the functions described here allow the extension to be
+called when these events occur.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XExtCodes</function>
+structure returns the information from
+<function>XInitExtension </function>
+and is defined in
+<X11/Xlib.h> :
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XExtCodes</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct _XExtCodes { /* public to extension, cannot be changed */
+ int extension; /* extension number */
+ int major_opcode; /* major op-code assigned by server */
+ int first_event; /* first event number for the extension */
+ int first_error; /* first error number for the extension */
+} XExtCodes;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XInitExtension</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XExtCodes<function> *XInitExtension</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitExtension</function>
+function determines if the named extension exists.
+Then, it allocates storage for maintaining the
+information about the extension on the connection,
+chains this onto the extension list for the connection,
+and returns the information the stub implementor will need to access
+the extension.
+If the extension does not exist,
+<function>XInitExtension</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+If the extension name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG''
+are all considered different names.
+</para>
+<para>
+<!-- .LP -->
+The extension number in the
+<function>XExtCodes </function>
+structure is
+needed in the other calls that follow.
+This extension number is unique only to a single connection.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XAddExtension</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XExtCodes<function> *XAddExtension</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For local Xlib extensions, the
+<function>XAddExtension</function>
+function allocates the
+<function>XExtCodes</function>
+structure, bumps the extension number count,
+and chains the extension onto the extension list.
+(This permits extensions to Xlib without requiring server extensions.)
+<!-- .SH -->
+Hooks into the Library
+</para>
+<para>
+<!-- .LP -->
+These functions allow you to define procedures that are to be
+called when various circumstances occur.
+The procedures include the creation of a new GC for a connection,
+the copying of a GC, the freeing of a GC, the creating and freeing of fonts,
+the conversion of events defined by extensions to and from wire
+format, and the handling of errors.
+</para>
+<para>
+<!-- .LP -->
+All of these functions return the previous procedure defined for this
+extension.
+<indexterm significance="preferred"><primary>XESetCloseDisplay</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XESetCloseDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when the display is closed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCloseDisplay</function>
+function defines a procedure to be called whenever
+<function>XCloseDisplay </function>
+is called.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When
+<function>XCloseDisplay </function>
+is called,
+your procedure is called
+with these arguments:
+</para>
+<literallayout class="monospaced">
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>codes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+</literallayout>
+<para>
+<indexterm significance="preferred"><primary>XESetCreateGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetCreateGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when a GC is closed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCreateGC</function>
+function defines a procedure to be called whenever
+a new GC is created.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When a GC is created,
+your procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>gc</emphasis>, <emphasis remap='I'>codes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ GC <emphasis remap='I'>gc</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+</literallayout>
+</para>
+<indexterm significance="preferred"><primary>XESetCopyGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetCopyGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when GC components are copied.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCopyGC</function>
+function defines a procedure to be called whenever
+a GC is copied.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When a GC is copied,
+your procedure is called with these arguments:
+</para>
+<literallayout class="monospaced">
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>gc</emphasis>, <emphasis remap='I'>codes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ GC <emphasis remap='I'>gc</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+</literallayout>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> *XESetFreeGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when a GC is freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XESetFreeGC</function>
+function defines a procedure to be called whenever
+a GC is freed.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When a GC is freed,
+your procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>gc</emphasis>, <emphasis remap='I'>codes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ GC <emphasis remap='I'>gc</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XESetCreateFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetCreateFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when a font is created.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCreateFont</function>
+function defines a procedure to be called whenever
+<function>XLoadQueryFont </function>
+and
+<function>XQueryFont</function>
+are called.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When
+<function>XLoadQueryFont </function>
+or
+<function>XQueryFont</function>
+is called,
+your procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>fs</emphasis>, <emphasis remap='I'>codes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XFontStruct *<emphasis remap='I'>fs</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XESetFreeFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetFreeFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when a font is freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetFreeFont</function>
+function defines a procedure to be called whenever
+<function>XFreeFont </function>
+is called.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When
+<function>XFreeFont </function>
+is called, your procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>fs</emphasis>, <emphasis remap='I'>codes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XFontStruct *<emphasis remap='I'>fs</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetWireToEvent</function>
+and
+<function>XESetEventToWire</function>
+functions allow you to define new events to the library.
+An
+<function>XEvent</function>
+structure always has a type code (type
+<function>int</function>)
+as the first component.
+This uniquely identifies what kind of event it is.
+The second component is always the serial number (type
+<function>unsigned</function>
+<function>long</function>)
+of the last request processed by the server.
+The third component is always a Boolean (type
+<function>Bool</function>)
+indicating whether the event came from a
+<function>SendEvent</function>
+protocol request.
+The fourth component is always a pointer to the display
+the event was read from.
+The fifth component is always a resource ID of one kind or another,
+usually a window, carefully selected to be useful to toolkit dispatchers.
+The fifth component should always exist, even if
+the event does not have a natural destination;
+if there is no value
+from the protocol to put in this component, initialize it to zero.
+<!-- .NT -->
+There is an implementation limit such that your host event
+structure size cannot be bigger than the size of the
+<function>XEvent </function>
+union of structures.
+There also is no way to guarantee that more than 24 elements or 96 characters
+in the structure will be fully portable between machines.
+<!-- .NE -->
+<indexterm significance="preferred"><primary>XESetWireToEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetWireToEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> event_number</parameter></paramdef>
+ <paramdef>Status<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event code.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when converting an event.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetWireToEvent</function>
+function defines a procedure to be called when an event
+needs to be converted from wire format
+(<function>xEvent</function>)
+to host format
+(<function>XEvent</function>).
+The event number defines which protocol event number to install a
+conversion procedure for.
+<function>XESetWireToEvent</function>
+returns any previously defined procedure.
+<!-- .NT -->
+You can replace a core event conversion function with one
+of your own, although this is not encouraged.
+It would, however, allow you to intercept a core event
+and modify it before being placed in the queue or otherwise examined.
+<!-- .NE -->
+When Xlib needs to convert an event from wire format to host
+format, your procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+Status (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>re</emphasis>, <emphasis remap='I'>event</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XEvent *<emphasis remap='I'>re</emphasis>;
+ xEvent *<emphasis remap='I'>event</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Your procedure must return status to indicate if the conversion succeeded.
+The re argument is a pointer to where the host format event should be stored,
+and the event argument is the 32-byte wire event structure.
+In the
+<function>XEvent </function>
+structure you are creating,
+you must fill in the five required members of the event structure.
+You should fill in the type member with the type specified for the
+<function>xEvent </function>
+structure.
+You should copy all other members from the
+<function>xEvent </function>
+structure (wire format) to the
+<function>XEvent </function>
+structure (host format).
+Your conversion procedure should return
+<function>True</function>
+if the event should be placed in the queue or
+<function>False</function>
+if it should not be placed in the queue.
+</para>
+<para>
+<!-- .LP -->
+To initialize the serial number component of the event, call
+<function>_XSetLastRequestRead</function>
+with the event and use the return value.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>_XSetLastRequestRead</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long<function> _XSetLastRequestRead</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>xGenericReply<parameter> *rep</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rep</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the wire event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XSetLastRequestRead</function>
+function computes and returns a complete serial number from the partial
+serial number in the event.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XESetEventToWire</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> *XESetEventToWire</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> event_number</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event code.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when converting an event.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetEventToWire</function>
+function defines a procedure to be called when an event
+needs to be converted from host format
+(<function>XEvent</function>)
+to wire format
+(<function>xEvent</function>)
+form.
+The event number defines which protocol event number to install a
+conversion procedure for.
+<function>XESetEventToWire</function>
+returns any previously defined procedure.
+It returns zero if the conversion fails or nonzero otherwise.
+<!-- .NT -->
+You can replace a core event conversion function with one
+of your own, although this is not encouraged.
+It would, however, allow you to intercept a core event
+and modify it before being sent to another client.
+<!-- .NE -->
+When Xlib needs to convert an event from host format to wire format,
+your procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>re</emphasis>, <emphasis remap='I'>event</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XEvent *<emphasis remap='I'>re</emphasis>;
+ xEvent *<emphasis remap='I'>event</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The re argument is a pointer to the host format event,
+and the event argument is a pointer to where the 32-byte wire event
+structure should be stored.
+You should fill in the type with the type from the
+<function>XEvent </function>
+structure.
+All other members then should be copied from the host format to the
+<function>xEvent </function>
+structure.
+<indexterm significance="preferred"><primary>XESetWireToError</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> *XESetWireToError</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> error_number</parameter></paramdef>
+ <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>error_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the error code.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when an error is received.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetWireToError</function>
+function defines a procedure to be called when an extension
+error needs to be converted from wire format to host format.
+The error number defines which protocol error code to install
+the conversion procedure for.
+<function>XESetWireToError</function>
+returns any previously defined procedure.
+</para>
+<para>
+<!-- .LP -->
+Use this function for extension errors that contain additional error values
+beyond those in a core X error, when multiple wire errors must be combined
+into a single Xlib error, or when it is necessary to intercept an
+X error before it is otherwise examined.
+</para>
+<para>
+<!-- .LP -->
+When Xlib needs to convert an error from wire format to host format,
+the procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+Bool (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>he</emphasis>, <emphasis remap='I'>we</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XErrorEvent *<emphasis remap='I'>he</emphasis>;
+ xError *<emphasis remap='I'>we</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The he argument is a pointer to where the host format error should be stored.
+The structure pointed at by he is guaranteed to be as large as an
+<function>XEvent</function>
+structure and so can be cast to a type larger than an
+<function>XErrorEvent</function>
+to store additional values.
+If the error is to be completely ignored by Xlib
+(for example, several protocol error structures will be combined into
+one Xlib error),
+then the function should return
+<function>False</function>;
+otherwise, it should return
+<function>True</function>.
+<indexterm significance="preferred"><primary>XESetError</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetError</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when an error is received.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Inside Xlib, there are times that you may want to suppress the
+calling of the external error handling when an error occurs.
+This allows status to be returned on a call at the cost of the call
+being synchronous (though most such functions are query operations, in any
+case, and are typically programmed to be synchronous).
+</para>
+<para>
+<!-- .LP -->
+When Xlib detects a protocol error in
+<function>_XReply</function>,
+it calls your procedure with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+int (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>err</emphasis>, <emphasis remap='I'>codes</emphasis>, <emphasis remap='I'>ret_code</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ xError *<emphasis remap='I'>err</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+ int *<emphasis remap='I'>ret_code</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The err argument is a pointer to the 32-byte wire format error.
+The codes argument is a pointer to the extension codes structure.
+The ret_code argument is the return code you may want
+<function>_XReply </function>
+returned to.
+</para>
+<para>
+<!-- .LP -->
+If your procedure returns a zero value,
+the error is not suppressed, and
+the client's error handler is called.
+(For further information, see section 11.8.2.)
+If your procedure returns nonzero,
+the error is suppressed, and
+<function>_XReply </function>
+returns the value of ret_code.
+<indexterm significance="preferred"><primary>XESetErrorString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XESetErrorString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>char<parameter> *(*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call to obtain an error string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorText </function>
+function returns a string to the user for an error.
+<function>XESetErrorString</function>
+allows you to define a procedure to be called that
+should return a pointer to the error message.
+The following is an example.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>code</emphasis>, <emphasis remap='I'>codes</emphasis>, <emphasis remap='I'>buffer</emphasis>, <emphasis remap='I'>nbytes</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ int <emphasis remap='I'>code</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+ char *<emphasis remap='I'>buffer</emphasis>;
+ int <emphasis remap='I'>nbytes</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Your procedure is called with the error code for every error detected.
+You should copy nbytes of a null-terminated string containing the
+error message into buffer.
+<indexterm significance="preferred"><primary>XESetPrintErrorValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> *XESSetPrintErrorValues</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>void<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when an error is printed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetPrintErrorValues</function>
+function defines a procedure to be called when an extension
+error is printed, to print the error values.
+Use this function for extension errors that contain additional error values
+beyond those in a core X error.
+It returns any previously defined procedure.
+</para>
+<para>
+<!-- .LP -->
+When Xlib needs to print an error,
+the procedure is called with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+void (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>ev</emphasis>, <emphasis remap='I'>fp</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XErrorEvent *<emphasis remap='I'>ev</emphasis>;
+ void *<emphasis remap='I'>fp</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The structure pointed at by ev is guaranteed to be as large as an
+<function>XEvent</function>
+structure and so can be cast to a type larger than an
+<function>XErrorEvent</function>
+to obtain additional values set by using
+<function>XESetWireToError</function>.
+The underlying type of the fp argument is system dependent;
+on a <acronym>POSIX</acronym>-compliant system, fp should be cast to type FILE*.
+<indexterm significance="preferred"><primary>XESetFlushGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetFlushGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> *(*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when a GC is flushed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The procedure set by the
+<function>XESetFlushGC</function>
+function has the same interface as the procedure set by the
+<function>XESetCopyGC</function>
+function, but is called when a GC cache needs to be updated in the server.
+<indexterm significance="preferred"><primary>XESetBeforeFlush</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XESetCopyGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> extension</parameter></paramdef>
+ <paramdef>int<parameter> *(*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to call when a buffer is flushed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetBeforeFlush</function>
+function defines a procedure to be called when data is about to be
+sent to the server. When data is about to be sent, your procedure is
+called one or more times with these arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+void (*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>codes</emphasis>, <emphasis remap='I'>data</emphasis>, <emphasis remap='I'>len</emphasis>)
+ Display *<emphasis remap='I'>display</emphasis>;
+ XExtCodes *<emphasis remap='I'>codes</emphasis>;
+ char *<emphasis remap='I'>data</emphasis>;
+ long <emphasis remap='I'>len</emphasis>;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The data argument specifies a portion of the outgoing data buffer,
+and its length in bytes is specified by the len argument.
+Your procedure must not alter the contents of the data and must not
+do additional protocol requests to the same display.
+<!-- .SH -->
+Hooks onto Xlib Data Structures
+</para>
+<para>
+<!-- .LP -->
+Various Xlib data structures have provisions for extension procedures
+to chain extension supplied data onto a list.
+These structures are
+<function>GC</function>,
+<function>Visual</function>,
+<function>Screen</function>,
+<function>ScreenFormat</function>,
+<function>Display</function>,
+and
+<function>XFontStruct</function>.
+Because the list pointer is always the first member in the structure,
+a single set of procedures can be used to manipulate the data
+on these lists.
+</para>
+<para>
+<!-- .LP -->
+The following structure is used in the functions in this section
+and is defined in
+<X11/Xlib.h>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XExtData</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct _XExtData {
+ int number; /* number returned by XInitExtension */
+ struct _XExtData *next; /* next item on list of data for structure */
+ int (*free_private)(); /* if defined, called to free private */
+ XPointer private_data; /* data private to this extension. */
+} XExtData;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When any of the data structures listed above are freed,
+the list is walked, and the structure's free procedure (if any) is called.
+If free is NULL,
+then the library frees both the data pointed to by the private_data member
+and the structure itself.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+union { Display *display;
+ GC gc;
+ Visual *visual;
+ Screen *screen;
+ ScreenFormat *pixmap_format;
+ XFontStruct *font } XEDataObject;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XEHeadOfExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XExtData<function> **XEHeadOfExtensionList</function></funcdef>
+ <paramdef>XEDataObject<parameter> object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEHeadOfExtensionList</function>
+function returns a pointer to the list of extension structures attached
+to the specified object.
+In concert with
+<function>XAddToExtensionList</function>,
+<function>XEHeadOfExtensionList</function>
+allows an extension to attach arbitrary data to any of the structures
+of types contained in
+<function>XEDataObject</function>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XAddToExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAddToExtensionList</function></funcdef>
+ <paramdef>XExtData<parameter> **structure</parameter></paramdef>
+ <paramdef>XExtData<parameter> *ext_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>structure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ext_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension data structure to add.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The structure argument is a pointer to one of the data structures
+enumerated above.
+You must initialize ext_data->number with the extension number
+before calling this function.
+<indexterm significance="preferred"><primary>XFindOnExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XExtData<function> *XFindOnExtensionList</function></funcdef>
+ <paramdef>struct_XExtData<parameter> **structure</parameter></paramdef>
+ <paramdef>int<parameter> number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>structure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension number from
+<function>XInitExtension</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFindOnExtensionList</function>
+function returns the first extension data structure
+for the extension numbered number.
+It is expected that an extension will add at most one extension
+data structure to any single data structure's extension data list.
+There is no way to find additional structures.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XAllocID </function>
+macro, which allocates and returns a resource ID, is defined in
+<X11/Xlib.h>.
+<indexterm significance="preferred"><primary>XAllocID</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAllocID</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This macro is a call through the
+<function>Display</function>
+structure to an internal resource ID allocator.
+It returns a resource ID that you can use when creating new resources.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XAllocIDs</function>
+macro allocates and returns an array of resource ID.
+<indexterm significance="preferred"><primary>XAllocIDs</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAllocIDs</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> *ids_return</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ids_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the resource IDs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rep</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of resource IDs requested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This macro is a call through the
+<function>Display</function>
+structure to an internal resource ID allocator.
+It returns resource IDs to the array supplied by the caller.
+To correctly handle automatic reuse of resource IDs, you must call
+<function>XAllocIDs</function>
+when requesting multiple resource IDs. This call might generate
+protocol requests.
+<!-- .SH -->
+GC Caching
+</para>
+<para>
+<!-- .LP -->
+GCs are cached by the library to allow merging of independent change
+requests to the same GC into single protocol requests.
+This is typically called a write-back cache.
+Any extension procedure whose behavior depends on the contents of a GC
+must flush the GC cache to make sure the server has up-to-date contents
+in its GC.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>FlushGC</function>
+macro checks the dirty bits in the library's GC structure and calls
+<function>_XFlushGCCache </function>
+if any elements have changed.
+The
+<function>FlushGC</function>
+macro is defined as follows:
+<indexterm significance="preferred"><primary>FlushGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> FlushGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Note that if you extend the GC to add additional resource ID components,
+you should ensure that the library stub sends the change request immediately.
+This is because a client can free a resource immediately after
+using it, so if you only stored the value in the cache without
+forcing a protocol request, the resource might be destroyed before being
+set into the GC.
+You can use the
+<function>_XFlushGCCache </function>
+procedure
+to force the cache to be flushed.
+The
+<function>_XFlushGCCache </function>
+procedure
+is defined as follows:
+<indexterm significance="preferred"><primary>_XFlushGCCache</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> _XFlushGCCache</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .SH -->
+Graphics Batching
+</para>
+<para>
+<!-- .LP -->
+If you extend X to add more poly graphics primitives, you may be able to
+take advantage of facilities in the library to allow back-to-back
+single calls to be transformed into poly requests.
+This may dramatically improve performance of programs that are not
+written using poly requests.
+A pointer to an
+<function>xReq</function>,
+called last_req in the display structure, is the last request being processed.
+By checking that the last request
+type, drawable, gc, and other options are the same as the new one
+and that there is enough space left in the buffer, you may be able
+to just extend the previous graphics request by extending the length
+field of the request and appending the data to the buffer.
+This can improve performance by five times or more in naive programs.
+For example, here is the source for the
+<function>XDrawPoint </function>
+stub.
+(Writing extension stubs is discussed in the next section.)
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<!-- .sM -->
+<!-- .nf -->
+
+#include <X11/Xlibint.h>
+
+/* precompute the maximum size of batching request allowed */
+
+static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
+
+XDrawPoint(dpy, d, gc, x, y)
+ register Display *dpy;
+ Drawable d;
+ GC gc;
+ int x, y; /* INT16 */
+{
+ xPoint *point;
+ LockDisplay(dpy);
+ FlushGC(dpy, gc);
+ {
+ register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
+ /* if same as previous request, with same drawable, batch requests */
+ if (
+ (req->reqType == X_PolyPoint)
+ && (req->drawable == d)
+ && (req->gc == gc->gid)
+ && (req->coordMode == CoordModeOrigin)
+ && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
+ && (((char *)dpy->bufptr - (char *)req) < size) ) {
+ point = (xPoint *) dpy->bufptr;
+ req->length += sizeof (xPoint) >> 2;
+ dpy->bufptr += sizeof (xPoint);
+ }
+
+ else {
+ GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
+ req->drawable = d;
+ req->gc = gc->gid;
+ req->coordMode = CoordModeOrigin;
+ point = (xPoint *) (req + 1);
+ }
+ point->x = x;
+ point->y = y;
+ }
+ UnlockDisplay(dpy);
+ SyncHandle();
+}
+<!-- .fi -->
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To keep clients from generating very long requests that may monopolize the
+server,
+there is a symbol defined in
+<X11/Xlibint.h>
+of EPERBATCH on the number of requests batched.
+Most of the performance benefit occurs in the first few merged requests.
+Note that
+<function>FlushGC </function>
+is called <emphasis remap='I'>before</emphasis> picking up the value of last_req,
+because it may modify this field.
+<!-- .SH -->
+Writing Extension Stubs
+</para>
+<para>
+<!-- .LP -->
+All X requests always contain the length of the request,
+expressed as a 16-bit quantity of 32 bits.
+This means that a single request can be no more than 256K bytes in
+length.
+Some servers may not support single requests of such a length.
+The value of dpy->max_request_size contains the maximum length as
+defined by the server implementation.
+For further information,
+see ``X Window System Protocol.''
+<!-- .SH -->
+Requests, Replies, and Xproto.h
+</para>
+<para>
+<!-- .LP -->
+The
+<X11/Xproto.h>
+file contains three sets of definitions that
+are of interest to the stub implementor:
+request names, request structures, and reply structures.
+</para>
+<para>
+<!-- .LP -->
+You need to generate a file equivalent to
+<X11/Xproto.h>
+for your extension and need to include it in your stub procedure.
+Each stub procedure also must include
+<X11/Xlibint.h> .
+</para>
+<para>
+<!-- .LP -->
+The identifiers are deliberately chosen in such a way that, if the
+request is called X_DoSomething, then its request structure is
+xDoSomethingReq, and its reply is xDoSomethingReply.
+The GetReq family of macros, defined in
+<X11/Xlibint.h> ,
+takes advantage of this naming scheme.
+</para>
+<para>
+<!-- .LP -->
+For each X request,
+there is a definition in
+<X11/Xproto.h>
+that looks similar to this:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+#define X_DoSomething 42
+</literallayout>
+In your extension header file,
+this will be a minor opcode,
+instead of a major opcode.
+<!-- .SH -->
+Request Format
+</para>
+<para>
+<!-- .LP -->
+Every request contains an 8-bit major opcode and a 16-bit length field
+expressed in units of 4 bytes.
+Every request consists of 4 bytes of header
+(containing the major opcode, the length field, and a data byte) followed by
+zero or more additional bytes of data.
+The length field defines the total length of the request, including the header.
+The length field in a request must equal the minimum length required to contain
+the request.
+If the specified length is smaller or larger than the required length,
+the server should generate a
+<function>BadLength </function>
+error.
+Unused bytes in a request are not required to be zero.
+Extensions should be designed in such a way that long protocol requests
+can be split up into smaller requests,
+if it is possible to exceed the maximum request size of the server.
+The protocol guarantees the maximum request size to be no smaller than
+4096 units (16384 bytes).
+</para>
+<para>
+<!-- .LP -->
+Major opcodes 128 through 255 are reserved for extensions.
+Extensions are intended to contain multiple requests,
+so extension requests typically have an additional minor opcode encoded
+in the second data byte in the request header,
+but the placement and interpretation of this minor opcode as well as all
+other fields in extension requests are not defined by the core protocol.
+Every request is implicitly assigned a sequence number (starting with one)
+used in replies, errors, and events.
+</para>
+<para>
+<!-- .LP -->
+To help but not cure portability problems to certain machines, the
+<function>B16</function>
+and
+<function>B32</function>
+macros have been defined so that they can become bitfield specifications
+on some machines.
+For example, on a Cray,
+these should be used for all 16-bit and 32-bit quantities, as discussed below.
+</para>
+<para>
+<!-- .LP -->
+Most protocol requests have a corresponding structure typedef in
+<X11/Xproto.h>,
+which looks like:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>xDoSomethingReq</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct _DoSomethingReq {
+ CARD8 reqType; /* X_DoSomething */
+ CARD8 someDatum; /* used differently in different requests */
+ CARD16 length B16; /* total # of bytes in request, divided by 4 */
+ ...
+ /* request-specific data */
+ ...
+} xDoSomethingReq;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If a core protocol request has a single 32-bit argument,
+you need not declare a request structure in your extension header file.
+Instead, such requests use the
+<function>xResourceReq</function>
+structure in
+<X11/Xproto.h>.
+This structure is used for any request whose single argument is a
+<function>Window</function>,
+<function>Pixmap</function>,
+<function>Drawable</function>,
+<function>GContext</function>,
+<function>Font</function>,
+<function>Cursor</function>,
+<function>Colormap</function>,
+<function>Atom</function>,
+or
+<function>VisualID</function>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>xResourceReq</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct _ResourceReq {
+ CARD8 reqType; /* the request type, e.g. X_DoSomething */
+ BYTE pad; /* not used */
+ CARD16 length B16; /* 2 (= total # of bytes in request, divided by 4) */
+ CARD32 id B32; /* the Window, Drawable, Font, GContext, etc. */
+} xResourceReq;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If convenient,
+you can do something similar in your extension header file.
+</para>
+<para>
+<!-- .LP -->
+In both of these structures,
+the reqType field identifies the type of the request (for example,
+X_MapWindow or X_CreatePixmap).
+The length field tells how long the request is
+in units of 4-byte longwords.
+This length includes both the request structure itself and any
+variable-length data, such as strings or lists, that follow the
+request structure.
+Request structures come in different sizes,
+but all requests are padded to be multiples of four bytes long.
+</para>
+<para>
+<!-- .LP -->
+A few protocol requests take no arguments at all.
+Instead, they use the
+<function>xReq </function>
+structure in
+<X11/Xproto.h>,
+which contains only a reqType and a length (and a pad byte).
+</para>
+<para>
+<!-- .LP -->
+If the protocol request requires a reply,
+then
+<X11/Xproto.h>
+also contains a reply structure typedef:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>xDoSomethingReply</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct _DoSomethingReply {
+ BYTE type; /* always X_Reply */
+ BYTE someDatum; /* used differently in different requests */
+ CARD16 sequenceNumber B16; /* # of requests sent so far */
+ CARD32 length B32; /* # of additional bytes, divided by 4 */
+ ...
+ /* request-specific data */
+ ...
+} xDoSomethingReply;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Most of these reply structures are 32 bytes long.
+If there are not that many reply values,
+then they contain a sufficient number of pad fields
+to bring them up to 32 bytes.
+The length field is the total number of bytes in the request minus 32,
+divided by 4.
+This length will be nonzero only if:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The reply structure is followed by variable-length data,
+such as a list or string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The reply structure is longer than 32 bytes.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Only
+<function>GetWindowAttributes</function>,
+<function>QueryFont</function>,
+<function>QueryKeymap</function>,
+and
+<function>GetKeyboardControl </function>
+have reply structures longer than 32 bytes in the core protocol.
+</para>
+<para>
+<!-- .LP -->
+A few protocol requests return replies that contain no data.
+<X11/Xproto.h>
+does not define reply structures for these.
+Instead, they use the
+<function>xGenericReply</function>
+structure, which contains only a type, length,
+and sequence number (and sufficient padding to make it 32 bytes long).
+<!-- .SH -->
+Starting to Write a Stub Procedure
+</para>
+<para>
+<!-- .LP -->
+An Xlib stub procedure should start like this:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+#include "<X11/Xlibint.h>
+
+XDoSomething (arguments, ... )
+/* argument declarations */
+{
+
+register XDoSomethingReq *req;
+...
+</literallayout>
+If the protocol request has a reply,
+then the variable declarations should include the reply structure for the request.
+The following is an example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+xDoSomethingReply rep;
+</literallayout>
+<!-- .SH -->
+Locking Data Structures
+</para>
+<para>
+<!-- .LP -->
+To lock the display structure for systems that
+want to support multithreaded access to a single display connection,
+each stub will need to lock its critical section.
+Generally, this section is the point from just before the appropriate GetReq
+call until all arguments to the call have been stored into the buffer.
+The precise instructions needed for this locking depend upon the machine
+architecture.
+Two calls, which are generally implemented as macros, have been provided.
+<indexterm significance="preferred"><primary>LockDisplay</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> LockDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>UnlockDisplay</primary></indexterm>
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> UnlockDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .SH -->
+Sending the Protocol Request and Arguments
+</para>
+<para>
+<!-- .LP -->
+After the variable declarations,
+a stub procedure should call one of four macros defined in
+<X11/Xlibint.h>:
+<function>GetReq</function>,
+<function>GetReqExtra</function>,
+<function>GetResReq</function>,
+or
+<function>GetEmptyReq</function>.
+All of these macros take, as their first argument,
+the name of the protocol request as declared in
+<X11/Xproto.h>
+except with X_ removed.
+Each one declares a
+<function>Display </function>
+structure pointer,
+called dpy, and a pointer to a request structure, called req,
+which is of the appropriate type.
+The macro then appends the request structure to the output buffer,
+fills in its type and length field, and sets req to point to it.
+</para>
+<para>
+<!-- .LP -->
+If the protocol request has no arguments (for instance, X_GrabServer),
+then use
+<function>GetEmptyReq</function>.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+GetEmptyReq (DoSomething, req);
+</literallayout>
+If the protocol request has a single 32-bit argument (such as a
+<function>Pixmap</function>,
+<function>Window</function>,
+<function>Drawable</function>,
+<function>Atom</function>,
+and so on),
+then use
+<function>GetResReq</function>.
+The second argument to the macro is the 32-bit object.
+<function>X_MapWindow </function>
+is a good example.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+GetResReq (DoSomething, rid, req);
+</literallayout>
+The rid argument is the
+<function>Pixmap</function>,
+<function>Window</function>,
+or other resource ID.
+</para>
+<para>
+<!-- .LP -->
+If the protocol request takes any other argument list,
+then call
+<function>GetReq</function>.
+After the
+<function>GetReq</function>,
+you need to set all the other fields in the request structure,
+usually from arguments to the stub procedure.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+GetReq (DoSomething, req);
+/* fill in arguments here */
+req->arg1 = arg1;
+req->arg2 = arg2;
+...
+</literallayout>
+A few stub procedures (such as
+<function>XCreateGC </function>
+and
+<function>XCreatePixmap</function>)
+return a resource ID to the caller but pass a resource ID as an argument
+to the protocol request.
+Such procedures use the macro
+<function>XAllocID </function>
+to allocate a resource ID from the range of IDs
+that were assigned to this client when it opened the connection.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+rid = req->rid = XAllocID();
+...
+return (rid);
+</literallayout>
+Finally, some stub procedures transmit a fixed amount of variable-length
+data after the request.
+Typically, these procedures (such as
+<function>XMoveWindow </function>
+and
+<function>XSetBackground</function>)
+are special cases of more general functions like
+<function>XMoveResizeWindow </function>
+and
+<function>XChangeGC</function>.
+These procedures use
+<function>GetReqExtra</function>,
+which is the same as
+<function>GetReq</function>
+except that it takes an additional argument (the number of
+extra bytes to allocate in the output buffer after the request structure).
+This number should always be a multiple of four.
+<!-- .SH -->
+Variable Length Arguments
+</para>
+<para>
+<!-- .LP -->
+Some protocol requests take additional variable-length data that
+follow the
+<function>xDoSomethingReq </function>
+structure.
+The format of this data varies from request to request.
+Some requests require a sequence of 8-bit bytes,
+others a sequence of 16-bit or 32-bit entities,
+and still others a sequence of structures.
+</para>
+<para>
+<!-- .LP -->
+It is necessary to add the length of any variable-length data to the
+length field of the request structure.
+That length field is in units of 32-bit longwords.
+If the data is a string or other sequence of 8-bit bytes,
+then you must round the length up and shift it before adding:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+req->length += (nbytes+3)>>2;
+</literallayout>
+To transmit variable-length data, use the
+<function>Data </function>
+macros.
+If the data fits into the output buffer,
+then this macro copies it to the buffer.
+If it does not fit, however,
+the
+<function>Data </function>
+macro calls
+<function>_XSend</function>,
+which transmits first the contents of the buffer and then your data.
+The
+<function>Data </function>
+macros take three arguments:
+the display, a pointer to the beginning of the data,
+and the number of bytes to be sent.
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> Data</function></funcdef>
+ <paramdef><parameter> display</parameter></paramdef>
+ <paramdef>(char<parameter> *</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>Data</function>,
+<function>Data16</function>,
+and
+<function>Data32</function>
+are macros that may use their last argument
+more than once, so that argument should be a variable rather than
+an expression such as ``nitems*sizeof(item)''.
+You should do that kind of computation in a separate statement before calling
+them.
+Use the appropriate macro when sending byte, short, or long data.
+</para>
+<para>
+<!-- .LP -->
+If the protocol request requires a reply,
+then call the procedure
+<function>_XSend </function>
+instead of the
+<function>Data </function>
+macro.
+<function>_XSend </function>
+takes the same arguments, but because it sends your data immediately instead of
+copying it into the output buffer (which would later be flushed
+anyway by the following call on
+<function>_XReply</function>),
+it is faster.
+<!-- .SH -->
+Replies
+</para>
+<para>
+<!-- .LP -->
+If the protocol request has a reply,
+then call
+<function>_XReply </function>
+after you have finished dealing with
+all the fixed-length and variable-length arguments.
+<function>_XReply </function>
+flushes the output buffer and waits for an
+<function>xReply </function>
+packet to arrive.
+If any events arrive in the meantime,
+<function>_XReply </function>
+places them in the queue for later use.
+<indexterm significance="preferred"><primary>_XReply</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> _XReply</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>xReply<parameter> *rep</parameter></paramdef>
+ <paramdef>int<parameter> extra</parameter></paramdef>
+ <paramdef>Bool<parameter> discard</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rep</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the reply structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>extra</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of 32-bit words expected after the replay.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>discard</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies if any data beyond that specified in the extra argument
+should be discarded.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XReply </function>
+function waits for a reply packet and copies its contents into the
+specified rep.
+<function>_XReply </function>
+handles error and event packets that occur before the reply is received.
+<function>_XReply </function>
+takes four arguments:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A
+<function>Display </function>
+* structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A pointer to a reply structure (which must be cast to an
+<function>xReply </function>
+*)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The number of additional 32-bit words (beyond
+<function>sizeof( xReply</function>)
+= 32 bytes)
+in the reply structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A Boolean that indicates whether
+<function>_XReply </function>
+is to discard any additional bytes
+beyond those it was told to read
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Because most reply structures are 32 bytes long,
+the third argument is usually 0.
+The only core protocol exceptions are the replies to
+<function>GetWindowAttributes</function>,
+<function>QueryFont</function>,
+<function>QueryKeymap</function>,
+and
+<function>GetKeyboardControl</function>,
+which have longer replies.
+</para>
+<para>
+<!-- .LP -->
+The last argument should be
+<function>False </function>
+if the reply structure is followed
+by additional variable-length data (such as a list or string).
+It should be
+<function>True </function>
+if there is not any variable-length data.
+<!-- .NT -->
+This last argument is provided for upward-compatibility reasons
+to allow a client to communicate properly with a hypothetical later
+version of the server that sends more data than the client expected.
+For example, some later version of
+<function>GetWindowAttributes </function>
+might use a
+larger, but compatible,
+<function>xGetWindowAttributesReply </function>
+that contains additional attribute data at the end.
+<!-- .NE -->
+<function>_XReply </function>
+returns
+<function>True</function>
+if it received a reply successfully or
+<function>False </function>
+if it received any sort of error.
+</para>
+<para>
+<!-- .LP -->
+For a request with a reply that is not followed by variable-length
+data, you write something like:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .R -->
+_XReply(display, (xReply *)&rep, 0, True);
+*ret1 = rep.ret1;
+*ret2 = rep.ret2;
+*ret3 = rep.ret3;
+...
+UnlockDisplay(dpy);
+SyncHandle();
+return (rep.ret4);
+}
+</literallayout>
+If there is variable-length data after the reply,
+change the
+<function>True </function>
+to
+<function>False</function>,
+and use the appropriate
+<function>_XRead </function>
+function to read the variable-length data.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> _XRead</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *data_return</parameter></paramdef>
+ <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead</function>
+function reads the specified number of bytes into data_return.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> _XRead16</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>short<parameter> *data_return</parameter></paramdef>
+ <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead16</function>
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> _XRead32</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>long<parameter> *data_return</parameter></paramdef>
+ <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead32</function>
+function reads the specified number of bytes,
+unpacking them as 32-bit quantities,
+into the specified array as longs.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> _XRead16Pad</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>short<parameter> *data_return</parameter></paramdef>
+ <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead16Pad</function>
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+If the number of bytes is not a multiple of four,
+<function>_XRead16Pad</function>
+reads and discards up to two additional pad bytes.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> _XReadPad</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *data_return</parameter></paramdef>
+ <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XReadPad</function>
+function reads the specified number of bytes into data_return.
+If the number of bytes is not a multiple of four,
+<function>_XReadPad</function>
+reads and discards up to three additional pad bytes.
+</para>
+<para>
+<!-- .LP -->
+Each protocol request is a little different.
+For further information,
+see the Xlib sources for examples.
+<!-- .SH -->
+Synchronous Calling
+</para>
+<para>
+<!-- .LP -->
+Each procedure should have a call, just before returning to the user,
+to a macro called
+<function>SyncHandle</function>.
+If synchronous mode is enabled (see
+<function>XSynchronize</function>),
+the request is sent immediately.
+The library, however, waits until any error the procedure could generate
+at the server has been handled.
+<!-- .SH -->
+Allocating and Deallocating Memory
+</para>
+<para>
+<!-- .LP -->
+To support the possible reentry of these procedures,
+you must observe several conventions when allocating and deallocating memory,
+most often done when returning data to the user from the window
+system of a size the caller could not know in advance
+(for example, a list of fonts or a list of extensions).
+The standard C library functions on many systems
+are not protected against signals or other multithreaded uses.
+The following analogies to standard I/O library functions
+have been defined:
+</para>
+<para>
+<!-- .LP -->
+These should be used in place of any calls you would make to the normal
+C library functions.
+</para>
+<para>
+<!-- .LP -->
+If you need a single scratch buffer inside a critical section
+(for example, to pack and unpack data to and from the wire protocol),
+the general memory allocators may be too expensive to use
+(particularly in output functions, which are performance critical).
+The following function returns a scratch buffer for use within a
+critical section:
+<indexterm significance="preferred"><primary>_XAllocScratch</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *_XAllocScratch</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This storage must only be used inside of a critical section of your
+stub. The returned pointer cannot be assumed valid after any call
+that might permit another thread to execute inside Xlib. For example,
+the pointer cannot be assumed valid after any use of the
+<function>GetReq</function>
+or
+<function>Data</function>
+families of macros,
+after any use of
+<function>_XReply</function>,
+or after any use of the
+<function>_XSend</function>
+or
+<function>_XRead</function>
+families of functions.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The following function returns a scratch buffer for use across
+critical sections:
+<indexterm significance="preferred"><primary>_XAllocTemp</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *_XAllocTemp</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This storage can be used across calls that might permit another thread to
+execute inside Xlib. The storage must be explicitly returned to Xlib.
+The following function returns the storage:
+<indexterm significance="preferred"><primary>_XFreeTemp</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> _XFreeTemp</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *buf</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+You must pass back the same pointer and size that were returned by
+<function>_XAllocTemp</function>.
+<!-- .SH -->
+Portability Considerations
+</para>
+<para>
+<!-- .LP -->
+Many machine architectures,
+including many of the more recent <acronym>RISC</acronym> architectures,
+do not correctly access data at unaligned locations;
+their compilers pad out structures to preserve this characteristic.
+Many other machines capable of unaligned references pad inside of structures
+as well to preserve alignment, because accessing aligned data is
+usually much faster.
+Because the library and the server use structures to access data at
+arbitrary points in a byte stream,
+all data in request and reply packets <emphasis remap='I'>must</emphasis> be naturally aligned;
+that is, 16-bit data starts on 16-bit boundaries in the request
+and 32-bit data on 32-bit boundaries.
+All requests <emphasis remap='I'>must</emphasis> be a multiple of 32 bits in length to preserve
+the natural alignment in the data stream.
+You must pad structures out to 32-bit boundaries.
+Pad information does not have to be zeroed unless you want to
+preserve such fields for future use in your protocol requests.
+Floating point varies radically between machines and should be
+avoided completely if at all possible.
+</para>
+<para>
+<!-- .LP -->
+This code may run on machines with 16-bit ints.
+So, if any integer argument, variable, or return value either can take
+only nonnegative values or is declared as a
+<function>CARD16</function>
+in the protocol, be sure to declare it as
+<function>unsigned</function>
+<function>int</function>
+and not as
+<function>int</function>.
+(This, of course, does not apply to Booleans or enumerations.)
+</para>
+<para>
+<!-- .LP -->
+Similarly,
+if any integer argument or return value is declared
+<function>CARD32</function>
+in the protocol,
+declare it as an
+<function>unsigned</function>
+<function>long</function>
+and not as
+<function>int</function>
+or
+<function>long</function>.
+This also goes for any internal variables that may
+take on values larger than the maximum 16-bit
+<function>unsigned</function>
+<function>int</function>.
+</para>
+<para>
+<!-- .LP -->
+The library currently assumes that a
+<function>char</function>
+is 8 bits, a
+<function>short</function>
+is 16 bits, an
+<function>int</function>
+is 16 or 32 bits, and a
+<function>long</function>
+is 32 bits.
+The
+<function>PackData </function>
+macro is a half-hearted attempt to deal with the possibility of 32 bit shorts.
+However, much more work is needed to make this work properly.
+<!-- .SH -->
+Deriving the Correct Extension Opcode
+</para>
+<para>
+<!-- .LP -->
+The remaining problem a writer of an extension stub procedure faces that
+the core protocol does not face is to map from the call to the proper
+major and minor opcodes.
+While there are a number of strategies,
+the simplest and fastest is outlined below.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Declare an array of pointers, _NFILE long (this is normally found
+in
+<stdio.h>
+and is the number of file descriptors supported on the system)
+of type
+<function>XExtCodes</function>.
+Make sure these are all initialized to NULL.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When your stub is entered, your initialization test is just to use
+the display pointer passed in to access the file descriptor and an index
+into the array.
+If the entry is NULL, then this is the first time you
+are entering the procedure for this display.
+Call your initialization procedure and pass to it the display pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Once in your initialization procedure, call
+<function>XInitExtension</function>;
+if it succeeds, store the pointer returned into this array.
+Make sure to establish a close display handler to allow you to zero the entry.
+Do whatever other initialization your extension requires.
+(For example, install event handlers and so on.)
+Your initialization procedure would normally return a pointer to the
+<function>XExtCodes </function>
+structure for this extension, which is what would normally
+be found in your array of pointers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+After returning from your initialization procedure,
+the stub can now continue normally, because it has its major opcode safely
+in its hand in the
+<function>XExtCodes </function>
+structure.
+<!-- .bp -->
+ </para>
+ </listitem>
+</itemizedlist>
+</appendix>
diff --git a/libX11/specs/libX11/AppD b/libX11/specs/libX11/AppD deleted file mode 100644 index f96e06175..000000000 --- a/libX11/specs/libX11/AppD +++ /dev/null @@ -1,1183 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBAppendix D\fP\s-1 - -\s+1\fBCompatibility Functions\fP\s-1 -.sp 2 -.na -.LP -.XS -Appendix D: Compatibility Functions -.XE -.LP -The X Version 11 and X Version 10 functions discussed in this appendix -are obsolete, have been superseded by newer X Version 11 functions, -and are maintained for compatibility reasons only. -.SH -X Version 11 Compatibility Functions -.LP -You can use the X Version 11 compatibility functions to: -.IP \(bu 5 -Set standard properties -.IP \(bu 5 -Set and get window sizing hints -.IP \(bu 5 -Set and get an -.PN XStandardColormap -structure -.IP \(bu 5 -Parse window geometry -.IP \(bu 5 -Get X environment defaults -.SH -Setting Standard Properties -.LP -To specify a minimum set of properties describing the simplest application, -use -.PN XSetStandardProperties . -This function has been superseded by -.PN XSetWMProperties -and sets all or portions of the -WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, -and WM_NORMAL_HINTS properties. -.IN "XSetStandardProperties" "" "@DEF@" -.sM -.FD 0 -XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char *\fIwindow_name\fP\^; -.br - char *\fIicon_name\fP\^; -.br - Pixmap \fIicon_pixmap\fP\^; -.br - char **\fIargv\fP\^; -.br - int \fIargc\fP\^; -.br - XSizeHints *\fIhints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwindow_name\fP 1i -Specifies the window name, -which should be a null-terminated string. -.IP \fIicon_name\fP 1i -Specifies the icon name, -which should be a null-terminated string. -.IP \fIicon_pixmap\fP 1i -Specifies the bitmap that is to be used for the icon or -.PN None . -.IP \fIargv\fP 1i -Specifies the application's argument list. -.IP \fIargc\fP 1i -Specifies the number of arguments. -.IP \fIhints\fP 1i -Specifies a pointer to the size hints for the window in its normal state. -.LP -.eM -The -.PN XSetStandardProperties -function provides a means by which simple applications set the -most essential properties with a single call. -.PN XSetStandardProperties -should be used to give a window manager some information about -your program's preferences. -It should not be used by applications that need -to communicate more information than is possible with -.PN XSetStandardProperties . -(Typically, argv is the argv array of your main program.) -If the strings are not in the Host Portable Character Encoding, -the result is implementation-dependent. -.LP -.PN XSetStandardProperties -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.SH -Setting and Getting Window Sizing Hints -.LP -Xlib provides functions that you can use to set or get window sizing hints. -The functions discussed in this section use the flags and the -.PN XSizeHints -structure, as defined in the -.hN X11/Xutil.h -header file and use the WM_NORMAL_HINTS property. -.LP -.sp -To set the size hints for a given window in its normal state, use -.PN XSetNormalHints . -This function has been superseded by -.PN XSetWMNormalHints . -.IN "XSetNormalHints" "" "@DEF@" -.sM -.FD 0 -XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints\fP 1i -Specifies a pointer to the size hints for the window in its normal state. -.LP -.eM -The -.PN XSetNormalHints -function sets the size hints structure for the specified window. -Applications use -.PN XSetNormalHints -to inform the window manager of the size -or position desirable for that window. -In addition, -an application that wants to move or resize itself should call -.PN XSetNormalHints -and specify its new desired location and size -as well as making direct Xlib calls to move or resize. -This is because window managers may ignore redirected -configure requests, but they pay attention to property changes. -.LP -To set size hints, -an application not only must assign values to the appropriate members -in the hints structure but also must set the flags member of the structure -to indicate which information is present and where it came from. -A call to -.PN XSetNormalHints -is meaningless, unless the flags member is set to indicate which members of -the structure have been assigned values. -.LP -.PN XSetNormalHints -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To return the size hints for a window in its normal state, use -.PN XGetNormalHints . -This function has been superseded by -.PN XGetWMNormalHints . -.IN "XGetNormalHints" "" "@DEF@" -.sM -.FD 0 -Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints_return\fP 1i -Returns the size hints for the window in its normal state. -.LP -.eM -The -.PN XGetNormalHints -function returns the size hints for a window in its normal state. -It returns a nonzero status if it succeeds or zero if -the application specified no normal size hints for this window. -.LP -.PN XGetNormalHints -can generate a -.PN BadWindow -error. -.LP -.sp -The next two functions set and read the WM_ZOOM_HINTS property. -.LP -To set the zoom hints for a window, use -.PN XSetZoomHints . -This function is no longer supported by the -\fIInter-Client Communication Conventions Manual\fP. -.IN "XSetZoomHints" "" "@DEF@" -.sM -.FD 0 -XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIzhints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIzhints\fP 1i -Specifies a pointer to the zoom hints. -.LP -.eM -Many window managers think of windows in one of three states: -iconic, normal, or zoomed. -The -.PN XSetZoomHints -function provides the window manager with information for the window in the -zoomed state. -.LP -.PN XSetZoomHints -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To read the zoom hints for a window, use -.PN XGetZoomHints . -This function is no longer supported by the -\fIInter-Client Communication Conventions Manual\fP. -.IN "XGetZoomHints" "" "@DEF@" -.sM -.FD 0 -Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIzhints_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIzhints_return\fP 1i -Returns the zoom hints. -.LP -.eM -The -.PN XGetZoomHints -function returns the size hints for a window in its zoomed state. -It returns a nonzero status if it succeeds or zero if -the application specified no zoom size hints for this window. -.LP -.PN XGetZoomHints -can generate a -.PN BadWindow -error. -.LP -.sp -To set the value of any property of type WM_SIZE_HINTS, use -.PN XSetSizeHints . -This function has been superseded by -.PN XSetWMSizeHints . -.IN "XSetSizeHints" "" "@DEF@" -.sM -.FD 0 -XSetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints\fP 1i -Specifies a pointer to the size hints. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XSetSizeHints -function sets the -.PN XSizeHints -structure for the named property and the specified window. -This is used by -.PN XSetNormalHints -and -.PN XSetZoomHints -and can be used to set the value of any property of type WM_SIZE_HINTS. -Thus, it may be useful if other properties of that type get defined. -.LP -.PN XSetSizeHints -can generate -.PN BadAlloc , -.PN BadAtom , -and -.PN BadWindow -errors. -.LP -.sp -To read the value of any property of type WM_SIZE_HINTS, use -.PN XGetSizeHints . -This function has been superseded by -.PN XGetWMSizeHints . -.IN "XGetSizeHints" "" "@DEF@" -.sM -.FD 0 -Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints_return\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints_return\fP 1i -Returns the size hints. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XGetSizeHints -function returns the -.PN XSizeHints -structure for the named property and the specified window. -This is used by -.PN XGetNormalHints -and -.PN XGetZoomHints . -It also can be used to retrieve the value of any property of type -WM_SIZE_HINTS. -Thus, it may be useful if other properties of that type get defined. -.PN XGetSizeHints -returns a nonzero status if a size hint was defined -or zero otherwise. -.LP -.PN XGetSizeHints -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.SH -Getting and Setting an XStandardColormap Structure -.LP -To get the -.PN XStandardColormap -structure associated with one of the described atoms, use -.PN XGetStandardColormap . -This function has been superseded by -.PN XGetRGBColormap . -.IN "XGetStandardColormap" "" "@DEF@" -.sM -.FD 0 -Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XStandardColormap *\fIcolormap_return\fP\^; -.br - Atom \fIproperty\fP\^; /* RGB_BEST_MAP, etc. */ -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIcolormap_return\fP 1i -Returns the colormap associated with the specified atom. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XGetStandardColormap -function returns the colormap definition associated with the atom supplied -as the property argument. -.PN XGetStandardColormap -returns a nonzero status if successful and zero otherwise. -For example, -to fetch the standard -.PN GrayScale -colormap for a display, -you use -.PN XGetStandardColormap -with the following syntax: -.LP -.sM -.Ds 0 -.TA .5i 1.5i -.ta .5i 1.5i -XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP); -.De -.LP -.eM -See section 14.3 for the semantics of standard colormaps. -.LP -.PN XGetStandardColormap -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.LP -.sp -To set a standard colormap, use -.PN XSetStandardColormap . -This function has been superseded by -.PN XSetRGBColormap . -.IN "XSetStandardColormap" "" "@DEF@" -.sM -.FD 0 -XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XStandardColormap *\fIcolormap\fP\^; -.br - Atom \fIproperty\fP\^; /* RGB_BEST_MAP, etc. */ -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XSetStandardColormap -function usually is only used by window or session managers. -.LP -.PN XSetStandardColormap -can generate -.PN BadAlloc , -.PN BadAtom , -.PN BadDrawable , -and -.PN BadWindow -errors. -.SH -Parsing Window Geometry -.LP -To parse window geometry given a user-specified position -and a default position, use -.PN XGeometry . -This function has been superseded by -.PN XWMGeometry . -.IN "Window" "determining location" -.IN "XGeometry" "" "@DEF@" -.sM -.FD 0 -int XGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIposition\fP\^, \fIdefault_position\fP\^, \fIbwidth\fP\^, \fIfwidth\fP\^, \fIfheight\fP\^, \fIxadder\fP\^, -.br - \fIyadder\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen\fP\^; -.br - char *\fIposition\fP\^, *\fIdefault_position\fP\^; -.br - unsigned int \fIbwidth\fP\^; -.br - unsigned int \fIfwidth\fP\^, \fIfheight\fP\^; -.br - int \fIxadder\fP\^, \fIyadder\fP\^; -.br - int *\fIx_return\fP\^, *\fIy_return\fP\^; -.br - int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen\fP 1i -Specifies the screen. -.IP \fIposition\fP 1i -.br -.ns -.IP \fIdefault_position\fP 1i -Specify the geometry specifications. -.IP \fIbwidth\fP 1i -Specifies the border width. -.IP \fIfheight\fP 1i -.br -.ns -.IP \fIfwidth\fP 1i -Specify the font height and width in pixels (increment size). -.IP \fIxadder\fP 1i -.br -.ns -.IP \fIyadder\fP 1i -Specify additional interior padding needed in the window. -.IP \fIx_return\fP 1i -.br -.ns -.IP \fIy_return\fP 1i -Return the x and y offsets. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height determined. -.LP -.eM -You pass in the border width (bwidth), -size of the increments fwidth and fheight -(typically font width and height), -and any additional interior space (xadder and yadder) -to make it easy to compute the resulting size. -The -.PN XGeometry -function returns the position the window should be placed given a position and -a default position. -.PN XGeometry -determines the placement of -a window using a geometry specification as specified by -.PN XParseGeometry -and the additional information about the window. -Given a fully qualified default geometry specification and -an incomplete geometry specification, -.PN XParseGeometry -returns a bitmask value as defined above in the -.PN XParseGeometry -call, -by using the position argument. -.LP -The returned width and height will be the width and height specified -by default_position as overridden by any user-specified position. -They are not affected by fwidth, fheight, xadder, or yadder. -The x and y coordinates are computed by using the border width, -the screen width and height, padding as specified by xadder and yadder, -and the fheight and fwidth times the width and height from the -geometry specifications. -.SH -Getting the X Environment Defaults -.LP -The -.PN XGetDefault -function provides a primitive interface to the resource manager facilities -discussed in chapter 15. -It is only useful in very simple applications. -.LP -.sp -.IN "XGetDefault" "" "@DEF@" -.sM -.FD 0 -char *XGetDefault\^(\^\fIdisplay\fP, \fIprogram\fP\^, \fIoption\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIprogram\fP\^; -.br - char *\fIoption\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprogram\fP 1i -Specifies the program name for the Xlib defaults (usually argv[0] -of the main program). -.IP \fIoption\fP 1i -Specifies the option name. -.LP -.eM -The -.PN XGetDefault -function returns the value of the resource \fIprog\fP.\fIoption\fP, -where \fIprog\fP is the program argument with the directory prefix removed -and \fIoption\fP must be a single component. -Note that multilevel resources cannot be used with -.PN XGetDefault . -The class "Program.Name" is always used for the resource lookup. -If the specified option name does not exist for this program, -.PN XGetDefault -returns NULL. -The strings returned by -.PN XGetDefault -are owned by Xlib and should not be modified or freed by the client. -.LP -If a database has been set with -.PN XrmSetDatabase , -that database is used for the lookup. -Otherwise, a database is created -and is set in the display (as if by calling -.PN XrmSetDatabase ). -The database is created in the current locale. -To create a database, -.PN XGetDefault -uses resources from the RESOURCE_MANAGER property on the root -window of screen zero. -If no such property exists, -a resource file in the user's home directory is used. -On a POSIX-conformant system, -this file is -.PN "$HOME/.Xdefaults" . -.IN "Files" "$HOME/.Xdefaults" -After loading these defaults, -.PN XGetDefault -merges additional defaults specified by the XENVIRONMENT -environment variable. -If XENVIRONMENT is defined, -it contains a full path name for the additional resource file. -If XENVIRONMENT is not defined, -.PN XGetDefault -looks for -.PN "$HOME/.Xdefaults-\fIname\fP" , -where \fIname\fP specifies the name of the machine on which the application -is running. -.SH -X Version 10 Compatibility Functions -.LP -You can use the X Version 10 compatibility functions to: -.IP \(bu 5 -Draw and fill polygons and curves -.IP \(bu 5 -Associate user data with a value -.SH -Drawing and Filling Polygons and Curves -.LP -Xlib provides functions that you can use to draw or fill -arbitrary polygons or curves. -These functions are provided mainly for compatibility with X Version 10 -and have no server support. -That is, they call other Xlib functions, not the server directly. -Thus, if you just have straight lines to draw, using -.PN XDrawLines -.IN "XDrawLines" -or -.PN XDrawSegments -.IN "XDrawSegments" -is much faster. -.LP -The functions discussed here provide all the functionality of the -X Version 10 functions -.PN XDraw , -.IN "X10 compatibility" "XDraw" -.PN XDrawFilled , -.IN "X10 compatibility" "XDrawFilled" -.PN XDrawPatterned , -.IN "X10 compatibility" "XDrawPatterned" -.PN XDrawDashed , -.IN "X10 compatibility" "XDrawDashed" -and -.PN XDrawTiled . -.IN "X10 compatibility" "XDrawTiled" -They are as compatible as possible given X Version 11's new line-drawing -functions. -One thing to note, however, is that -.PN VertexDrawLastPoint -is no longer supported. -Also, the error status returned is the opposite of what it was under -X Version 10 (this is the X Version 11 standard error status). -.PN XAppendVertex -and -.PN XClearVertexFlag -from X Version 10 also are not supported. -.LP -Just how the graphics context you use is set up actually -determines whether you get dashes or not, and so on. -Lines are properly joined if they connect and include -the closing of a closed figure (see -.PN XDrawLines ). -The functions discussed here fail (return zero) only if they run out of memory -or are passed a -.PN Vertex -list that has a -.PN Vertex -with -.PN VertexStartClosed -set that is not followed by a -.PN Vertex -with -.PN VertexEndClosed -set. -.LP -.sp -To achieve the effects of the X Version 10 -.PN XDraw , -.IN "X10 compatibility" "XDraw" -.PN XDrawDashed , -.IN "X10 compatibility" "XDrawDashed" -and -.PN XDrawPatterned , -.IN "X10 compatibility" "XDrawPatterned" -use -.PN XDraw . -.IN "XDraw" "" "@DEF@" -.sM -.FD 0 -#include <X11/X10.h> - -Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - Vertex *\fIvlist\fP\^; -.br - int \fIvcount\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIvlist\fP 1i -Specifies a pointer to the list of vertices that indicate what to draw. -.IP \fIvcount\fP 1i -Specifies how many vertices are in vlist. -.LP -.eM -The -.PN XDraw -function draws an arbitrary polygon or curve. -The figure drawn is defined by the specified list of vertices (vlist). -The points are connected by lines as specified in the flags in the -vertex structure. -.LP -Each Vertex, as defined in -.hN X11/X10.h , -is a structure with the following members: -.LP -.IN "Vertex" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 1.5i -.ta .5i 1.5i -typedef struct _Vertex { - short x,y; - unsigned short flags; -} Vertex; -.De -.LP -.eM -The x and y members are the coordinates of the vertex -that are relative to either the upper left inside corner of the drawable -(if -.PN VertexRelative -is zero) or the previous vertex (if -.PN VertexRelative -is one). -.LP -The flags, as defined in -.hN X11/X10.h , -are as follows: -.IN "VertexRelative" "" "@DEF@" -.IN "VertexDontDraw" "" "@DEF@" -.IN "VertexCurved" "" "@DEF@" -.IN "VertexStartClosed" "" "@DEF@" -.IN "VertexEndClosed" "" "@DEF@" -.sM -.TS -l l l. -T{ -.PN VertexRelative -T} T{ -0x0001 -T} T{ -/* else absolute */ -T} -T{ -.PN VertexDontDraw -T} T{ -0x0002 -T} T{ -/* else draw */ -T} -T{ -.PN VertexCurved -T} T{ -0x0004 -T} T{ -/* else straight */ -T} -T{ -.PN VertexStartClosed -T} T{ -0x0008 -T} T{ -/* else not */ -T} -T{ -.PN VertexEndClosed -T} T{ -0x0010 -T} T{ -/* else not */ -T} -.TE -.LP -.eM -.IP \(bu 5 -If -.PN VertexRelative -is not set, -the coordinates are absolute (that is, relative to the drawable's origin). -The first vertex must be an absolute vertex. -.IP \(bu 5 -If -.PN VertexDontDraw -is one, -no line or curve is drawn from the previous vertex to this one. -This is analogous to picking up the pen and moving to another place -before drawing another line. -.IP \(bu 5 -If -.PN VertexCurved -is one, -a spline algorithm is used to draw a smooth curve from the previous vertex -through this one to the next vertex. -Otherwise, a straight line is drawn from the previous vertex to this one. -It makes sense to set -.PN VertexCurved -to one only if a previous and next vertex are both defined -(either explicitly in the array or through the definition of a closed -curve). -.IP \(bu 5 -It is permissible for -.PN VertexDontDraw -bits and -.PN VertexCurved -bits both to be one. -This is useful if you want to define the previous point for the smooth curve -but do not want an actual curve drawing to start until this point. -.IP \(bu 5 -If -.PN VertexStartClosed -is one, -then this point marks the beginning of a closed curve. -This vertex must be followed later in the array by another vertex -whose effective coordinates are identical -and that has a -.PN VertexEndClosed -bit of one. -The points in between form a cycle to determine predecessor -and successor vertices for the spline algorithm. -.LP -This function uses these GC components: -function, plane-mask, line-width, line-style, cap-style, join-style, -fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and -clip-mask. -It also uses these GC mode-dependent components: -foreground, background, tile, stipple, -tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list. -.LP -.sp -To achieve the effects of the X Version 10 -.PN XDrawTiled -.IN "X10 compatibility" "XDrawTiled" -and -.PN XDrawFilled , -.IN "X10 compatibility" "XDrawFilled" -use -.PN XDrawFilled . -.IN "XDrawFilled" "" "@DEF@" -.sM -.FD 0 -#include <X11/X10.h> - -Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - Vertex *\fIvlist\fP\^; -.br - int \fIvcount\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIvlist\fP 1i -Specifies a pointer to the list of vertices that indicate what to draw. -.IP \fIvcount\fP 1i -Specifies how many vertices are in vlist. -.LP -.eM -The -.PN XDrawFilled -function draws arbitrary polygons or curves and then fills them. -.LP -This function uses these GC components: -function, plane-mask, line-width, line-style, cap-style, join-style, -fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and -clip-mask. -It also uses these GC mode-dependent components: -foreground, background, tile, stipple, -tile-stipple-x-origin, tile-stipple-y-origin, -dash-offset, dash-list, fill-style, and fill-rule. -.SH -Associating User Data with a Value -.LP -These functions have been superseded by the context management functions -(see section 16.10). -It is often necessary to associate arbitrary information with resource IDs. -Xlib provides the -.PN XAssocTable -functions that you can use to make such an association. -.IN "Hash Lookup" -.IN "Window" "IDs" -.IN "Resource IDs" -Application programs often need to be able to easily refer to -their own data structures when an event arrives. -The -.PN XAssocTable -system provides users of the X library with a method -for associating their own data structures with X resources -.Pn ( Pixmaps , -.PN Fonts , -.PN Windows , -and so on). -.LP -An -.PN XAssocTable -can be used to type X resources. -For example, the user -may want to have three or four types of windows, -each with different properties. -This can be accomplished by associating each X window ID -with a pointer to a window property data structure defined by the -user. -A generic type has been defined in the X library for resource IDs. -It is called an XID. -.LP -There are a few guidelines that should be observed when using an -.PN XAssocTable : -.IP \(bu 5 -All XIDs are relative to the specified display. -.IP \(bu 5 -Because of the hashing scheme used by the association mechanism, -the following rules for determining the size of a -.PN XAssocTable -should be followed. -Associations will be made and looked up more -efficiently if the table size (number of buckets in the hashing -system) is a power of two and if there are not more than 8 XIDs per -bucket. -.LP -.sp -To return a pointer to a new -.PN XAssocTable , -use -.PN XCreateAssocTable . -.IN "XCreateAssocTable" "" "@DEF@" -.sM -.FD 0 -XAssocTable *XCreateAssocTable\^(\^\fIsize\fP\^) -.br - int \fIsize\fP\^; -.FN -.IP \fIsize\fP 1i -Specifies the number of buckets in the hash system of -.PN XAssocTable . -.LP -.eM -The size argument specifies the number of buckets in the -hash system of -.PN XAssocTable . -For reasons of efficiency the number of buckets -should be a power of two. -Some size suggestions might be: use 32 buckets per 100 objects, -and a reasonable maximum number of objects per buckets is 8. -If an error allocating memory for the -.PN XAssocTable -occurs, -a NULL pointer is returned. -.LP -.sp -To create an entry in a given -.PN XAssocTable , -use -.PN XMakeAssoc . -.IN "XMakeAssoc" "" "@DEF@" -.sM -.FD 0 -XMakeAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^, \fIdata\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XAssocTable *\fItable\fP\^; -.br - XID \fIx_id\fP\^; -.br - char *\fIdata\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItable\fP 1i -Specifies the assoc table. -.IP \fIx_id\fP 1i -Specifies the X resource ID. -.IP \fIdata\fP 1i -Specifies the data to be associated with the X resource ID. -.LP -.eM -The -.PN XMakeAssoc -function inserts data into an -.PN XAssocTable -keyed on an XID. -Data is inserted into the table only once. -Redundant inserts are ignored. -The queue in each association bucket is sorted from the lowest XID to -the highest XID. -.LP -.sp -To obtain data from a given -.PN XAssocTable , -use -.PN XLookUpAssoc . -.IN "XLookUpAssoc" "" "@DEF@" -.sM -.FD 0 -char *XLookUpAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XAssocTable *\fItable\fP\^; -.br - XID \fIx_id\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItable\fP 1i -Specifies the assoc table. -.IP \fIx_id\fP 1i -Specifies the X resource ID. -.LP -.eM -The -.PN XLookUpAssoc -function retrieves the data stored in an -.PN XAssocTable -by its XID. -If an appropriately matching XID can be found in the table, -.PN XLookUpAssoc -returns the data associated with it. -If the x_id cannot be found in the table, -it returns NULL. -.LP -.sp -To delete an entry from a given -.PN XAssocTable , -use -.PN XDeleteAssoc . -.IN "XDeleteAssoc" "" "@DEF@" -.sM -.FD 0 -XDeleteAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XAssocTable *\fItable\fP\^; -.br - XID \fIx_id\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItable\fP 1i -Specifies the assoc table. -.IP \fIx_id\fP 1i -Specifies the X resource ID. -.LP -.eM -The -.PN XDeleteAssoc -function deletes an association in an -.PN XAssocTable -keyed on its XID. -Redundant deletes (and deletes of nonexistent XIDs) are ignored. -Deleting associations in no way impairs the performance of an -.PN XAssocTable . -.LP -.sp -To free the memory associated with a given -.PN XAssocTable , -use -.PN XDestroyAssocTable . -.IN "XDestroyAssocTable" "" "@DEF@" -.sM -.FD 0 -XDestroyAssocTable\^(\^\fItable\fP\^) -.br - XAssocTable *\fItable\fP\^; -.FN -.IP \fItable\fP 1i -Specifies the assoc table. -.LP -.eM -.bp diff --git a/libX11/specs/libX11/AppD.xml b/libX11/specs/libX11/AppD.xml new file mode 100644 index 000000000..57d60a219 --- /dev/null +++ b/libX11/specs/libX11/AppD.xml @@ -0,0 +1,1900 @@ +<appendix id="compatibility_functions">
+<title>Compatibility Functions</title>
+<para>
+<!-- .LP -->
+The X Version 11 and X Version 10 functions discussed in this appendix
+are obsolete, have been superseded by newer X Version 11 functions,
+and are maintained for compatibility reasons only.
+<!-- .SH -->
+X Version 11 Compatibility Functions
+</para>
+<para>
+<!-- .LP -->
+You can use the X Version 11 compatibility functions to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Set standard properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and get window sizing hints
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and get an
+<function>XStandardColormap</function>
+structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Parse window geometry
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Get X environment defaults
+<!-- .SH -->
+Setting Standard Properties
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To specify a minimum set of properties describing the simplest application,
+use
+<function>XSetStandardProperties</function>.
+This function has been superseded by
+<function>XSetWMProperties</function>
+and sets all or portions of the
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND,
+and WM_NORMAL_HINTS properties.
+<indexterm significance="preferred"><primary>XSetStandardProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetStandardProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *window_name</parameter></paramdef>
+ <paramdef>char<parameter> *icon_name</parameter></paramdef>
+ <paramdef>Pixmap<parameter> icon_pixmap</parameter></paramdef>
+ <paramdef>char<parameter> **argv</parameter></paramdef>
+ <paramdef>int<parameter> argc</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_pixmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the bitmap that is to be used for the icon or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetStandardProperties</function>
+function provides a means by which simple applications set the
+most essential properties with a single call.
+<function>XSetStandardProperties</function>
+should be used to give a window manager some information about
+your program's preferences.
+It should not be used by applications that need
+to communicate more information than is possible with
+<function>XSetStandardProperties</function>.
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetStandardProperties</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+<!-- .SH -->
+</para>
+<para>
+Setting and Getting Window Sizing Hints
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set or get window sizing hints.
+The functions discussed in this section use the flags and the
+<function>XSizeHints </function>
+structure, as defined in the
+<!-- .hN X11/Xutil.h -->
+header file and use the WM_NORMAL_HINTS property.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the size hints for a given window in its normal state, use
+<function>XSetNormalHints</function>.
+This function has been superseded by
+<function>XSetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XSetNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetNormalHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetNormalHints</function>
+function sets the size hints structure for the specified window.
+Applications use
+<function>XSetNormalHints</function>
+to inform the window manager of the size
+or position desirable for that window.
+In addition,
+an application that wants to move or resize itself should call
+<function>XSetNormalHints</function>
+and specify its new desired location and size
+as well as making direct Xlib calls to move or resize.
+This is because window managers may ignore redirected
+configure requests, but they pay attention to property changes.
+</para>
+<para>
+<!-- .LP -->
+To set size hints,
+an application not only must assign values to the appropriate members
+in the hints structure but also must set the flags member of the structure
+to indicate which information is present and where it came from.
+A call to
+<function>XSetNormalHints</function>
+is meaningless, unless the flags member is set to indicate which members of
+the structure have been assigned values.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetNormalHints</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the size hints for a window in its normal state, use
+<function>XGetNormalHints</function>.
+This function has been superseded by
+<function>XGetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XGetNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetNormalHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetNormalHints</function>
+function returns the size hints for a window in its normal state.
+It returns a nonzero status if it succeeds or zero if
+the application specified no normal size hints for this window.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetNormalHints</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The next two functions set and read the WM_ZOOM_HINTS property.
+</para>
+<para>
+<!-- .LP -->
+To set the zoom hints for a window, use
+<function>XSetZoomHints</function>.
+This function is no longer supported by the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+<indexterm significance="preferred"><primary>XSetZoomHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetZoomHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *zhints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>zhints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the zoom hints.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Many window managers think of windows in one of three states:
+iconic, normal, or zoomed.
+The
+<function>XSetZoomHints</function>
+function provides the window manager with information for the window in the
+zoomed state.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetZoomHints</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read the zoom hints for a window, use
+<function>XGetZoomHints</function>.
+This function is no longer supported by the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+<indexterm significance="preferred"><primary>XGetZoomHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetZoomHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *zhints_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>zhints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the zoom hints.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetZoomHints</function>
+function returns the size hints for a window in its zoomed state.
+It returns a nonzero status if it succeeds or zero if
+the application specified no zoom size hints for this window.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetZoomHints</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the value of any property of type WM_SIZE_HINTS, use
+<function>XSetSizeHints</function>.
+This function has been superseded by
+<function>XSetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XSetSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetSizeHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the size hints.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetSizeHints</function>
+function sets the
+<function>XSizeHints</function>
+structure for the named property and the specified window.
+This is used by
+<function>XSetNormalHints</function>
+and
+<function>XSetZoomHints</function>
+and can be used to set the value of any property of type WM_SIZE_HINTS.
+Thus, it may be useful if other properties of that type get defined.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetSizeHints</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read the value of any property of type WM_SIZE_HINTS, use
+<function>XGetSizeHints</function>.
+This function has been superseded by
+<function>XGetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XGetSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetSizeHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the size hints.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetSizeHints</function>
+function returns the
+<function>XSizeHints</function>
+structure for the named property and the specified window.
+This is used by
+<function>XGetNormalHints</function>
+and
+<function>XGetZoomHints</function>.
+It also can be used to retrieve the value of any property of type
+WM_SIZE_HINTS.
+Thus, it may be useful if other properties of that type get defined.
+<function>XGetSizeHints</function>
+returns a nonzero status if a size hint was defined
+or zero otherwise.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetSizeHints</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow </function>
+errors.
+<!-- .SH -->
+Getting and Setting an XStandardColormap Structure
+</para>
+<para>
+<!-- .LP -->
+To get the
+<function>XStandardColormap </function>
+structure associated with one of the described atoms, use
+<function>XGetStandardColormap</function>.
+This function has been superseded by
+<function>XGetRGBColormap</function>.
+<indexterm significance="preferred"><primary>XGetStandardColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetStandardColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XStandardColormap<parameter> *colormap_return</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the colormap associated with the specified atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetStandardColormap</function>
+function returns the colormap definition associated with the atom supplied
+as the property argument.
+<function>XGetStandardColormap</function>
+returns a nonzero status if successful and zero otherwise.
+For example,
+to fetch the standard
+<function>GrayScale</function>
+colormap for a display,
+you use
+<function>XGetStandardColormap</function>
+with the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+See section 14.3 for the semantics of standard colormaps.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetStandardColormap</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a standard colormap, use
+<function>XSetStandardColormap</function>.
+This function has been superseded by
+<function>XSetRGBColormap</function>.
+<indexterm significance="preferred"><primary>XSetStandardColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetStandardColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XStandardColormap<parameter> *colormap</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetStandardColormap</function>
+function usually is only used by window or session managers.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetStandardColormap</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+<function>BadDrawable</function>,
+and
+<function>BadWindow </function>
+errors.
+<!-- .SH -->
+Parsing Window Geometry
+</para>
+<para>
+<!-- .LP -->
+To parse window geometry given a user-specified position
+and a default position, use
+<function>XGeometry</function>.
+This function has been superseded by
+<function>XWMGeometry</function>.
+<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGeometry</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen</parameter></paramdef>
+ <paramdef>char*position,<parameter> *default_position</parameter></paramdef>
+ <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>
+ <paramdef>unsignedintfwidth,<parameter> fheight</parameter></paramdef>
+ <paramdef>intxadder,<parameter> yadder</parameter></paramdef>
+ <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+ <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default_position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the geometry specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bwidth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the border width.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fheight</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fwidth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the font height and width in pixels (increment size).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>xadder</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>yadder</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify additional interior padding needed in the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the x and y offsets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height determined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+You pass in the border width (bwidth),
+size of the increments fwidth and fheight
+(typically font width and height),
+and any additional interior space (xadder and yadder)
+to make it easy to compute the resulting size.
+The
+<function>XGeometry </function>
+function returns the position the window should be placed given a position and
+a default position.
+<function>XGeometry</function>
+determines the placement of
+a window using a geometry specification as specified by
+<function>XParseGeometry </function>
+and the additional information about the window.
+Given a fully qualified default geometry specification and
+an incomplete geometry specification,
+<function>XParseGeometry</function>
+returns a bitmask value as defined above in the
+<function>XParseGeometry</function>
+call,
+by using the position argument.
+</para>
+<para>
+<!-- .LP -->
+The returned width and height will be the width and height specified
+by default_position as overridden by any user-specified position.
+They are not affected by fwidth, fheight, xadder, or yadder.
+The x and y coordinates are computed by using the border width,
+the screen width and height, padding as specified by xadder and yadder,
+and the fheight and fwidth times the width and height from the
+geometry specifications.
+<!-- .SH -->
+</para>
+<para>
+Getting the X Environment Defaults
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XGetDefault</function>
+function provides a primitive interface to the resource manager facilities
+discussed in chapter 15. <!-- xref -->
+It is only useful in very simple applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XGetDefault</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XGetDefault</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *program</parameter></paramdef>
+ <paramdef>char<parameter> *option</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>program</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the program name for the Xlib defaults (usually argv[0]
+of the main program).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>option</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the option name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetDefault</function>
+function returns the value of the resource <emphasis remap='I'>prog</emphasis>.<emphasis remap='I'>option</emphasis>,
+where <emphasis remap='I'>prog</emphasis> is the program argument with the directory prefix removed
+and <emphasis remap='I'>option</emphasis> must be a single component.
+Note that multilevel resources cannot be used with
+<function>XGetDefault</function>.
+The class "Program.Name" is always used for the resource lookup.
+If the specified option name does not exist for this program,
+<function>XGetDefault</function>
+returns NULL.
+The strings returned by
+<function>XGetDefault</function>
+are owned by Xlib and should not be modified or freed by the client.
+</para>
+<para>
+<!-- .LP -->
+If a database has been set with
+<function>XrmSetDatabase</function>,
+that database is used for the lookup.
+Otherwise, a database is created
+and is set in the display (as if by calling
+<function>XrmSetDatabase</function>).
+The database is created in the current locale.
+To create a database,
+<function>XGetDefault</function>
+uses resources from the RESOURCE_MANAGER property on the root
+window of screen zero.
+If no such property exists,
+a resource file in the user's home directory is used.
+On a <acronym>POSIX</acronym>-conformant system,
+this file is
+<function>"$HOME/.Xdefaults"</function>.
+<indexterm><primary>Files</primary><secondary>$HOME/.Xdefaults</secondary></indexterm>
+After loading these defaults,
+<function>XGetDefault</function>
+merges additional defaults specified by the XENVIRONMENT
+environment variable.
+If XENVIRONMENT is defined,
+it contains a full path name for the additional resource file.
+If XENVIRONMENT is not defined,
+<function>XGetDefault</function>
+looks for
+"$HOME/.Xdefaults-<emphasis remap='I'>name</emphasis>" ,
+where <emphasis remap='I'>name</emphasis> specifies the name of the machine on which the application
+is running.
+<!-- .SH -->
+X Version 10 Compatibility Functions
+</para>
+<para>
+<!-- .LP -->
+You can use the X Version 10 compatibility functions to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Draw and fill polygons and curves
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Associate user data with a value
+<!-- .SH -->
+Drawing and Filling Polygons and Curves
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to draw or fill
+arbitrary polygons or curves.
+These functions are provided mainly for compatibility with X Version 10
+and have no server support.
+That is, they call other Xlib functions, not the server directly.
+Thus, if you just have straight lines to draw, using
+<function>XDrawLines </function>
+<indexterm><primary>XDrawLines</primary></indexterm>
+or
+<function>XDrawSegments </function>
+<indexterm><primary>XDrawSegments</primary></indexterm>
+is much faster.
+</para>
+<para>
+<!-- .LP -->
+The functions discussed here provide all the functionality of the
+X Version 10 functions
+<function>XDraw</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>
+<function>XDrawFilled</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>
+<function>XDrawPatterned</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>
+<function>XDrawDashed</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>
+and
+<function>XDrawTiled</function>.
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>
+They are as compatible as possible given X Version 11's new line-drawing
+functions.
+One thing to note, however, is that
+<function>VertexDrawLastPoint </function>
+is no longer supported.
+Also, the error status returned is the opposite of what it was under
+X Version 10 (this is the X Version 11 standard error status).
+<function>XAppendVertex </function>
+and
+<function>XClearVertexFlag </function>
+from X Version 10 also are not supported.
+</para>
+<para>
+<!-- .LP -->
+Just how the graphics context you use is set up actually
+determines whether you get dashes or not, and so on.
+Lines are properly joined if they connect and include
+the closing of a closed figure (see
+<function>XDrawLines</function>).
+The functions discussed here fail (return zero) only if they run out of memory
+or are passed a
+<function>Vertex </function>
+list that has a
+<function>Vertex </function>
+with
+<function>VertexStartClosed</function>
+set that is not followed by a
+<function>Vertex </function>
+with
+<function>VertexEndClosed </function>
+set.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To achieve the effects of the X Version 10
+<function>XDraw</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>
+<function>XDrawDashed</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>
+and
+<function>XDrawPatterned</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>
+use
+<function>XDraw</function>.
+</para>
+
+<para>
+#include <X11/X10.h>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XDraw</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Vertex<parameter> *vlist</parameter></paramdef>
+ <paramdef>int<parameter> vcount</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vlist</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the list of vertices that indicate what to draw.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vcount</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how many vertices are in vlist.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDraw </function>
+function draws an arbitrary polygon or curve.
+The figure drawn is defined by the specified list of vertices (vlist).
+The points are connected by lines as specified in the flags in the
+vertex structure.
+</para>
+<para>
+<!-- .LP -->
+Each Vertex, as defined in
+<!-- .hN X11/X10.h , -->
+is a structure with the following members:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Vertex</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+typedef struct _Vertex {
+ short x,y;
+ unsigned short flags;
+} Vertex;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x and y members are the coordinates of the vertex
+that are relative to either the upper left inside corner of the drawable
+(if
+<function>VertexRelative </function>
+is zero) or the previous vertex (if
+<function>VertexRelative </function>
+is one).
+</para>
+<para>
+<!-- .LP -->
+The flags, as defined in
+<!-- .hN X11/X10.h , -->
+are as follows:
+<indexterm significance="preferred"><primary>VertexRelative</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexDontDraw</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexCurved</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexStartClosed</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexEndClosed</primary></indexterm>
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+VertexRelative 0x0001 /* else absolute */
+VertexDontDraw 0x0002 /* else draw */
+VertexCurved 0x0004 /* else straight */
+VertexStartClosed 0x0008 /* else not */
+VertexEndClosed 0x0010 /* else not */
+</literallayout>
+
+<itemizedlist>
+ <listitem>
+ <para>
+If
+<function>VertexRelative </function>
+is not set,
+the coordinates are absolute (that is, relative to the drawable's origin).
+The first vertex must be an absolute vertex.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If
+<function>VertexDontDraw </function>
+is one,
+no line or curve is drawn from the previous vertex to this one.
+This is analogous to picking up the pen and moving to another place
+before drawing another line.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If
+<function>VertexCurved </function>
+is one,
+a spline algorithm is used to draw a smooth curve from the previous vertex
+through this one to the next vertex.
+Otherwise, a straight line is drawn from the previous vertex to this one.
+It makes sense to set
+<function>VertexCurved </function>
+to one only if a previous and next vertex are both defined
+(either explicitly in the array or through the definition of a closed
+curve).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It is permissible for
+<function>VertexDontDraw </function>
+bits and
+<function>VertexCurved</function>
+bits both to be one.
+This is useful if you want to define the previous point for the smooth curve
+but do not want an actual curve drawing to start until this point.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If
+<function>VertexStartClosed </function>
+is one,
+then this point marks the beginning of a closed curve.
+This vertex must be followed later in the array by another vertex
+whose effective coordinates are identical
+and that has a
+<function>VertexEndClosed </function>
+bit of one.
+The points in between form a cycle to determine predecessor
+and successor vertices for the spline algorithm.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+This function uses these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
+clip-mask.
+It also uses these GC mode-dependent components:
+foreground, background, tile, stipple,
+tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To achieve the effects of the X Version 10
+<function>XDrawTiled </function>
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>
+and
+<function>XDrawFilled</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>
+use
+<function>XDrawFilled</function>.
+</para>
+
+<para>#include <X11/X10.h></para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XDrawFilled</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Vertex<parameter> *vlist</parameter></paramdef>
+ <paramdef>int<parameter> vcount</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vlist</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the list of vertices that indicate what to draw.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vcount</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how many vertices are in vlist.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawFilled </function>
+function draws arbitrary polygons or curves and then fills them.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
+clip-mask.
+It also uses these GC mode-dependent components:
+foreground, background, tile, stipple,
+tile-stipple-x-origin, tile-stipple-y-origin,
+dash-offset, dash-list, fill-style, and fill-rule.
+<!-- .SH -->
+Associating User Data with a Value
+</para>
+<para>
+<!-- .LP -->
+These functions have been superseded by the context management functions
+(see section 16.10).
+It is often necessary to associate arbitrary information with resource IDs.
+Xlib provides the
+<function>XAssocTable </function>
+functions that you can use to make such an association.
+<indexterm><primary>Hash Lookup</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>IDs</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary></indexterm>
+Application programs often need to be able to easily refer to
+their own data structures when an event arrives.
+The
+<function>XAssocTable</function>
+system provides users of the X library with a method
+for associating their own data structures with X resources
+(<function>Pixmaps</function>,
+<function>Fonts</function>,
+<function>Windows</function>,
+and so on).
+</para>
+<para>
+<!-- .LP -->
+An
+<function>XAssocTable</function>
+can be used to type X resources.
+For example, the user
+may want to have three or four types of windows,
+each with different properties.
+This can be accomplished by associating each X window ID
+with a pointer to a window property data structure defined by the
+user.
+A generic type has been defined in the X library for resource IDs.
+It is called an XID.
+</para>
+<para>
+<!-- .LP -->
+There are a few guidelines that should be observed when using an
+<function>XAssocTable :</function>
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+All XIDs are relative to the specified display.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Because of the hashing scheme used by the association mechanism,
+the following rules for determining the size of a
+<function>XAssocTable</function>
+should be followed.
+Associations will be made and looked up more
+efficiently if the table size (number of buckets in the hashing
+system) is a power of two and if there are not more than 8 XIDs per
+bucket.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a pointer to a new
+<function>XAssocTable</function>,
+use
+<function>XCreateAssocTable</function>.
+<indexterm significance="preferred"><primary>XCreateAssocTable</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XAssocTable<function> *XCreateAssocTable</function></funcdef>
+ <paramdef>int<parameter> size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of buckets in the hash system of
+<function>XAssocTable</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The size argument specifies the number of buckets in the
+hash system of
+<function>XAssocTable</function>.
+For reasons of efficiency the number of buckets
+should be a power of two.
+Some size suggestions might be: use 32 buckets per 100 objects,
+and a reasonable maximum number of objects per buckets is 8.
+If an error allocating memory for the
+<function>XAssocTable </function>
+occurs,
+a NULL pointer is returned.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an entry in a given
+<function>XAssocTable</function>,
+use
+<function>XMakeAssoc</function>.
+<indexterm significance="preferred"><primary>XMakeAssoc</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMakeAssoc</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+ <paramdef>XID<parameter> x_id</parameter></paramdef>
+ <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the assoc table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X resource ID.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data to be associated with the X resource ID.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMakeAssoc</function>
+function inserts data into an
+<function>XAssocTable</function>
+keyed on an XID.
+Data is inserted into the table only once.
+Redundant inserts are ignored.
+The queue in each association bucket is sorted from the lowest XID to
+the highest XID.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain data from a given
+<function>XAssocTable</function>,
+use
+<function>XLookUpAssoc</function>.
+<indexterm significance="preferred"><primary>XLookUpAssoc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XLookUpAssoc</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+ <paramdef>XID<parameter> x_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the assoc table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X resource ID.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookUpAssoc</function>
+function retrieves the data stored in an
+<function>XAssocTable</function>
+by its XID.
+If an appropriately matching XID can be found in the table,
+<function>XLookUpAssoc</function>
+returns the data associated with it.
+If the x_id cannot be found in the table,
+it returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry from a given
+<function>XAssocTable</function>,
+use
+<function>XDeleteAssoc</function>.
+<indexterm significance="preferred"><primary>XDeleteAssoc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDeleteAssoc</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+ <paramdef>XID<parameter> x_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the assoc table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X resource ID.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteAssoc</function>
+function deletes an association in an
+<function>XAssocTable</function>
+keyed on its XID.
+Redundant deletes (and deletes of nonexistent XIDs) are ignored.
+Deleting associations in no way impairs the performance of an
+<function>XAssocTable</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free the memory associated with a given
+<function>XAssocTable</function>,
+use
+<function>XDestroyAssocTable</function>.
+</para>
+<indexterm significance="preferred"><primary>XDestroyAssocTable</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDestroyAssocTable</function></funcdef>
+ <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the assoc table.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</appendix>
diff --git a/libX11/specs/libX11/CH01 b/libX11/specs/libX11/CH01.xml index 765e4b5fb..0e86e7496 100644 --- a/libX11/specs/libX11/CH01 +++ b/libX11/specs/libX11/CH01.xml @@ -1,663 +1,825 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -.EH '\fBXlib \- C Library\fP''\fB\*(xV\fP' -.OH '\fBXlib \- C Library\fP''\fB\*(xV\fP' -.EF ''\fB % \fP'' -.OF ''\fB % \fP'' -.hw WM_NORMAL_HINTS -\& -.sp 1 -.ce 3 -\s+1\fBChapter 1\fP\s-1 - -\s+1\fBIntroduction to Xlib\fP\s-1 -.sp 2 -.if \n(GS .nr nh*hl 1 -.nr H1 1 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 1: Introduction to Xlib -.XE -The X Window System is a network-transparent window system -that was designed at MIT. -X display servers run on computers with either monochrome or color -bitmap display hardware. -The server distributes user input to and accepts output requests from various -client programs located either on the same machine or elsewhere in -the network. -Xlib is a C subroutine library that application programs (clients) -use to interface with the window system by means of a stream connection. -Although a client usually runs on the same machine as the X server -it is talking to, this need not be the case. -.LP -\fIXlib \- C Language X Interface\fP is a reference guide to the low-level -C language interface to the X Window System protocol. -It is neither a tutorial nor a user's guide to programming the X Window System. -Rather, it provides a detailed description of each function in the library -as well as a discussion of the related background information. -\fIXlib \- C Language X Interface\fP assumes a basic understanding of a graphics -window system and of the C programming language. -Other higher-level abstractions -(for example, those provided by the toolkits for X) -are built on top of the Xlib library. -For further information about these higher-level libraries, -see the appropriate toolkit documentation. -The \fIX Window System Protocol\fP provides the definitive word on the -behavior of X. -Although additional information appears here, -the protocol document is the ruling document. -.LP -To provide an introduction to X programming, -this chapter discusses: -.IP \(bu 5 -Overview of the X Window System -.IP \(bu 5 -Errors -.IP \(bu 5 -Standard header files -.IP \(bu 5 -Generic values and types -.IP \(bu 5 -Naming and argument conventions within Xlib -.IP \(bu 5 -Programming considerations -.IP \(bu 5 -Character sets and encodings -.IP \(bu 5 -Formatting conventions -.NH 2 -Overview of the X Window System -.XS -\*(SN Overview of the X Window System -.XE -.LP -Some of the terms used in this book are unique to X, -and other terms that are common to other window systems -have different meanings in X. -You may find it helpful to refer to the glossary, -which is located at the end of the book. -.LP -The X Window System supports one or more screens containing -overlapping windows or subwindows. -A screen is a physical monitor and hardware -that can be color, grayscale, or monochrome. -There can be multiple screens for each display or workstation. -A single X server can provide display services for any number of screens. -A set of screens for a single user with one keyboard and one pointer -(usually a mouse) is called a display. -.LP -.IN "Screen" -All the windows in an X server are arranged in strict hierarchies. -At the top of each hierarchy is a root window, -which covers each of the display screens. -Each root window is partially or completely covered by child windows. -All windows, except for root windows, have parents. -There is usually at least one window for each application program. -.IN "Child window" -.IN "Parent Window" -Child windows may in turn have their own children. -In this way, -an application program can create an arbitrarily deep tree -on each screen. -X provides graphics, text, and raster operations for windows. -.LP -A child window can be larger than its parent. -That is, part or all of -the child window can extend beyond the boundaries of the parent, -but all output to a window is clipped by its parent. -.IN "Stacking order" -If several children of a window have overlapping locations, -one of the children is considered to be on top of or raised over the -others, thus obscuring them. -Output to areas covered by other windows is suppressed by the window -system unless the window has backing store. -If a window is obscured by a second window, -the second window obscures only those ancestors of the second window -that are also ancestors of the first window. -.LP -.IN "Window" "" "@DEF@" -A window has a border zero or more pixels in width, which can -be any pattern (pixmap) or solid color you like. -A window usually but not always has a background pattern, -which will be repainted by the window system when uncovered. -Child windows obscure their parents, -and graphic operations in the parent window usually -are clipped by the children. -.LP -Each window and pixmap has its own coordinate system. -The coordinate system has the X axis horizontal and the Y axis vertical -with the origin [0, 0] at the upper-left corner. -Coordinates are integral, -in terms of pixels, -and coincide with pixel centers. -For a window, -the origin is inside the border at the inside, upper-left corner. -.LP -X does not guarantee to preserve the contents of windows. -When part or all of a window is hidden and then brought back onto the screen, -its contents may be lost. -The server then sends the client program an -.PN Expose -event to notify it that part or all of the window needs to be repainted. -Programs must be prepared to regenerate the contents of windows on demand. -.LP -.IN "Pixmap" -.IN "Drawable" -.IN "Tile" -.IN "Bitmap" -X also provides off-screen storage of graphics objects, -called pixmaps. -Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. -Pixmaps can be used in most graphics functions interchangeably with -windows and are used in various graphics operations to define patterns or tiles. -Windows and pixmaps together are referred to as drawables. -.LP -Most of the functions in Xlib just add requests to an output buffer. -These requests later execute asynchronously on the X server. -Functions that return values of information stored in -the server do not return (that is, they block) -until an explicit reply is received or an error occurs. -You can provide an error handler, -which will be called when the error is reported. -.LP -.IN "XSync" -If a client does not want a request to execute asynchronously, -it can follow the request with a call to -.PN XSync , -which blocks until all previously buffered -asynchronous events have been sent and acted on. -As an important side effect, -the output buffer in Xlib is always flushed by a call to any function -that returns a value from the server or waits for input. -.LP -.IN "Resource IDs" -.IN "Resource IDs" "Window" -.IN "Resource IDs" "Font" -.IN "Resource IDs" "Pixmap" -.IN "Resource IDs" "Cursor" -.IN "Resource IDs" "GContext" -Many Xlib functions will return an integer resource ID, -which allows you to refer to objects stored on the X server. -These can be of type -.PN Window , -.PN Font , -.PN Pixmap , -.PN Colormap , -.PN Cursor , -and -.PN GContext , -as defined in the file -.hN X11/X.h . -These resources are created by requests and are destroyed -(or freed) by requests or when connections are closed. -Most of these resources are potentially sharable between -applications, and in fact, windows are manipulated explicitly by -window manager programs. -Fonts and cursors are shared automatically across multiple screens. -Fonts are loaded and unloaded as needed and are shared by multiple clients. -Fonts are often cached in the server. -Xlib provides no support for sharing graphics contexts between applications. -.LP -.IN "Event" -Client programs are informed of events. -Events may either be side effects of a request (for example, restacking windows -generates -.PN Expose -events) or completely asynchronous (for example, from the keyboard). -A client program asks to be informed of events. -Because other applications can send events to your application, -programs must be prepared to handle (or ignore) events of all types. -.LP -Input events (for example, a key pressed or the pointer moved) -arrive asynchronously from the server and are queued until they are -requested by an explicit call (for example, -.PN XNextEvent -or -.PN XWindowEvent ). -In addition, some library -functions (for example, -.PN XRaiseWindow ) -generate -.PN Expose -and -.PN ConfigureRequest -events. -These events also arrive asynchronously, but the client may -.IN "XSync" -wish to explicitly wait for them by calling -.PN XSync -after calling a function that can cause the server to generate events. -.NH 2 -Errors -.XS -\*(SN Errors -.XE -.LP -Some functions return -.PN Status , -an integer error indication. -If the function fails, it returns a zero. -If the function returns a status of zero, -it has not updated the return arguments. -.IN "Status" -Because C does not provide multiple return values, -many functions must return their results by writing into client-passed storage. -.IN "Error" "handling" -By default, errors are handled either by a standard library function -or by one that you provide. -Functions that return pointers to strings return NULL pointers if -the string does not exist. -.LP -The X server reports protocol errors at the time that it detects them. -If more than one error could be generated for a given request, -the server can report any of them. -.LP -Because Xlib usually does not transmit requests to the server immediately -(that is, it buffers them), errors can be reported much later than they -actually occur. -For debugging purposes, however, -Xlib provides a mechanism for forcing synchronous behavior -(see section 11.8.1). -When synchronization is enabled, -errors are reported as they are generated. -.LP -When Xlib detects an error, -it calls an error handler, -which your program can provide. -If you do not provide an error handler, -the error is printed, and your program terminates. -.NH 2 -Standard Header Files -.XS -\*(SN Standard Header Files -.XE -.LP -The following include files are part of the Xlib standard: -.IP \(bu 5 -.hN X11/Xlib.h -.IP -This is the main header file for Xlib. -The majority of all Xlib symbols are declared by including this file. -This file also contains the preprocessor symbol -.PN XlibSpecificationRelease . -.IN "XlibSpecificationRelease" "" "@DEF@" -This symbol is defined to have the 6 in this release of the standard. -(Release 5 of Xlib was the first release to have this symbol.) -.IP \(bu 5 -.hN X11/X.h -.IP -This file declares types and constants for the X protocol that are -to be used by applications. -It is included automatically from -.hN X11/Xlib.h , -so application code should never need to reference this file directly. -.IP \(bu 5 -.hN X11/Xcms.h -.IP -This file contains symbols for much of the color management facilities -described in chapter 6. -All functions, types, and symbols with the prefix ``Xcms'', -plus the Color Conversion Contexts macros, are declared in this file. -.hN X11/Xlib.h -must be included before including this file. -.IP \(bu 5 -.hN X11/Xutil.h -.IP -This file declares various functions, types, and symbols used for -inter-client communication and application utility functions, -which are described in chapters 14 and 16. -.hN X11/Xlib.h -must be included before including this file. -.IP \(bu 5 -.hN X11/Xresource.h -.IP -This file declares all functions, types, and symbols for the -resource manager facilities, which are described in chapter 15. -.hN X11/Xlib.h -must be included before including this file. -.IP \(bu 5 -.hN X11/Xatom.h -.IP -This file declares all predefined atoms, -which are symbols with the prefix ``XA_''. -.IP \(bu 5 -.hN X11/cursorfont.h -.IP -This file declares the cursor symbols for the standard cursor font, -which are listed in appendix B. -All cursor symbols have the prefix ``XC_''. -.IP \(bu 5 -.hN X11/keysymdef.h -.IP -This file declares all standard KeySym values, -which are symbols with the prefix ``XK_''. -The KeySyms are arranged in groups, and a preprocessor symbol controls -inclusion of each group. The preprocessor symbol must be defined -prior to inclusion of the file to obtain the associated values. -The preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270, -XK_LATIN1, XK_LATIN2, -XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK, -XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW, -XK_THAI, and XK_KOREAN. -.IP \(bu 5 -.hN X11/keysym.h -.IP -This file defines the preprocessor symbols -XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, -XK_LATIN4, and XK_GREEK -and then includes -.hN X11/keysymdef.h . -.IP \(bu 5 -.hN X11/Xlibint.h -.IP -This file declares all the functions, types, and symbols used for -extensions, which are described in appendix C. -This file automatically includes -.hN X11/Xlib.h . -.IP \(bu 5 -.hN X11/Xproto.h -.IP -This file declares types and symbols for the basic X protocol, -for use in implementing extensions. -It is included automatically from -.hN X11/Xlibint.h , -so application and extension code should never need to -reference this file directly. -.IP \(bu 5 -.hN X11/Xprotostr.h -.IP -This file declares types and symbols for the basic X protocol, -for use in implementing extensions. -It is included automatically from -.hN X11/Xproto.h , -so application and extension code should never need to -reference this file directly. -.IP \(bu 5 -.hN X11/X10.h -.IP -This file declares all the functions, types, and symbols used for the -X10 compatibility functions, which are described in appendix D. -.NH 2 -Generic Values and Types -.XS -\*(SN Generic Values and Types -.XE -.LP -The following symbols are defined by Xlib and used throughout the manual: -.IN "Bool" "" "@DEF@" -.IN "True" "" "@DEF@" -.IN "False" "" "@DEF@" -.IP \(bu 5 -Xlib defines the type -.PN Bool -and the Boolean values -.PN True -and -.PN False . -.IN "None" "" "@DEF@" -.IP \(bu 5 -.PN None -is the universal null resource ID or atom. -.IN "XID" "" "@DEF@" -.IP \(bu 5 -The type -.PN XID -is used for generic resource IDs. -.IN "XPointer" "" "@DEF@" -.IP \(bu 5 -The type -.PN XPointer -is defined to be char\^* and is used as a generic opaque pointer to data. -.NH 2 -Naming and Argument Conventions within Xlib -.XS -\*(SN Naming and Argument Conventions within Xlib -.XE -.LP -Xlib follows a number of conventions for the naming and syntax of the functions. -Given that you remember what information the function requires, -these conventions are intended to make the syntax of the functions more -predictable. -.LP -The major naming conventions are: -.IP \(bu 5 -To differentiate the X symbols from the other symbols, -the library uses mixed case for external symbols. -It leaves lowercase for variables and all uppercase for user macros, -as per existing convention. -.IP \(bu 5 -All Xlib functions begin with a capital X. -.IP \(bu 5 -The beginnings of all function names and symbols are capitalized. -.IP \(bu 5 -All user-visible data structures begin with a capital X. -More generally, -anything that a user might dereference begins with a capital X. -.IP \(bu 5 -Macros and other symbols do not begin with a capital X. -To distinguish them from all user symbols, -each word in the macro is capitalized. -.IP \(bu 5 -All elements of or variables in a data structure are in lowercase. -Compound words, where needed, are constructed with underscores (\^_\^). -.IP \(bu 5 -The display argument, where used, is always first in the argument list. -.IP \(bu 5 -All resource objects, where used, occur at the beginning of the argument list -immediately after the display argument. -.IP \(bu 5 -When a graphics context is present together with -another type of resource (most commonly, a drawable), the -graphics context occurs in the argument list after the other -resource. -Drawables outrank all other resources. -.IP \(bu 5 -Source arguments always precede the destination arguments in the argument list. -.IP \(bu 5 -The x argument always precedes the y argument in the argument list. -.IP \(bu 5 -The width argument always precedes the height argument in the argument list. -.IP \(bu 5 -Where the x, y, width, and height arguments are used together, -the x and y arguments always precede the width and height arguments. -.IP \(bu 5 -Where a mask is accompanied with a structure, -the mask always precedes the pointer to the structure in the argument list. -.NH 2 -Programming Considerations -.XS -\*(SN Programming Considerations -.XE -.LP -The major programming considerations are: -.IP \(bu 5 -Coordinates and sizes in X are actually 16-bit quantities. -This decision was made to minimize the bandwidth required for a -given level of performance. -Coordinates usually are declared as an -.PN int -in the interface. -Values larger than 16 bits are truncated silently. -Sizes (width and height) are declared as unsigned quantities. -.IP \(bu 5 -Keyboards are the greatest variable between different -manufacturers' workstations. -If you want your program to be portable, -you should be particularly conservative here. -.IP \(bu 5 -Many display systems have limited amounts of off-screen memory. -If you can, you should minimize use of pixmaps and backing -store. -.IP \(bu 5 -The user should have control of his screen real estate. -Therefore, you should write your applications to react to window management -rather than presume control of the entire screen. -What you do inside of your top-level window, however, -is up to your application. -For further information, -see chapter 14 -and the \fIInter-Client Communication Conventions Manual\fP. -.NH 2 -Character Sets and Encodings -.XS -\*(SN Character Sets and Encodings -.XE -.LP -Some of the Xlib functions make reference to specific character sets -and character encodings. -The following are the most common: -.IP \(bu 5 -X Portable Character Set -.IP -A basic set of 97 characters, -which are assumed to exist in all locales supported by Xlib. -This set contains the following characters: -.IP -.Ds 0 -.EQ -delim DD -.EN -a..z A..Z 0..9 -!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ -<space>, <tab>, and <newline> -.EQ -delim %% -.EN -.De -.IP -This set is the left/lower half -of the graphic character set of ISO8859-1 plus space, tab, and newline. -It is also the set of graphic characters in 7-bit ASCII plus the same -three control characters. -The actual encoding of these characters on the host is system dependent. -.IP \(bu 5 -Host Portable Character Encoding -.IP -The encoding of the X Portable Character Set on the host. -The encoding itself is not defined by this standard, -but the encoding must be the same in all locales supported by Xlib on the host. -If a string is said to be in the Host Portable Character Encoding, -then it only contains characters from the X Portable Character Set, -in the host encoding. -.IP \(bu 5 -Latin-1 -.IP -The coded character set defined by the ISO8859-1 standard. -.IP \(bu 5 -Latin Portable Character Encoding -.IP -The encoding of the X Portable Character Set using the Latin-1 codepoints -plus ASCII control characters. -If a string is said to be in the Latin Portable Character Encoding, -then it only contains characters from the X Portable Character Set, -not all of Latin-1. -.IP \(bu 5 -STRING Encoding -.IP -Latin-1, plus tab and newline. -.IP \(bu 5 -POSIX Portable Filename Character Set -.IP -The set of 65 characters, -which can be used in naming files on a POSIX-compliant host, -that are correctly processed in all locales. -The set is: -.IP -.Ds 0 -a..z A..Z 0..9 ._- -.De -.NH 2 -Formatting Conventions -.XS -\*(SN Formatting Conventions -.XE -.LP -\fIXlib \- C Language X Interface\fP uses the following conventions: -.IP \(bu 5 -Global symbols are printed in -.PN this -.PN special -.PN font . -These can be either function names, -symbols defined in include files, or structure names. -When declared and defined, -function arguments are printed in \fIitalics\fP. -In the explanatory text that follows, -they usually are printed in regular type. -.IP \(bu 5 -Each function is introduced by a general discussion that -distinguishes it from other functions. -The function declaration itself follows, -and each argument is specifically explained. -Although ANSI C function prototype syntax is not used, -Xlib header files normally declare functions using function prototypes -in ANSI C environments. -General discussion of the function, if any is required, -follows the arguments. -Where applicable, -the last paragraph of the explanation lists the possible -Xlib error codes that the function can generate. -For a complete discussion of the Xlib error codes, -see section 11.8.2. -.IP \(bu 5 -To eliminate any ambiguity between those arguments that you pass and those that -a function returns to you, -the explanations for all arguments that you pass start with the word -\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP. -The explanations for all arguments that are returned to you start with the -word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP. -The explanations for all arguments that you can pass and are returned start -with the words \fIspecifies and returns\^\fP. -.IP \(bu 5 -Any pointer to a structure that is used to return a value is designated as -such by the \fI_return\fP suffix as part of its name. -All other pointers passed to these functions are -used for reading only. -A few arguments use pointers to structures that are used for -both input and output and are indicated by using the \fI_in_out\fP suffix. -.bp +<chapter><title>Introduction to Xlib</title>
+
+<para>
+The X Window System is a network-transparent window system that was designed at MIT. X
+display servers run on computers with either monochrome or color bitmap display hardware. The
+server distributes user input to and accepts output requests from various client programs located
+either on the same machine or elsewhere in the network. Xlib is a C subroutine library that appli-
+cation programs (clients) use to interface with the window system by means of a stream connec-
+tion. Although a client usually runs on the same machine as the X server it is talking to, this need
+not be the case.
+</para>
+<para>
+Xlib − C Language X Interface is a reference guide to the low-level C language interface to the X
+Window System protocol. It is neither a tutorial nor a user’s guide to programming the X Win-
+dow System. Rather, it provides a detailed description of each function in the library as well as a
+discussion of the related background information. Xlib − C Language X Interface assumes a
+basic understanding of a graphics window system and of the C programming language. Other
+higher-level abstractions (for example, those provided by the toolkits for X) are built on top of the
+Xlib library. For further information about these higher-level libraries, see the appropriate toolkit
+documentation. The X Window System Protocol provides the definitive word on the behavior of
+X. Although additional information appears here, the protocol document is the ruling document.
+</para>
+<para>
+To provide an introduction to X programming, this chapter discusses:
+</para>
+
+<itemizedlist>
+ <listitem><para>Overview of the X Window System</para></listitem>
+ <listitem><para>Errors</para></listitem>
+ <listitem><para>Standard header files</para></listitem>
+ <listitem><para>Generic values and types</para></listitem>
+ <listitem><para>Naming and argument conventions within Xlib</para></listitem>
+ <listitem><para>Programming considerations</para></listitem>
+ <listitem><para>Character sets and encodings</para></listitem>
+ <listitem><para>Formatting conventions</para></listitem>
+</itemizedlist>
+
+
+<sect1 id="Overview_of_the_X_Window_System">
+<title>Overview of the X Window System</title>
+<!-- .XS -->
+<!-- (SN Overview of the X Window System -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some of the terms used in this book are unique to X,
+and other terms that are common to other window systems
+have different meanings in X.
+You may find it helpful to refer to the glossary,
+which is located at the end of the book.
+</para>
+<para>
+<!-- .LP -->
+The X Window System supports one or more screens containing
+overlapping windows or subwindows.
+A screen is a physical monitor and hardware
+that can be color, grayscale, or monochrome.
+There can be multiple screens for each display or workstation.
+A single X server can provide display services for any number of screens.
+A set of screens for a single user with one keyboard and one pointer
+(usually a mouse) is called a display.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Screen</primary></indexterm>
+All the windows in an X server are arranged in strict hierarchies.
+At the top of each hierarchy is a root window,
+which covers each of the display screens.
+Each root window is partially or completely covered by child windows.
+All windows, except for root windows, have parents.
+There is usually at least one window for each application program.
+<indexterm><primary>Child window</primary></indexterm>
+<indexterm><primary>Parent Window</primary></indexterm>
+Child windows may in turn have their own children.
+In this way,
+an application program can create an arbitrarily deep tree
+on each screen.
+X provides graphics, text, and raster operations for windows.
+</para>
+<para>
+<!-- .LP -->
+A child window can be larger than its parent.
+That is, part or all of
+the child window can extend beyond the boundaries of the parent,
+but all output to a window is clipped by its parent.
+<indexterm><primary>Stacking order</primary></indexterm>
+If several children of a window have overlapping locations,
+one of the children is considered to be on top of or raised over the
+others, thus obscuring them.
+Output to areas covered by other windows is suppressed by the window
+system unless the window has backing store.
+If a window is obscured by a second window,
+the second window obscures only those ancestors of the second window
+that are also ancestors of the first window.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Window</primary></indexterm>
+A window has a border zero or more pixels in width, which can
+be any pattern (pixmap) or solid color you like.
+A window usually but not always has a background pattern,
+which will be repainted by the window system when uncovered.
+Child windows obscure their parents,
+and graphic operations in the parent window usually
+are clipped by the children.
+</para>
+<para>
+<!-- .LP -->
+Each window and pixmap has its own coordinate system.
+The coordinate system has the X axis horizontal and the Y axis vertical
+with the origin [0, 0] at the upper-left corner.
+Coordinates are integral,
+in terms of pixels,
+and coincide with pixel centers.
+For a window,
+the origin is inside the border at the inside, upper-left corner.
+</para>
+<para>
+<!-- .LP -->
+X does not guarantee to preserve the contents of windows.
+When part or all of a window is hidden and then brought back onto the screen,
+its contents may be lost.
+The server then sends the client program an
+<function>Expose</function>
+event to notify it that part or all of the window needs to be repainted.
+Programs must be prepared to regenerate the contents of windows on demand.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Pixmap</primary></indexterm>
+<indexterm><primary>Drawable</primary></indexterm>
+<indexterm><primary>Tile</primary></indexterm>
+<indexterm><primary>Bitmap</primary></indexterm>
+X also provides off-screen storage of graphics objects,
+called pixmaps.
+Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.
+Pixmaps can be used in most graphics functions interchangeably with
+windows and are used in various graphics operations to define patterns or tiles.
+Windows and pixmaps together are referred to as drawables.
+</para>
+<para>
+<!-- .LP -->
+Most of the functions in Xlib just add requests to an output buffer.
+These requests later execute asynchronously on the X server.
+Functions that return values of information stored in
+the server do not return (that is, they block)
+until an explicit reply is received or an error occurs.
+You can provide an error handler,
+which will be called when the error is reported.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XSync</primary></indexterm>
+If a client does not want a request to execute asynchronously,
+it can follow the request with a call to
+<function>XSync</function>,
+which blocks until all previously buffered
+asynchronous events have been sent and acted on.
+As an important side effect,
+the output buffer in Xlib is always flushed by a call to any function
+that returns a value from the server or waits for input.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Resource IDs</primary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm>
+Many Xlib functions will return an integer resource ID,
+which allows you to refer to objects stored on the X server.
+These can be of type
+<function>Window</function>,
+<function>Font</function>,
+<function>Pixmap</function>,
+<function>Colormap</function>,
+<function>Cursor</function>,
+and
+<function>GContext</function>,
+as defined in the file
+<!-- .hN X11/X.h . -->
+These resources are created by requests and are destroyed
+(or freed) by requests or when connections are closed.
+Most of these resources are potentially sharable between
+applications, and in fact, windows are manipulated explicitly by
+window manager programs.
+Fonts and cursors are shared automatically across multiple screens.
+Fonts are loaded and unloaded as needed and are shared by multiple clients.
+Fonts are often cached in the server.
+Xlib provides no support for sharing graphics contexts between applications.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Event</primary></indexterm>
+Client programs are informed of events.
+Events may either be side effects of a request (for example, restacking windows
+generates
+<function>Expose </function>
+events) or completely asynchronous (for example, from the keyboard).
+A client program asks to be informed of events.
+Because other applications can send events to your application,
+programs must be prepared to handle (or ignore) events of all types.
+</para>
+<para>
+<!-- .LP -->
+Input events (for example, a key pressed or the pointer moved)
+arrive asynchronously from the server and are queued until they are
+requested by an explicit call (for example,
+<function>XNextEvent</function>
+or
+<function>XWindowEvent</function>).
+In addition, some library
+functions (for example,
+<function>XRaiseWindow</function>)
+generate
+<function>Expose</function>
+and
+<function>ConfigureRequest</function>
+events.
+These events also arrive asynchronously, but the client may
+<indexterm><primary>XSync</primary></indexterm>
+wish to explicitly wait for them by calling
+<function>XSync</function>
+after calling a function that can cause the server to generate events.
+</para>
+</sect1>
+<sect1 id="Errors">
+<title>Errors</title>
+<!-- .XS -->
+<!-- (SN Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some functions return
+<function>Status</function>,
+an integer error indication.
+If the function fails, it returns a zero.
+If the function returns a status of zero,
+it has not updated the return arguments.
+<indexterm><primary>Status</primary></indexterm>
+Because C does not provide multiple return values,
+many functions must return their results by writing into client-passed storage.
+<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm>
+By default, errors are handled either by a standard library function
+or by one that you provide.
+Functions that return pointers to strings return NULL pointers if
+the string does not exist.
+</para>
+<para>
+<!-- .LP -->
+The X server reports protocol errors at the time that it detects them.
+If more than one error could be generated for a given request,
+the server can report any of them.
+</para>
+<para>
+<!-- .LP -->
+Because Xlib usually does not transmit requests to the server immediately
+(that is, it buffers them), errors can be reported much later than they
+actually occur.
+For debugging purposes, however,
+Xlib provides a mechanism for forcing synchronous behavior
+(see section 11.8.1). <!-- xref -->
+When synchronization is enabled,
+errors are reported as they are generated.
+</para>
+<para>
+<!-- .LP -->
+When Xlib detects an error,
+it calls an error handler,
+which your program can provide.
+If you do not provide an error handler,
+the error is printed, and your program terminates.
+</para>
+</sect1>
+<sect1 id="Standard_Header_Files">
+<title>Standard Header Files</title>
+<!-- .XS -->
+<!-- (SN Standard Header Files -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following include files are part of the Xlib standard:
+</para>
+<!-- .IP \(bu 5 -->
+<!-- .hN X11/Xlib.h -->
+<!-- .IP -->
+
+<variablelist>
+ <varlistentry>
+ <term></X11/Xlib.h></term>
+ <listitem>
+ <para>
+This is the main header file for Xlib.
+The majority of all Xlib symbols are declared by including this file.
+This file also contains the preprocessor symbol
+<function>XlibSpecificationRelease</function>.
+<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm>
+This symbol is defined to have the 6 in this release of the standard.
+(Release 5 of Xlib was the first release to have this symbol.)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/X.h></term>
+ <listitem>
+ <para>
+This file declares types and constants for the X protocol that are
+to be used by applications. It is included automatically from
+>X11/Xlib.h< so application code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xcms.h></term>
+ <listitem>
+ <para>
+This file contains symbols for much of the color management facilities
+described in chapter 6. All functions, types, and symbols with the
+prefix "Xcms", <!-- xref -->
+plus the Color Conversion Contexts macros, are declared in this file.
+<X11/Xlib.h> must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xutil.h></term>
+ <listitem>
+ <para>
+This file declares various functions, types, and symbols used for
+inter-client communication and application utility functions,
+which are described in chapters 14 and 16. <!-- xref -->
+<X11/Xlib.h> must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xresource.h></term>
+ <listitem>
+ <para>
+This file declares all functions, types, and symbols for the
+resource manager facilities, which are described in chapter 15.
+<X11/Xlib.h> <!-- xref -->
+must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xatom.h></term>
+ <listitem>
+ <para>
+This file declares all predefined atoms,
+which are symbols with the prefix "XA_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/cursorfont.h></term>
+ <listitem>
+ <para>
+This file declares the cursor symbols for the standard cursor font,
+which are listed in appendix B.
+All cursor symbols have the prefix "XC_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/keysymdef.h></term>
+ <listitem>
+ <para>
+This file declares all standard KeySym values,
+which are symbols with the prefix "XK_".
+The KeySyms are arranged in groups, and a preprocessor symbol controls
+inclusion of each group. The preprocessor symbol must be defined
+prior to inclusion of the file to obtain the associated values.
+The preprocessor symbols are <function>XK_MISCELLANY, XK_XKB_KEYS, XK_3270,
+XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC,
+XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL,
+XK_HEBREW, XK_THAI, and XK_KOREAN</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/keysym.h></term>
+ <listitem>
+ <para>
+This file defines the preprocessor symbols
+XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3,
+XK_LATIN4, and XK_GREEK
+and then includes <X11/keysymdef.h>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xlibint.h></term>
+ <listitem>
+ <para>
+This file declares all the functions, types, and symbols used for
+extensions, which are described in appendix C.
+This file automatically includes
+<X11/Xlib.h<.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xproto.h></term>
+ <listitem>
+ <para>
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+<X11/Xlibint.h<,
+so application and extension code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xprotostr.h></term>
+ <listitem>
+ <para>
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+<X11/Xproto.h<,
+so application and extension code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/X10.h></term>
+ <listitem>
+ <para>
+This file declares all the functions, types, and symbols used for the
+X10 compatibility functions, which are described in appendix D.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect1>
+
+
+
+<sect1 id="Generic_Values_and_Types">
+<title>Generic Values and Types</title>
+<!-- .XS -->
+<!-- (SN Generic Values and Types -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following symbols are defined by Xlib and used throughout the manual:
+<indexterm significance="preferred"><primary>Bool</primary></indexterm>
+<indexterm significance="preferred"><primary>True</primary></indexterm>
+<indexterm significance="preferred"><primary>False</primary></indexterm>
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Xlib defines the type
+<function>Bool</function>
+and the Boolean values
+<function>True</function>
+and
+<function>False</function>.
+<indexterm significance="preferred"><primary>None</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>None</function>
+is the universal null resource ID or atom.
+<indexterm significance="preferred"><primary>XID</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The type
+<function>XID</function>
+is used for generic resource IDs.
+<indexterm significance="preferred"><primary>XPointer</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The type
+<function>XPointer</function>
+is defined to be char\^* and is used as a generic opaque pointer to data.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Naming_and_Argument_Conventions_within_Xlib">
+<title>Naming and Argument Conventions within Xlib</title>
+<!-- .XS -->
+<!-- (SN Naming and Argument Conventions within Xlib -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib follows a number of conventions for the naming and syntax of the functions.
+Given that you remember what information the function requires,
+these conventions are intended to make the syntax of the functions more
+predictable.
+</para>
+<para>
+<!-- .LP -->
+The major naming conventions are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+To differentiate the X symbols from the other symbols,
+the library uses mixed case for external symbols.
+It leaves lowercase for variables and all uppercase for user macros,
+as per existing convention.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All Xlib functions begin with a capital X.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The beginnings of all function names and symbols are capitalized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All user-visible data structures begin with a capital X.
+More generally,
+anything that a user might dereference begins with a capital X.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Macros and other symbols do not begin with a capital X.
+To distinguish them from all user symbols,
+each word in the macro is capitalized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All elements of or variables in a data structure are in lowercase.
+Compound words, where needed, are constructed with underscores (_).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The display argument, where used, is always first in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All resource objects, where used, occur at the beginning of the argument list
+immediately after the display argument.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a graphics context is present together with
+another type of resource (most commonly, a drawable), the
+graphics context occurs in the argument list after the other
+resource.
+Drawables outrank all other resources.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Source arguments always precede the destination arguments in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The x argument always precedes the y argument in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The width argument always precedes the height argument in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Where the x, y, width, and height arguments are used together,
+the x and y arguments always precede the width and height arguments.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Where a mask is accompanied with a structure,
+the mask always precedes the pointer to the structure in the argument list.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Programming_Considerations">
+<title>Programming Considerations</title>
+<!-- .XS -->
+<!-- (SN Programming Considerations -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The major programming considerations are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Coordinates and sizes in X are actually 16-bit quantities.
+This decision was made to minimize the bandwidth required for a
+given level of performance.
+Coordinates usually are declared as an
+<function>int </function>
+in the interface.
+Values larger than 16 bits are truncated silently.
+Sizes (width and height) are declared as unsigned quantities.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keyboards are the greatest variable between different
+manufacturers' workstations.
+If you want your program to be portable,
+you should be particularly conservative here.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Many display systems have limited amounts of off-screen memory.
+If you can, you should minimize use of pixmaps and backing
+store.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The user should have control of his screen real estate.
+Therefore, you should write your applications to react to window management
+rather than presume control of the entire screen.
+What you do inside of your top-level window, however,
+is up to your application.
+For further information,
+see chapter 14 <!-- xref -->
+and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Character_Sets_and_Encodings">
+<title>Character Sets and Encodings</title>
+<!-- .XS -->
+<!-- (SN Character Sets and Encodings -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some of the Xlib functions make reference to specific character sets
+and character encodings.
+The following are the most common:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+X Portable Character Set
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A basic set of 97 characters,
+which are assumed to exist in all locales supported by Xlib.
+This set contains the following characters:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This set is the left/lower half
+of the graphic character set of ISO8859-1 plus space, tab, and newline.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Host Portable Character Encoding
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The encoding of the X Portable Character Set on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Latin-1
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The coded character set defined by the ISO8859-1 standard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Latin Portable Character Encoding
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+STRING Encoding
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Latin-1, plus tab and newline.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<acronym>POSIX</acronym> Portable Filename Character Set
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The set of 65 characters,
+which can be used in naming files on a <acronym>POSIX</acronym>-compliant host,
+that are correctly processed in all locales.
+The set is:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literallayout class="monospaced">
+a..z A..Z 0..9 ._-
+</literallayout>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Formatting_Conventions">
+<title>Formatting Conventions</title>
+<!-- .XS -->
+<!-- (SN Formatting Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<emphasis remap='I'>Xlib \- C Language X Interface</emphasis> uses the following conventions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Global symbols are printed in
+<function>this </function>
+<function>special </function>
+<function>font</function>.
+These can be either function names,
+symbols defined in include files, or structure names.
+When declared and defined,
+function arguments are printed in <emphasis remap='I'>italics</emphasis>.
+In the explanatory text that follows,
+they usually are printed in regular type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Each function is introduced by a general discussion that
+distinguishes it from other functions.
+The function declaration itself follows,
+and each argument is specifically explained.
+Although ANSI C function prototype syntax is not used,
+Xlib header files normally declare functions using function prototypes
+in ANSI C environments.
+General discussion of the function, if any is required,
+follows the arguments.
+Where applicable,
+the last paragraph of the explanation lists the possible
+Xlib error codes that the function can generate.
+For a complete discussion of the Xlib error codes,
+see section 11.8.2. <!-- xref -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To eliminate any ambiguity between those arguments that you pass and those that
+a function returns to you,
+the explanations for all arguments that you pass start with the word
+<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify\^</emphasis>.
+The explanations for all arguments that are returned to you start with the
+word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return\^</emphasis>.
+The explanations for all arguments that you can pass and are returned start
+with the words <emphasis remap='I'>specifies and returns\^</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Any pointer to a structure that is used to return a value is designated as
+such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
+All other pointers passed to these functions are
+used for reading only.
+A few arguments use pointers to structures that are used for
+both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix.
+<!-- .bp -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH02 b/libX11/specs/libX11/CH02 deleted file mode 100644 index dbf0b4850..000000000 --- a/libX11/specs/libX11/CH02 +++ /dev/null @@ -1,2051 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2000 The Open Group -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of The Open Group shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from The Open Group. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 2\fP\s-1 - -\s+1\fBDisplay Functions\fP\s-1 -.sp 2 -.nr H1 2 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 2: Display Functions -.XE -Before your program can use a display, you must establish a connection -to the X server. -Once you have established a connection, -you then can use the Xlib macros and functions discussed in this chapter -to return information about the display. -This chapter discusses how to: -.IP \(bu 5 -Open (connect to) the display -.IP \(bu 5 -Obtain information about the display, image formats, or screens -.IP \(bu 5 -Generate a -.PN NoOperation -protocol request -.IP \(bu 5 -Free client-created data -.IP \(bu 5 -Close (disconnect from) a display -.IP \(bu 5 -Use X Server connection close operations -.IP \(bu 5 -Use Xlib with threads -.IP \(bu 5 -Use internal connections -.NH 2 -Opening the Display -.XS -\*(SN Opening the Display -.XE -.LP -To open a connection to the X server that controls a display, use -.PN XOpenDisplay . -.IN "XOpenDisplay" "" "@DEF@" -.LP -.sM -.FD 0 -Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^) -.br - char *\fIdisplay_name\fP\^; -.FN -.IP \fIdisplay_name\fP 1i -Specifies the hardware display name, which determines the display -and communications domain to be used. -On a POSIX-conformant system, if the display_name is NULL, -it defaults to the value of the DISPLAY environment variable. -.IN "Environment" "DISPLAY" -.LP -.eM -The encoding and interpretation of the display name are -implementation-dependent. -Strings in the Host Portable Character Encoding are supported; -support for other characters is implementation-dependent. -On POSIX-conformant systems, -the display name or DISPLAY environment variable can be a string in the format: -.LP -.sM -.Ds 0 -.TA 1i -.ta 1i - \fIprotocol\fP\^/\^\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP -.De -.IP \fIprotocol\fP 1i -Specifies a protocol family or an alias for a protocol family. Supported -protocol families are implementation dependent. The protocol entry is -optional. If protocol is not specified, the / separating protocol and -hostname must also not be specified. -.IP \fIhostname\fP 1i -Specifies the name of the host machine on which the display is physically -attached. -You follow the hostname with either a single colon (:) or a double colon (::). -.IP \fInumber\fP 1i -Specifies the number of the display server on that host machine. -You may optionally follow this display number with a period (.). -A single CPU can have more than one display. -Multiple displays are usually numbered starting with zero. -.IN "Screen" -.IP \fIscreen_number\fP 1i -Specifies the screen to be used on that server. -Multiple screens can be controlled by a single X server. -The screen_number sets an internal variable that can be accessed by -using the -.PN DefaultScreen -macro or the -.PN XDefaultScreen -function if you are using languages other than C (see section 2.2.1). -.LP -.eM -For example, the following would specify screen 1 of display 0 on the -machine named ``dual-headed'': -.LP -.Ds -dual-headed:0.1 -.De -.LP -The -.PN XOpenDisplay -function returns a -.PN Display -structure that serves as the -connection to the X server and that contains all the information -about that X server. -.PN XOpenDisplay -connects your application to the X server through TCP -or DECnet communications protocols, -or through some local inter-process communication protocol. -.IN "Protocol" "TCP" -.IN "Protocol" "DECnet" -If the protocol is specified as "tcp", "inet", or "inet6", or -if no protocol is specified and the hostname is a host machine name and a single colon (:) -separates the hostname and display number, -.PN XOpenDisplay -connects using TCP streams. (If the protocol is specified as "inet", TCP over -IPv4 is used. If the protocol is specified as "inet6", TCP over IPv6 is used. -Otherwise, the implementation determines which IP version is used.) -If the hostname and protocol are both not specified, -Xlib uses whatever it believes is the fastest transport. -If the hostname is a host machine name and a double colon (::) -separates the hostname and display number, -.PN XOpenDisplay -connects using DECnet. -A single X server can support any or all of these transport mechanisms -simultaneously. -A particular Xlib implementation can support many more of these transport -mechanisms. -.LP -.IN "Display" -If successful, -.PN XOpenDisplay -returns a pointer to a -.PN Display -structure, -which is defined in -.hN X11/Xlib.h . -If -.PN XOpenDisplay -does not succeed, it returns NULL. -After a successful call to -.PN XOpenDisplay , -all of the screens in the display can be used by the client. -The screen number specified in the display_name argument is returned -by the -.PN DefaultScreen -macro (or the -.PN XDefaultScreen -function). -You can access elements of the -.PN Display -and -.PN Screen -structures only by using the information macros or functions. -For information about using macros and functions to obtain information from -the -.PN Display -structure, -see section 2.2.1. -.LP -X servers may implement various types of access control mechanisms -(see section 9.8). -.NH 2 -Obtaining Information about the Display, Image Formats, or Screens -.XS -\*(SN Obtaining Information about the Display, Image Formats, or Screens -.XE -.LP -The Xlib library provides a number of useful macros -and corresponding functions that return data from the -.PN Display -structure. -The macros are used for C programming, -and their corresponding function equivalents are for other language bindings. -This section discusses the: -.IP \(bu 5 -Display macros -.IP \(bu 5 -Image format functions and macros -.IP \(bu 5 -Screen information macros -.LP -.IN "Display" "data structure" -All other members of the -.PN Display -structure (that is, those for which no macros are defined) are private to Xlib -and must not be used. -Applications must never directly modify or inspect these private members of the -.PN Display -structure. -.NT Note -The -.PN XDisplayWidth , -.PN XDisplayHeight , -.PN XDisplayCells , -.PN XDisplayPlanes , -.PN XDisplayWidthMM , -and -.PN XDisplayHeightMM -functions in the next sections are misnamed. -These functions really should be named Screen\fIwhatever\fP -and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP. -Our apologies for the resulting confusion. -.NE -.NH 3 -Display Macros -.XS -\*(SN Display Macros -.XE -.LP -Applications should not directly modify any part of the -.PN Display -and -.PN Screen -structures. -The members should be considered read-only, -although they may change as the result of other operations on the display. -.LP -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data both can return. -.LP -.sp -.sM -.FD 0 -AllPlanes -.sp -unsigned long XAllPlanes(\^) -.FN -.LP -.eM -.IN "AllPlanes" "" "@DEF@" -.IN "XAllPlanes" "" "@DEF@" -Both return a value with all bits set to 1 suitable for use in a plane argument to -a procedure. -.LP -.sp -Both -.PN BlackPixel -and -.PN WhitePixel -can be used in implementing a monochrome application. -These pixel values are for permanently allocated entries in the default -colormap. -The actual RGB (red, green, and blue) values are settable on some screens -and, in any case, may not actually be black or white. -The names are intended to convey the expected relative intensity of the colors. -.sM -.FD 0 -BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "BlackPixel" "" "@DEF@" -.IN "XBlackPixel" "" "@DEF@" -Both return the black pixel value for the specified screen. -.LP -.sp -.sM -.FD 0 -WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "WhitePixel" "" "@DEF@" -.IN "XWhitePixel" "" "@DEF@" -Both return the white pixel value for the specified screen. -.LP -.sp -.sM -.FD 0 -ConnectionNumber\^(\^\fIdisplay\fP\^) -.sp -int XConnectionNumber\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ConnectionNumber" "" "@DEF@" -.IN "XConnectionNumber" "" "@DEF@" -Both return a connection number for the specified display. -On a POSIX-conformant system, -this is the file descriptor of the connection. -.LP -.sp -.sM -.FD 0 -DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultColormap" "" "@DEF@" -.IN "XDefaultColormap" "" "@DEF@" -Both return the default colormap ID for allocation on the specified screen. -Most routine allocations of color should be made out of this colormap. -.LP -.sp -.sM -.FD 0 -DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultDepth" "" "@DEF@" -.IN "XDefaultDepth" "" "@DEF@" -Both return the depth (number of planes) of the default root window for the -specified screen. -Other depths may also be supported on this screen (see -.PN XMatchVisualInfo ). -.LP -.sp -.IN "XListDepths" "" "@DEF@" -To determine the number of depths that are available on a given screen, use -.PN XListDepths . -.sM -.FD 0 -int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP; -.br - int \fIscreen_number\fP; -.br - int *\fIcount_return\fP; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.ds Cn depths -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XListDepths -function returns the array of depths -that are available on the specified screen. -If the specified screen_number is valid and sufficient memory for the array -can be allocated, -.PN XListDepths -sets count_return to the number of available depths. -Otherwise, it does not set count_return and returns NULL. -To release the memory allocated for the array of depths, use -.PN XFree . -.LP -.sp -.sM -.FD 0 -DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultGC" "" "@DEF@" -.IN "XDefaultGC" "" "@DEF@" -Both return the default graphics context for the root window of the -specified screen. -This GC is created for the convenience of simple applications -and contains the default GC components with the foreground and -background pixel values initialized to the black and white -pixels for the screen, respectively. -You can modify its contents freely because it is not used in any Xlib -function. -This GC should never be freed. -.LP -.sp -.sM -.FD 0 -DefaultRootWindow\^(\^\fIdisplay\fP\^) -.sp -Window XDefaultRootWindow\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DefaultRootWindow" "" "@DEF@" -.IN "XDefaultRootWindow" "" "@DEF@" -Both return the root window for the default screen. -.LP -.sp -.sM -.FD 0 -DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) -.sp -Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DefaultScreenOfDisplay" "" "@DEF@" -.IN "XDefaultScreenOfDisplay" "" "@DEF@" -Both return a pointer to the default screen. -.LP -.sp -.sM -.FD 0 -ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) -.sp -Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "ScreenOfDisplay" "" "@DEF@" -.IN "XScreenOfDisplay" "" "@DEF@" -Both return a pointer to the indicated screen. -.LP -.sp -.sM -.FD 0 -DefaultScreen\^(\^\fIdisplay\fP\^) -.sp -int XDefaultScreen\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DefaultScreen" "" "@DEF@" -.IN "XDefaultScreen" "" "@DEF@" -Both return the default screen number referenced by the -.PN XOpenDisplay -function. -This macro or function should be used to retrieve the screen number -in applications that will use only a single screen. -.LP -.sp -.sM -.FD 0 -DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultVisual" "" "@DEF@" -.IN "XDefaultVisual" "" "@DEF@" -Both return the default visual type for the specified screen. -For further information about visual types, -see section 3.1. -.LP -.sp -.sM -.FD 0 -DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayCells" "" "@DEF@" -.IN "XDisplayCells" "" "@DEF@" -Both return the number of entries in the default colormap. -.LP -.sp -.sM -.FD 0 -DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayPlanes" "" "@DEF@" -.IN "XDisplayPlanes" "" "@DEF@" -Both return the depth of the root window of the specified screen. -For an explanation of depth, -see the glossary. -.LP -.sp -.sM -.FD 0 -DisplayString\^(\^\fIdisplay\fP\^) -.sp -char *XDisplayString\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DisplayString" "" "@DEF@" -.IN "XDisplayString" "" "@DEF@" -Both return the string that was passed to -.PN XOpenDisplay -when the current display was opened. -On POSIX-conformant systems, -if the passed string was NULL, these return the value of -the DISPLAY environment variable when the current display was opened. -.IN "POSIX System Call" "fork" -These are useful to applications that invoke the -.PN fork -system call and want to open a new connection to the same display from the -child process as well as for printing error messages. -.LP -.sp -.sM -.FD 0 -long XExtendedMaxRequestSize(\^\fIdisplay\fP\^) - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "XExtendedMaxRequestSize" "" "@DEF@" -The -.PN XExtendedMaxRequestSize -function returns zero if the specified display does not support an -extended-length protocol encoding; otherwise, -it returns the maximum request size (in 4-byte units) supported -by the server using the extended-length encoding. -The Xlib functions -.PN XDrawLines , -.PN XDrawArcs , -.PN XFillPolygon , -.PN XChangeProperty , -.PN XSetClipRectangles , -and -.PN XSetRegion -will use the extended-length encoding as necessary, if supported -by the server. Use of the extended-length encoding in other Xlib -functions (for example, -.PN XDrawPoints , -.PN XDrawRectangles , -.PN XDrawSegments , -.PN XFillArcs , -.PN XFillRectangles , -.PN XPutImage ) -is permitted but not required; an Xlib implementation may choose to -split the data across multiple smaller requests instead. -.LP -.sp -.sM -.FD 0 -long XMaxRequestSize(\^\fIdisplay\fP\^) - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "XMaxRequestSize" "" "@DEF@" -The -.PN XMaxRequestSize -function returns the maximum request size (in 4-byte units) supported -by the server without using an extended-length protocol encoding. -Single protocol requests to the server can be no larger than this size -unless an extended-length protocol encoding is supported by the server. -The protocol guarantees the size to be no smaller than 4096 units -(16384 bytes). -Xlib automatically breaks data up into multiple protocol requests -as necessary for the following functions: -.PN XDrawPoints , -.PN XDrawRectangles , -.PN XDrawSegments , -.PN XFillArcs , -.PN XFillRectangles , -and -.PN XPutImage . -.LP -.sp -.sM -.FD 0 -LastKnownRequestProcessed\^(\^\fIdisplay\fP\^) -.sp -unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "LastKnownRequestProcessed" "" "@DEF@" -.IN "XLastKnownRequestProcessed" "" "@DEF@" -Both extract the full serial number of the last request known by Xlib -to have been processed by the X server. -Xlib automatically sets this number when replies, events, and errors -are received. -.LP -.sp -.sM -.FD 0 -NextRequest\^(\^\fIdisplay\fP\^) -.sp -unsigned long XNextRequest\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "NextRequest" "" "@DEF@" -.IN "XNextRequest" "" "@DEF@" -Both extract the full serial number that is to be used for the next -request. -Serial numbers are maintained separately for each display connection. -.LP -.sp -.sM -.FD 0 -ProtocolVersion\^(\^\fIdisplay\fP\^) -.sp -int XProtocolVersion\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ProtocolVersion" "" "@DEF@" -.IN "XProtocolVersion" "" "@DEF@" -Both return the major version number (11) of the X protocol associated with -the connected display. -.LP -.sp -.sM -.FD 0 -ProtocolRevision\^(\^\fIdisplay\fP\^) -.sp -int XProtocolRevision\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ProtocolRevision" "" "@DEF@" -.IN "XProtocolRevision" "" "@DEF@" -Both return the minor protocol revision number of the X server. -.LP -.sp -.sM -.FD 0 -QLength\^(\^\fIdisplay\fP\^) -.sp -int XQLength\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "QLength" "" "@DEF@" -.IN "XQLength" "" "@DEF@" -Both return the length of the event queue for the connected display. -Note that there may be more events that have not been read into -the queue yet (see -.PN XEventsQueued ). -.LP -.sp -.sM -.FD 0 -RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "Window" "RootWindow" -.IN "RootWindow" "" "@DEF@" -.IN "Window" "XRootWindow" -.IN "XRootWindow" "" "@DEF@" -Both return the root window. -These are useful with functions that need a drawable of a particular screen -and for creating top-level windows. -.LP -.sp -.sM -.FD 0 -ScreenCount\^(\^\fIdisplay\fP\^) -.sp -int XScreenCount\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ScreenCount" "" "@DEF@" -.IN "XScreenCount" "" "@DEF@" -Both return the number of available screens. -.LP -.sp -.sM -.FD 0 -ServerVendor\^(\^\fIdisplay\fP\^) -.sp -char *XServerVendor\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ServerVendor" "" "@DEF@" -.IN "XServerVendor" "" "@DEF@" -Both return a pointer to a null-terminated string that provides -some identification of the owner of the X server implementation. -If the data returned by the server is in the Latin Portable Character Encoding, -then the string is in the Host Portable Character Encoding. -Otherwise, the contents of the string are implementation-dependent. -.LP -.sp -.sM -.FD 0 -VendorRelease\^(\^\fIdisplay\fP\^) -.sp -int XVendorRelease\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "VendorRelease" "" "@DEF@" -.IN "XVendorRelease" "" "@DEF@" -Both return a number related to a vendor's release of the X server. -.NH 3 -Image Format Functions and Macros -.XS -\*(SN Image Format Functions and Macros -.XE -.LP -Applications are required to present data to the X server -in a format that the server demands. -To help simplify applications, -most of the work required to convert the data is provided by Xlib -(see sections 8.7 and 16.8). -.LP -The -.PN XPixmapFormatValues -structure provides an interface to the pixmap format information -that is returned at the time of a connection setup. -It contains: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int depth; - int bits_per_pixel; - int scanline_pad; -} XPixmapFormatValues; -.De -.LP -.eM -.sp -To obtain the pixmap format information for a given display, use -.PN XListPixmapFormats . -.IN "XListPixmapFormats" "" "@DEF@" -.sM -.FD 0 -XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Cn pixmap formats that are supported by the display -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XListPixmapFormats -function returns an array of -.PN XPixmapFormatValues -structures that describe the types of Z format images supported -by the specified display. -If insufficient memory is available, -.PN XListPixmapFormats -returns NULL. -To free the allocated storage for the -.PN XPixmapFormatValues -structures, use -.PN XFree . -.LP -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data they both return for the specified server and screen. -These are often used by toolkits as well as by simple applications. -.LP -.sp -.sM -.FD 0 -ImageByteOrder\^(\^\fIdisplay\fP\^) -.sp -int XImageByteOrder\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ImageByteOrder" "" "@DEF@" -.IN "XImageByteOrder" "" "@DEF@" -Both specify the required byte order for images for each scanline unit in -XY format (bitmap) or for each pixel value in -Z format. -The macro or function can return either -.PN LSBFirst -or -.PN MSBFirst . -.LP -.sp -.sM -.FD 0 -BitmapUnit\^(\^\fIdisplay\fP\^) -.sp -int XBitmapUnit\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "BitmapUnit" "" "@DEF@" -.IN "XBitmapUnit" "" "@DEF@" -Both return the size of a bitmap's scanline unit in bits. -The scanline is calculated in multiples of this value. -.LP -.sp -.sM -.FD 0 -BitmapBitOrder\^(\^\fIdisplay\fP\^) -.sp -int XBitmapBitOrder\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "BitmapBitOrder" "" "@DEF@" -.IN "XBitmapBitOrder" "" "@DEF@" -Within each bitmap unit, the left-most bit in the bitmap as displayed -on the screen is either the least significant or most significant bit in the -unit. -This macro or function can return -.PN LSBFirst -or -.PN MSBFirst . -.LP -.sp -.sM -.FD 0 -BitmapPad\^(\^\fIdisplay\fP\^) -.sp -int XBitmapPad\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "BitmapPad" "" "@DEF@" -.IN "XBitmapPad" "" "@DEF@" -Each scanline must be padded to a multiple of bits returned -by this macro or function. -.LP -.sp -.sM -.FD 0 -DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayHeight" "" "@DEF@" -.IN "XDisplayHeight" "" "@DEF@" -Both return an integer that describes the height of the screen -in pixels. -.LP -.sp -.sM -.FD 0 -DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayHeightMM" "" "@DEF@" -.IN "XDisplayHeightMM" "" "@DEF@" -Both return the height of the specified screen in millimeters. -.LP -.sp -.sM -.FD 0 -DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayWidth" "" "@DEF@" -.IN "XDisplayWidth" "" "@DEF@" -Both return the width of the screen in pixels. -.LP -.sp -.sM -.FD 0 -DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayWidthMM" "" "@DEF@" -.IN "XDisplayWidthMM" "" "@DEF@" -Both return the width of the specified screen in millimeters. -.NH 3 -Screen Information Macros -.XS -\*(SN Screen Information Macros -.XE -.LP -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data they both can return. -These macros or functions all take a pointer to the appropriate screen -structure. -.LP -.sp -.sM -.FD 0 -BlackPixelOfScreen\^(\^\fIscreen\fP\^) -.sp -unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "BlackPixelOfScreen" "" "@DEF@" -.IN "XBlackPixelOfScreen" "" "@DEF@" -Both return the black pixel value of the specified screen. -.LP -.sp -.sM -.FD 0 -WhitePixelOfScreen\^(\^\fIscreen\fP\^) -.sp -unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "WhitePixelOfScreen" "" "@DEF@" -.IN "XWhitePixelOfScreen" "" "@DEF@" -Both return the white pixel value of the specified screen. -.LP -.sp -.sM -.FD 0 -CellsOfScreen\^(\^\fIscreen\fP\^) -.sp -int XCellsOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "CellsOfScreen" "" "@DEF@" -.IN "XCellsOfScreen" "" "@DEF@" -Both return the number of colormap cells in the default colormap -of the specified screen. -.LP -.sp -.sM -.FD 0 -DefaultColormapOfScreen\^(\^\fIscreen\fP\^) -.sp -Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultColormapOfScreen" "" "@DEF@" -.IN "XDefaultColormapOfScreen" "" "@DEF@" -Both return the default colormap of the specified screen. -.LP -.sp -.sM -.FD 0 -DefaultDepthOfScreen\^(\^\fIscreen\fP\^) -.sp -int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultDepthOfScreen" "" "@DEF@" -.IN "XDefaultDepthOfScreen" "" "@DEF@" -Both return the depth of the root window. -.LP -.sp -.sM -.FD 0 -DefaultGCOfScreen\^(\^\fIscreen\fP\^) -.sp -GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultGCOfScreen" "" "@DEF@" -.IN "XDefaultGCOfScreen" "" "@DEF@" -Both return a default graphics context (GC) of the specified screen, -which has the same depth as the root window of the screen. -The GC must never be freed. -.LP -.sp -.sM -.FD 0 -DefaultVisualOfScreen\^(\^\fIscreen\fP\^) -.sp -Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultVisualOfScreen" "" "@DEF@" -.IN "XDefaultVisualOfScreen" "" "@DEF@" -Both return the default visual of the specified screen. -For information on visual types, -see section 3.1. -.LP -.sp -.sM -.FD 0 -DoesBackingStore\^(\^\fIscreen\fP\^) -.sp -int XDoesBackingStore\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DoesBackingStore" "" "@DEF@" -.IN "XDoesBackingStore" "" "@DEF@" -Both return a value indicating whether the screen supports backing -stores. -The value returned can be one of -.PN WhenMapped , -.PN NotUseful , -or -.PN Always -(see section 3.2.4). -.LP -.sp -.sM -.FD 0 -DoesSaveUnders\^(\^\fIscreen\fP\^) -.sp -Bool XDoesSaveUnders\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DoesSaveUnders" "" "@DEF@" -.IN "XDoesSaveUnders" "" "@DEF@" -Both return a Boolean value indicating whether the -screen supports save unders. -If -.PN True , -the screen supports save unders. -If -.PN False , -the screen does not support save unders (see section 3.2.5). -.LP -.sp -.sM -.FD 0 -DisplayOfScreen\^(\^\fIscreen\fP\^) -.sp -Display *XDisplayOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DisplayOfScreen" "" "@DEF@" -.IN "XDisplayOfScreen" "" "@DEF@" -Both return the display of the specified screen. -.LP -.sp -.sM -.IN "XScreenNumberOfScreen" "" "@DEF@" -.FD 0 -int XScreenNumberOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -The -.PN XScreenNumberOfScreen -function returns the screen index number of the specified screen. -.LP -.sp -.sM -.FD 0 -EventMaskOfScreen\^(\^\fIscreen\fP\^) -.sp -long XEventMaskOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "EventMaskOfScreen" "" "@DEF@" -.IN "XEventMaskOfScreen" "" "@DEF@" -Both return the event mask of the root window for the specified screen -at connection setup time. -.LP -.sp -.sM -.FD 0 -WidthOfScreen\^(\^\fIscreen\fP\^) -.sp -int XWidthOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "WidthOfScreen" "" "@DEF@" -.IN "XWidthOfScreen" "" "@DEF@" -Both return the width of the specified screen in pixels. -.LP -.sp -.sM -.FD 0 -HeightOfScreen\^(\^\fIscreen\fP\^) -.sp -int XHeightOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "HeightOfScreen" "" "@DEF@" -.IN "XHeightOfScreen" "" "@DEF@" -Both return the height of the specified screen in pixels. -.LP -.sp -.sM -.FD 0 -WidthMMOfScreen\^(\^\fIscreen\fP\^) -.sp -int XWidthMMOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "WidthMMOfScreen" "" "@DEF@" -.IN "XWidthMMOfScreen" "" "@DEF@" -Both return the width of the specified screen in millimeters. -.LP -.sp -.sM -.FD 0 -HeightMMOfScreen\^(\^\fIscreen\fP\^) -.sp -int XHeightMMOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "HeightMMOfScreen" "" "@DEF@" -.IN "XHeightMMOfScreen" "" "@DEF@" -Both return the height of the specified screen in millimeters. -.LP -.sp -.sM -.FD 0 -MaxCmapsOfScreen\^(\^\fIscreen\fP\^) -.sp -int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "MaxCmapsOfScreen" "" "@DEF@" -.IN "XMaxCmapsOfScreen" "" "@DEF@" -Both return the maximum number of installed colormaps supported -by the specified screen (see section 9.3). -.LP -.sp -.sM -.FD 0 -MinCmapsOfScreen\^(\^\fIscreen\fP\^) -.sp -int XMinCmapsOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "MinCmapsOfScreen" "" "@DEF@" -.IN "XMinCmapsOfScreen" "" "@DEF@" -Both return the minimum number of installed colormaps supported -by the specified screen (see section 9.3). -.LP -.sp -.sM -.FD 0 -PlanesOfScreen\^(\^\fIscreen\fP\^) -.sp -int XPlanesOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "PlanesOfScreen" "" "@DEF@" -.IN "XPlanesOfScreen" "" "@DEF@" -Both return the depth of the root window. -.LP -.sp -.sM -.FD 0 -RootWindowOfScreen\^(\^\fIscreen\fP\^) -.sp -Window XRootWindowOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "RootWindowOfScreen" "" "@DEF@" -.IN "XRootWindowOfScreen" "" "@DEF@" -Both return the root window of the specified screen. -.NH 2 -Generating a NoOperation Protocol Request -.XS -\*(SN Generating a NoOperation Protocol Request -.XE -.LP -To execute a -.PN NoOperation -protocol request, use -.PN XNoOp . -.IN "XNoOp" "" "@DEF@" -.sM -.FD 0 -XNoOp\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XNoOp -function sends a -.PN NoOperation -protocol request to the X server, -thereby exercising the connection. -.NH 2 -Freeing Client-Created Data -.XS -\*(SN Freeing Client-Created Data -.XE -.LP -To free in-memory data that was created by an Xlib function, use -.PN XFree . -.IN "XFree" "" "@DEF@" -.sM -.FD 0 -XFree\^(\^\fIdata\fP\^) -.br - void *\fIdata\fP\^; -.FN -.IP \fIdata\fP 1i -Specifies the data that is to be freed. -.LP -.eM -The -.PN XFree -function is a general-purpose Xlib routine that frees the specified data. -You must use it to free any objects that were allocated by Xlib, -unless an alternate function is explicitly specified for the object. -A NULL pointer cannot be passed to this function. -.NH 2 -Closing the Display -.XS -\*(SN Closing the Display -.XE -.LP -To close a display or disconnect from the X server, use -.PN XCloseDisplay . -.IN "XCloseDisplay" "" "@DEF@" -.LP -.sM -.FD 0 -XCloseDisplay\^(\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XCloseDisplay -function closes the connection to the X server for the display specified in the -.PN Display -structure and destroys all windows, resource IDs -.Pn ( Window , -.PN Font , -.PN Pixmap , -.PN Colormap , -.PN Cursor , -and -.PN GContext ), -or other resources that the client has created -on this display, unless the close-down mode of the resource has been changed -(see -.PN XSetCloseDownMode ). -Therefore, these windows, resource IDs, and other resources should never be -referenced again or an error will be generated. -Before exiting, you should call -.PN XCloseDisplay -explicitly so that any pending errors are reported as -.PN XCloseDisplay -performs a final -.PN XSync -operation. -.IN "Resource IDs" -.IN "XCloseDisplay" -.LP -.PN XCloseDisplay -can generate a -.PN BadGC -error. -.sp -.LP -Xlib provides a function to permit the resources owned by a client -to survive after the client's connection is closed. -To change a client's close-down mode, use -.PN XSetCloseDownMode . -.IN "XSetCloseDownMode" "" "@DEF@" -.sM -.FD 0 -XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIclose_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIclose_mode\fP 1i -Specifies the client close-down mode. -You can pass -.PN DestroyAll , -.PN RetainPermanent , -or -.PN RetainTemporary . -.LP -.eM -The -.PN XSetCloseDownMode -defines what will happen to the client's resources at connection close. -A connection starts in -.PN DestroyAll -mode. -For information on what happens to the client's resources when the -close_mode argument is -.PN RetainPermanent -or -.PN RetainTemporary , -see section 2.6. -.LP -.PN XSetCloseDownMode -can generate a -.PN BadValue -error. -.NH 2 -Using X Server Connection Close Operations -.XS -\*(SN Using X Server Connection Close Operations -.XE -.LP -When the X server's connection to a client is closed -either by an explicit call to -.PN XCloseDisplay -or by a process that exits, the X server performs the following -automatic operations: -.IP \(bu 5 -It disowns all selections owned by the client -(see -.PN XSetSelectionOwner ). -.IP \(bu 5 -It performs an -.PN XUngrabPointer -and -.PN XUngrabKeyboard -if the client has actively grabbed the pointer -or the keyboard. -.IP \(bu 5 -It performs an -.PN XUngrabServer -if the client has grabbed the server. -.IP \(bu 5 -It releases all passive grabs made by the client. -.IP \(bu 5 -It marks all resources (including colormap entries) allocated -by the client either as permanent or temporary, -depending on whether the close-down mode is -.PN RetainPermanent -or -.PN RetainTemporary . -However, this does not prevent other client applications from explicitly -destroying the resources (see -.PN XSetCloseDownMode ). -.LP -When the close-down mode is -.PN DestroyAll , -the X server destroys all of a client's resources as follows: -.IP \(bu 5 -It examines each window in the client's save-set to determine if it is an inferior -(subwindow) of a window created by the client. -(The save-set is a list of other clients' windows -that are referred to as save-set windows.) -If so, the X server reparents the save-set window to the closest ancestor so -that the save-set window is not an inferior of a window created by the client. -The reparenting leaves unchanged the absolute coordinates (with respect to -the root window) of the upper-left outer corner of the save-set -window. -.IP \(bu 5 -It performs a -.PN MapWindow -request on the save-set window if the save-set window is unmapped. -The X server does this even if the save-set window was not an inferior of -a window created by the client. -.IP \(bu 5 -It destroys all windows created by the client. -.IP \(bu 5 -It performs the appropriate free request on each nonwindow resource created by -the client in the server (for example, -.PN Font , -.PN Pixmap , -.PN Cursor , -.PN Colormap , -and -.PN GContext ). -.IP \(bu 5 -It frees all colors and colormap entries allocated by a client application. -.LP -Additional processing occurs when the last connection to the X server closes. -An X server goes through a cycle of having no connections and having some -connections. -When the last connection to the X server closes as a result of a connection -closing with the close_mode of -.PN DestroyAll , -the X server does the following: -.IP \(bu 5 -It resets its state as if it had just been -started. -The X server begins by destroying all lingering resources from -clients that have terminated in -.PN RetainPermanent -or -.PN RetainTemporary -mode. -.IP \(bu 5 -It deletes all but the predefined atom identifiers. -.IP \(bu 5 -It deletes all properties on all root windows (see section 4.3). -.IP \(bu 5 -It resets all device maps and attributes -(for example, key click, bell volume, and acceleration) -as well as the access control list. -.IP \(bu 5 -It restores the standard root tiles and cursors. -.IP \(bu 5 -It restores the default font path. -.IP \(bu 5 -It restores the input focus to state -.PN PointerRoot . -.LP -However, the X server does not reset if you close a connection with a close-down -mode set to -.PN RetainPermanent -or -.PN RetainTemporary . -.NH 2 -Using Xlib with Threads -.XS -\*(SN Using Xlib with Threads -.XE -.LP -On systems that have threads, support may be provided to permit -multiple threads to use Xlib concurrently. -.LP -.sp -To initialize support for concurrent threads, use -.PN XInitThreads . -.IN "XInitThreads" "" "@DEF@" -.sM -.FD 0 -Status XInitThreads\^(\|); -.FN -.LP -.eM -The -.PN XInitThreads -function initializes Xlib support for concurrent threads. -This function must be the first Xlib function a -multi-threaded program calls, and it must complete -before any other Xlib call is made. -This function returns a nonzero status if initialization was -successful; otherwise, it returns zero. -On systems that do not support threads, this function always returns zero. -.LP -It is only necessary to call this function if multiple threads -might use Xlib concurrently. If all calls to Xlib functions -are protected by some other access mechanism (for example, -a mutual exclusion lock in a toolkit or through explicit client -programming), Xlib thread initialization is not required. -It is recommended that single-threaded programs not call this function. - -.LP -.sp -To lock a display across several Xlib calls, use -.PN XLockDisplay . -.IN "XLockDisplay" "" "@DEF@" -.sM -.FD 0 -void XLockDisplay\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XLockDisplay -function locks out all other threads from using the specified display. -Other threads attempting to use the display will block until -the display is unlocked by this thread. -Nested calls to -.PN XLockDisplay -work correctly; the display will not actually be unlocked until -.PN XUnlockDisplay -has been called the same number of times as -.PN XLockDisplay . -This function has no effect unless Xlib was successfully initialized -for threads using -.PN XInitThreads . -.LP -.sp -To unlock a display, use -.PN XUnlockDisplay . -.IN "XUnlockDisplay" "" "@DEF@" -.sM -.FD 0 -void XUnlockDisplay\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XUnlockDisplay -function allows other threads to use the specified display again. -Any threads that have blocked on the display are allowed to continue. -Nested locking works correctly; if -.PN XLockDisplay -has been called multiple times by a thread, then -.PN XUnlockDisplay -must be called an equal number of times before the display is -actually unlocked. -This function has no effect unless Xlib was successfully initialized -for threads using -.PN XInitThreads . -.NH 2 -Using Internal Connections -.XS -\*(SN Using Internal Connections -.XE -.LP -In addition to the connection to the X server, an Xlib implementation -may require connections to other kinds of servers (for example, to -input method servers as described in chapter 13). Toolkits and clients -that use multiple displays, or that use displays in combination with -other inputs, need to obtain these additional connections to correctly -block until input is available and need to process that input -when it is available. Simple clients that use a single display and -block for input in an Xlib event function do not need to use these -facilities. -.LP -To track internal connections for a display, use -.PN XAddConnectionWatch . -.LP -.IN "XWatchProc" "" "@DEF@" -.IN "XAddConnectionWatch" "" "@DEF@" -.sM -.FD 0 -typedef void (*XConnectionWatchProc)\^(\^\fIdisplay\fP, \fIclient_data\fP, \fIfd\fP, \fIopening\fP, \fIwatch_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - int \fIfd\fP\^; -.br - Bool \fIopening\fP\^; -.br - XPointer *\fIwatch_data\fP\^; -.sp -Status XAddConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XWatchProc \fIprocedure\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprocedure\fP 1i -Specifies the procedure to be called. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.LP -.eM -The -.PN XAddConnectionWatch -function registers a procedure to be called each time Xlib opens or closes an -internal connection for the specified display. The procedure is passed the -display, the specified client_data, the file descriptor for the connection, -a Boolean indicating whether the connection is being opened or closed, and a -pointer to a location for private watch data. If opening is -.PN True , -the procedure can store a pointer to private data in the location pointed -to by watch_data; -when the procedure is later called for this same connection and opening is -.PN False , -the location pointed to by watch_data will hold this same private data pointer. -.LP -This function can be called at any time after a display is opened. -If internal connections already exist, the registered procedure will -immediately be called for each of them, before -.PN XAddConnectionWatch -returns. -.PN XAddConnectionWatch -returns a nonzero status if the procedure is successfully registered; -otherwise, it returns zero. -.LP -The registered procedure should not call any Xlib functions. -If the procedure directly or indirectly causes the state of internal -connections or watch procedures to change, the result is not defined. -If Xlib has been initialized for threads, the procedure is called with -the display locked and the result of a call by the procedure to any -Xlib function that locks the display is not defined unless the executing -thread has externally locked the display using -.PN XLockDisplay . -.LP -.sp -To stop tracking internal connections for a display, use -.PN XRemoveConnectionWatch . -.IN "XRemoveConnectionWatch" "" "@DEF@" -.sM -.FD 0 -Status XRemoveConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XWatchProc \fIprocedure\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprocedure\fP 1i -Specifies the procedure to be called. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.LP -.eM -The -.PN XRemoveConnectionWatch -function removes a previously registered connection watch procedure. -The client_data must match the client_data used when the procedure -was initially registered. - -.LP -.sp -To process input on an internal connection, use -.PN XProcessInternalConnection . -.IN "XProcessInternalConnection" "" "@DEF@" -.sM -.FD 0 -void XProcessInternalConnection\^(\^\fIdisplay\fP, \fIfd\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIfd\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfd\fP 1i -Specifies the file descriptor. -.LP -.eM -The -.PN XProcessInternalConnection -function processes input available on an internal connection. -This function should be called for an internal connection only -after an operating system facility (for example, -.PN select -or -.PN poll ) -has indicated that input is available; otherwise, -the effect is not defined. -.LP -.sp -To obtain all of the current internal connections for a display, use -.PN XInternalConnectionNumbers . -.IN "XInternalConnectionNumbers" "" "@DEF@" -.sM -.FD 0 -Status XInternalConnectionNumbers\^(\^\fIdisplay\fP, \fIfd_return\fP\^, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int **\fIfd_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfd_return\fP 1i -Returns the file descriptors. -.ds Cn file descriptors -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XInternalConnectionNumbers -function returns a list of the file descriptors for all internal -connections currently open for the specified display. -When the allocated list is no longer needed, -free it by using -.PN XFree . -This functions returns a nonzero status if the list is successfully allocated; -otherwise, it returns zero. -.LP -.bp diff --git a/libX11/specs/libX11/CH02.xml b/libX11/specs/libX11/CH02.xml new file mode 100644 index 000000000..23f9f1ce2 --- /dev/null +++ b/libX11/specs/libX11/CH02.xml @@ -0,0 +1,3488 @@ +<chapter id="display_functions">
+<title>Display Functions</title>
+<para>
+Before your program can use a display, you must establish a connection
+to the X server.
+Once you have established a connection,
+you then can use the Xlib macros and functions discussed in this chapter
+to return information about the display.
+This chapter discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Open (connect to) the display
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain information about the display, image formats, or screens
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Generate a
+<function>NoOperation</function>
+protocol request
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Free client-created data
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Close (disconnect from) a display
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use X Server connection close operations
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use Xlib with threads
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use internal connections
+ </para>
+ </listitem>
+</itemizedlist>
+<sect1 id="Opening_the_Display">
+<title>Opening the Display</title>
+<!-- .XS -->
+<!-- (SN Opening the Display -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open a connection to the X server that controls a display, use
+<function>XOpenDisplay</function>.
+<indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+</para>
+<para>
+AllPlanes()
+</para>
+<para>
+XAllPlanes
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hardware display name, which determines the display
+and communications domain to be used.
+On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL,
+it defaults to the value of the DISPLAY environment variable.
+<indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The encoding and interpretation of the display name are
+implementation-dependent.
+Strings in the Host Portable Character Encoding are supported;
+support for other characters is implementation-dependent.
+On <acronym>POSIX</acronym>-conformant systems,
+the display name or DISPLAY environment variable can be a string in the format:
+</para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA 1i -->
+<!-- .ta 1i -->
+ <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis>
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>protocol</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a protocol family or an alias for a protocol family. Supported
+protocol families are implementation dependent. The protocol entry is
+optional. If protocol is not specified, the / separating protocol and
+hostname must also not be specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hostname</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the host machine on which the display is physically
+attached.
+You follow the hostname with either a single colon (:) or a double colon (::).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of the display server on that host machine.
+You may optionally follow this display number with a period (.).
+A single <acronym>CPU</acronym> can have more than one display.
+Multiple displays are usually numbered starting with zero.
+<indexterm><primary>Screen</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen to be used on that server.
+Multiple screens can be controlled by a single X server.
+The screen_number sets an internal variable that can be accessed by
+using the
+<function>DefaultScreen </function>
+macro or the
+<function>XDefaultScreen</function>
+function if you are using languages other than C (see section 2.2.1).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For example, the following would specify screen 1 of display 0 on the
+machine named ``dual-headed'':
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+dual-headed:0.1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XOpenDisplay</function>
+function returns a
+<function>Display </function>
+structure that serves as the
+connection to the X server and that contains all the information
+about that X server.
+<function>XOpenDisplay</function>
+connects your application to the X server through <acronym>TCP</acronym>
+or DECnet communications protocols,
+or through some local inter-process communication protocol.
+<indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm>
+<indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm>
+If the protocol is specified as "tcp", "inet", or "inet6", or
+if no protocol is specified and the hostname is a host machine name and a single colon (:)
+separates the hostname and display number,
+<function>XOpenDisplay</function>
+connects using <acronym>TCP</acronym> streams. (If the protocol is specified as "inet", <acronym>TCP</acronym> over
+IPv4 is used. If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used.
+Otherwise, the implementation determines which <acronym>IP</acronym> version is used.)
+If the hostname and protocol are both not specified,
+Xlib uses whatever it believes is the fastest transport.
+If the hostname is a host machine name and a double colon (::)
+separates the hostname and display number,
+<function>XOpenDisplay</function>
+connects using DECnet.
+A single X server can support any or all of these transport mechanisms
+simultaneously.
+A particular Xlib implementation can support many more of these transport
+mechanisms.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Display</primary></indexterm>
+If successful,
+<function>XOpenDisplay </function>
+returns a pointer to a
+<function>Display </function>
+structure,
+which is defined in
+<!-- .hN X11/Xlib.h . -->
+If
+<function>XOpenDisplay </function>
+does not succeed, it returns NULL.
+After a successful call to
+<function>XOpenDisplay</function>,
+all of the screens in the display can be used by the client.
+The screen number specified in the display_name argument is returned
+by the
+<function>DefaultScreen</function>
+macro (or the
+<function>XDefaultScreen</function>
+function).
+You can access elements of the
+<function>Display</function>
+and
+<function>Screen</function>
+structures only by using the information macros or functions.
+For information about using macros and functions to obtain information from
+the
+<function>Display </function>
+structure,
+see section 2.2.1.
+</para>
+<para>
+<!-- .LP -->
+X servers may implement various types of access control mechanisms
+(see section 9.8).
+</para>
+</sect1>
+<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">
+<title>Obtaining Information about the Display, Image Formats, or Screens</title>
+<!-- .XS -->
+<!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Xlib library provides a number of useful macros
+and corresponding functions that return data from the
+<function>Display </function>
+structure.
+The macros are used for C programming,
+and their corresponding function equivalents are for other language bindings.
+This section discusses the:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Display macros
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Image format functions and macros
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Screen information macros
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>
+All other members of the
+<function>Display </function>
+structure (that is, those for which no macros are defined) are private to Xlib
+and must not be used.
+Applications must never directly modify or inspect these private members of the
+<function>Display </function>
+structure.
+<!-- .NT Note -->
+The
+<function>XDisplayWidth</function>,
+<function>XDisplayHeight</function>,
+<function>XDisplayCells</function>,
+<function>XDisplayPlanes</function>,
+<function>XDisplayWidthMM</function>,
+and
+<function>XDisplayHeightMM</function>
+functions in the next sections are misnamed.
+These functions really should be named Screen<emphasis remap='I'>whatever</emphasis>
+and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.
+Our apologies for the resulting confusion.
+<!-- .NE -->
+</para>
+<sect2 id="Display_Macros_">
+<title>Display Macros </title>
+<!-- .XS -->
+<!-- (SN Display Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications should not directly modify any part of the
+<function>Display</function>
+and
+<function>Screen</function>
+structures.
+The members should be considered read-only,
+although they may change as the result of other operations on the display.
+</para>
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data both can return.
+</para>
+<para>AllPlanes()</para>
+<para>XAllPlanes()</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>
+<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>
+Both return a value with all bits set to 1 suitable for use in a plane argument to
+a procedure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Both
+<function>BlackPixel </function>
+and
+<function>WhitePixel </function>
+can be used in implementing a monochrome application.
+These pixel values are for permanently allocated entries in the default
+colormap.
+The actual <acronym>RGB</acronym> (red, green, and blue) values are settable on some screens
+and, in any case, may not actually be black or white.
+The names are intended to convey the expected relative intensity of the colors.
+<!-- .sM -->
+</para>
+<para>
+BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XBlackPixel</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>
+<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>
+Both return the black pixel value for the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XWhitePixel</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>
+<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>
+Both return the white pixel value for the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ConnectionNumber(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XConnectionNumber</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>
+<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>
+Both return a connection number for the specified display.
+On a <acronym>POSIX</acronym>-conformant system,
+this is the file descriptor of the connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap <function> XDefaultColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>
+Both return the default colormap ID for allocation on the specified screen.
+Most routine allocations of color should be made out of this colormap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDefaultDepth</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>
+Both return the depth (number of planes) of the default root window for the
+specified screen.
+Other depths may also be supported on this screen (see
+<function>XMatchVisualInfo</function>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XListDepths</primary></indexterm>
+To determine the number of depths that are available on a given screen, use
+<function>XListDepths</function>.
+<!-- .sM -->
+</para>
+<para>
+DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC <function> XDefaultGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+<!-- .ds Cn depths -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListDepths</function>
+function returns the array of depths
+that are available on the specified screen.
+If the specified screen_number is valid and sufficient memory for the array
+can be allocated,
+<function>XListDepths</function>
+sets count_return to the number of available depths.
+Otherwise, it does not set count_return and returns NULL.
+To release the memory allocated for the array of depths, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC <function> XDefaultGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>
+Both return the default graphics context for the root window of the
+specified screen.
+This GC is created for the convenience of simple applications
+and contains the default GC components with the foreground and
+background pixel values initialized to the black and white
+pixels for the screen, respectively.
+You can modify its contents freely because it is not used in any Xlib
+function.
+This GC should never be freed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultRootWindow(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window <function> XDefaultRootWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>
+Both return the root window for the default screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Screen *<function> XDefaultScreenOfDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>
+Both return a pointer to the default screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Screen *<function> XScreenOfDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>
+<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>
+Both return a pointer to the indicated screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultScreen(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDefaultScreen</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>
+Both return the default screen number referenced by the
+<function>XOpenDisplay</function>
+function.
+This macro or function should be used to retrieve the screen number
+in applications that will use only a single screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Visual *<function> XDefaultVisual</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>
+Both return the default visual type for the specified screen.
+For further information about visual types,
+see section 3.1.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDisplayCells</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>
+Both return the number of entries in the default colormap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDisplayPlanes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>
+Both return the depth of the root window of the specified screen.
+For an explanation of depth,
+see the glossary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayString(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XDisplayString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayString</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>
+Both return the string that was passed to
+<function>XOpenDisplay</function>
+when the current display was opened.
+On <acronym>POSIX</acronym>-conformant systems,
+if the passed string was NULL, these return the value of
+the DISPLAY environment variable when the current display was opened.
+<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>
+These are useful to applications that invoke the
+<function>fork</function>
+system call and want to open a new connection to the same display from the
+child process as well as for printing error messages.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XLastKnownRequestProcessed</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>
+The
+<function>XExtendedMaxRequestSize</function>
+function returns zero if the specified display does not support an
+extended-length protocol encoding; otherwise,
+it returns the maximum request size (in 4-byte units) supported
+by the server using the extended-length encoding.
+The Xlib functions
+<function>XDrawLines</function>,
+<function>XDrawArcs</function>,
+<function>XFillPolygon</function>,
+<function>XChangeProperty</function>,
+<function>XSetClipRectangles</function>,
+and
+<function>XSetRegion</function>
+will use the extended-length encoding as necessary, if supported
+by the server. Use of the extended-length encoding in other Xlib
+functions (for example,
+<function>XDrawPoints</function>,
+<function>XDrawRectangles</function>,
+<function>XDrawSegments</function>,
+<function>XFillArcs</function>,
+<function>XFillRectangles</function>,
+<function>XPutImage</function>)
+is permitted but not required; an Xlib implementation may choose to
+split the data across multiple smaller requests instead.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XLastKnownRequestProcessed</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>
+The
+<function>XMaxRequestSize</function>
+function returns the maximum request size (in 4-byte units) supported
+by the server without using an extended-length protocol encoding.
+Single protocol requests to the server can be no larger than this size
+unless an extended-length protocol encoding is supported by the server.
+The protocol guarantees the size to be no smaller than 4096 units
+(16384 bytes).
+Xlib automatically breaks data up into multiple protocol requests
+as necessary for the following functions:
+<function>XDrawPoints</function>,
+<function>XDrawRectangles</function>,
+<function>XDrawSegments</function>,
+<function>XFillArcs</function>,
+<function>XFillRectangles</function>,
+and
+<function>XPutImage</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XLastKnownRequestProcessed</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>
+<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>
+Both extract the full serial number of the last request known by Xlib
+to have been processed by the X server.
+Xlib automatically sets this number when replies, events, and errors
+are received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+NextRequest(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XNextRequest</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>NextRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>
+Both extract the full serial number that is to be used for the next
+request.
+Serial numbers are maintained separately for each display connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ProtocolVersion(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XProtocolVersion</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>
+<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>
+Both return the major version number (11) of the X protocol associated with
+the connected display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ProtocolRevision(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XProtocolRevision</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>
+<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>
+Both return the minor protocol revision number of the X server.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+QLength(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XQLength</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>QLength</primary></indexterm>
+<indexterm significance="preferred"><primary>XQLength</primary></indexterm>
+Both return the length of the event queue for the connected display.
+Note that there may be more events that have not been read into
+the queue yet (see
+<function>XEventsQueued</function>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window <function> XRootWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>
+<indexterm significance="preferred"><primary>RootWindow</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>
+<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>
+Both return the root window.
+These are useful with functions that need a drawable of a particular screen
+and for creating top-level windows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ScreenCount(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XScreenCount</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>
+<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>
+Both return the number of available screens.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ServerVendor(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XServerVendor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>
+<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>
+Both return a pointer to a null-terminated string that provides
+some identification of the owner of the X server implementation.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the string is in the Host Portable Character Encoding.
+Otherwise, the contents of the string are implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+VendorRelease(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XVendorRelease</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>
+<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>
+Both return a number related to a vendor's release of the X server.
+</para>
+</sect2>
+<sect2 id="Image_Format_Functions_and_Macros">
+<title>Image Format Functions and Macros</title>
+<!-- .XS -->
+<!-- (SN Image Format Functions and Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications are required to present data to the X server
+in a format that the server demands.
+To help simplify applications,
+most of the work required to convert the data is provided by Xlib
+(see sections 8.7 and 16.8).
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XPixmapFormatValues</function>
+structure provides an interface to the pixmap format information
+that is returned at the time of a connection setup.
+It contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int depth;
+ int bits_per_pixel;
+ int scanline_pad;
+} XPixmapFormatValues;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To obtain the pixmap format information for a given display, use
+<function>XListPixmapFormats</function>.
+<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+ImageByteOrder(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XImageByteOrder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Cn pixmap formats that are supported by the display -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListPixmapFormats</function>
+function returns an array of
+<function>XPixmapFormatValues</function>
+structures that describe the types of Z format images supported
+by the specified display.
+If insufficient memory is available,
+<function>XListPixmapFormats</function>
+returns NULL.
+To free the allocated storage for the
+<function>XPixmapFormatValues</function>
+structures, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data they both return for the specified server and screen.
+These are often used by toolkits as well as by simple applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ImageByteOrder(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XImageByteOrder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>
+<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>
+Both specify the required byte order for images for each scanline unit in
+XY format (bitmap) or for each pixel value in
+Z format.
+The macro or function can return either
+<function>LSBFirst </function>
+or
+<function>MSBFirst</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BitmapUnit(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XBitmapUnit</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>
+Both return the size of a bitmap's scanline unit in bits.
+The scanline is calculated in multiples of this value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BitmapBitOrder(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XBitmapBitOrder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>
+Within each bitmap unit, the left-most bit in the bitmap as displayed
+on the screen is either the least significant or most significant bit in the
+unit.
+This macro or function can return
+<function>LSBFirst</function>
+or
+<function>MSBFirst</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BitmapPad(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XBitmapPad</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>
+Each scanline must be padded to a multiple of bits returned
+by this macro or function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDisplayHeight</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>
+Both return an integer that describes the height of the screen
+in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDisplayHeightMM</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>
+Both return the height of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDisplayWidth</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>
+Both return the width of the screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDisplayWidthMM</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>
+Both return the width of the specified screen in millimeters.
+</para>
+</sect2>
+<sect2 id="Screen_Information_Macros">
+<title>Screen Information Macros</title>
+<!-- .XS -->
+<!-- (SN Screen Information Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data they both can return.
+These macros or functions all take a pointer to the appropriate screen
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XBlackPixelOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>
+Both return the black pixel value of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XWhitePixelOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>
+Both return the white pixel value of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+CellsOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XCellsOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>
+Both return the number of colormap cells in the default colormap
+of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap <function> XDefaultColormapOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>
+Both return the default colormap of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDefaultDepthOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>
+Both return the depth of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC <function> XDefaultGCOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>
+Both return a default graphics context (GC) of the specified screen,
+which has the same depth as the root window of the screen.
+The GC must never be freed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Visual *<function> XDefaultVisualOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>
+Both return the default visual of the specified screen.
+For information on visual types,
+see section 3.1.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DoesBackingStore(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDoesBackingStore</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>
+<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>
+Both return a value indicating whether the screen supports backing
+stores.
+The value returned can be one of
+<function>WhenMapped</function>,
+<function>NotUseful</function>,
+or
+<function>Always </function>
+(see section 3.2.4).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DoesSaveUnders(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XDoesSaveUnders</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>
+<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>
+Both return a Boolean value indicating whether the
+screen supports save unders.
+If
+<function>True</function>,
+the screen supports save unders.
+If
+<function>False</function>,
+the screen does not support save unders (see section 3.2.5).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display *<function> XDisplayOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>
+Both return the display of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>
+</para>
+<para>
+EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>long <function> XEventMaskOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XScreenNumberOfScreen</function>
+function returns the screen index number of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>long <function> XEventMaskOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>
+Both return the event mask of the root window for the specified screen
+at connection setup time.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WidthOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XWidthOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>
+Both return the width of the specified screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+HeightOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XHeightOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>
+Both return the height of the specified screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XWidthMMOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>
+Both return the width of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XHeightMMOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>
+Both return the height of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XMaxCmapsOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>
+Both return the maximum number of installed colormaps supported
+by the specified screen (see section 9.3).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XMinCmapsOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>
+Both return the minimum number of installed colormaps supported
+by the specified screen (see section 9.3).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+PlanesOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XPlanesOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>
+Both return the depth of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window <function> XRootWindowOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<function>Screen</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>
+Both return the root window of the specified screen.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Generating_a_NoOperation_Protocol_Request">
+<title>Generating a NoOperation Protocol Request</title>
+<!-- .XS -->
+<!-- (SN Generating a NoOperation Protocol Request -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To execute a
+<function>NoOperation </function>
+protocol request, use
+<function>XNoOp</function>.
+<indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XNoOp</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>display</emphasis></term>
+ <listitem>
+ <para>Specifies the connection to the X server.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNoOp</function>
+function sends a
+<function>NoOperation </function>
+protocol request to the X server,
+thereby exercising the connection.
+</para>
+</sect1>
+<sect1 id="Freeing_Client_Created_Data">
+<title>Freeing Client-Created Data</title>
+<!-- .XS -->
+<!-- (SN Freeing Client-Created Data -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To free in-memory data that was created by an Xlib function, use
+<function>XFree</function>.
+<indexterm significance="preferred"><primary>XFree</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XFree</funcdef>
+ <paramdef>void<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data that is to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFree</function>
+function is a general-purpose Xlib routine that frees the specified data.
+You must use it to free any objects that were allocated by Xlib,
+unless an alternate function is explicitly specified for the object.
+A NULL pointer cannot be passed to this function.
+</para>
+</sect1>
+<sect1 id="Closing_the_Display">
+<title>Closing the Display</title>
+<!-- .XS -->
+<!-- (SN Closing the Display -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To close a display or disconnect from the X server, use
+<function>XCloseDisplay</function>.
+<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XCloseDisplay</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseDisplay</function>
+function closes the connection to the X server for the display specified in the
+<function>Display</function>
+structure and destroys all windows, resource IDs
+(<function>Window</function>,
+<function>Font</function>,
+<function>Pixmap</function>,
+<function>Colormap</function>,
+<function>Cursor</function>,
+and
+<function>GContext</function>),
+or other resources that the client has created
+on this display, unless the close-down mode of the resource has been changed
+(see
+<function>XSetCloseDownMode</function>).
+Therefore, these windows, resource IDs, and other resources should never be
+referenced again or an error will be generated.
+Before exiting, you should call
+<function>XCloseDisplay</function>
+explicitly so that any pending errors are reported as
+<function>XCloseDisplay</function>
+performs a final
+<function>XSync</function>
+operation.
+<indexterm><primary>Resource IDs</primary></indexterm>
+<indexterm><primary>XCloseDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<function>XCloseDisplay</function>
+can generate a
+<function>BadGC</function>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides a function to permit the resources owned by a client
+to survive after the client's connection is closed.
+To change a client's close-down mode, use
+<function>XSetCloseDownMode</function>.
+<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XSetCloseDownMode</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> close_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>close_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client close-down mode.
+You can pass
+<function>DestroyAll</function>,
+<function>RetainPermanent</function>,
+or
+<function>RetainTemporary</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetCloseDownMode</function>
+defines what will happen to the client's resources at connection close.
+A connection starts in
+<function>DestroyAll</function>
+mode.
+For information on what happens to the client's resources when the
+close_mode argument is
+<function>RetainPermanent</function>
+or
+<function>RetainTemporary</function>,
+see section 2.6.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetCloseDownMode</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+</sect1>
+<sect1 id="Using_X_Server_Connection_Close_Operations_">
+<title>Using X Server Connection Close Operations </title>
+<!-- .XS -->
+<!-- (SN Using X Server Connection Close Operations -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When the X server's connection to a client is closed
+either by an explicit call to
+<function>XCloseDisplay</function>
+or by a process that exits, the X server performs the following
+automatic operations:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It disowns all selections owned by the client
+(see
+<function>XSetSelectionOwner</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs an
+<function>XUngrabPointer</function>
+and
+<function>XUngrabKeyboard </function>
+if the client has actively grabbed the pointer
+or the keyboard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs an
+<function>XUngrabServer </function>
+if the client has grabbed the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It releases all passive grabs made by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It marks all resources (including colormap entries) allocated
+by the client either as permanent or temporary,
+depending on whether the close-down mode is
+<function>RetainPermanent</function>
+or
+<function>RetainTemporary</function>.
+However, this does not prevent other client applications from explicitly
+destroying the resources (see
+<function>XSetCloseDownMode</function>).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+When the close-down mode is
+<function>DestroyAll</function>,
+the X server destroys all of a client's resources as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It examines each window in the client's save-set to determine if it is an inferior
+(subwindow) of a window created by the client.
+(The save-set is a list of other clients' windows
+that are referred to as save-set windows.)
+If so, the X server reparents the save-set window to the closest ancestor so
+that the save-set window is not an inferior of a window created by the client.
+The reparenting leaves unchanged the absolute coordinates (with respect to
+the root window) of the upper-left outer corner of the save-set
+window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs a
+<function>MapWindow</function>
+request on the save-set window if the save-set window is unmapped.
+The X server does this even if the save-set window was not an inferior of
+a window created by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It destroys all windows created by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs the appropriate free request on each nonwindow resource created by
+the client in the server (for example,
+<function>Font</function>,
+<function>Pixmap</function>,
+<function>Cursor</function>,
+<function>Colormap</function>,
+and
+<function>GContext</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It frees all colors and colormap entries allocated by a client application.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Additional processing occurs when the last connection to the X server closes.
+An X server goes through a cycle of having no connections and having some
+connections.
+When the last connection to the X server closes as a result of a connection
+closing with the close_mode of
+<function>DestroyAll</function>,
+the X server does the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It resets its state as if it had just been
+started.
+The X server begins by destroying all lingering resources from
+clients that have terminated in
+<function>RetainPermanent</function>
+or
+<function>RetainTemporary</function>
+mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It deletes all but the predefined atom identifiers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It deletes all properties on all root windows (see section 4.3).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It resets all device maps and attributes
+(for example, key click, bell volume, and acceleration)
+as well as the access control list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the standard root tiles and cursors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the default font path.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the input focus to state
+<function>PointerRoot</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+However, the X server does not reset if you close a connection with a close-down
+mode set to
+<function>RetainPermanent</function>
+or
+<function>RetainTemporary</function>.
+</para>
+</sect1>
+<sect1 id="Using_Xlib_with_Threads">
+<title>Using Xlib with Threads</title>
+<!-- .XS -->
+<!-- (SN Using Xlib with Threads -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+On systems that have threads, support may be provided to permit
+multiple threads to use Xlib concurrently.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To initialize support for concurrent threads, use
+<function>XInitThreads</function>.
+<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>Status XInitThreads();</para>
+<!-- .FN -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitThreads</function>
+function initializes Xlib support for concurrent threads.
+This function must be the first Xlib function a
+multi-threaded program calls, and it must complete
+before any other Xlib call is made.
+This function returns a nonzero status if initialization was
+successful; otherwise, it returns zero.
+On systems that do not support threads, this function always returns zero.
+</para>
+<para>
+<!-- .LP -->
+It is only necessary to call this function if multiple threads
+might use Xlib concurrently. If all calls to Xlib functions
+are protected by some other access mechanism (for example,
+a mutual exclusion lock in a toolkit or through explicit client
+programming), Xlib thread initialization is not required.
+It is recommended that single-threaded programs not call this function.
+
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lock a display across several Xlib calls, use
+<function>XLockDisplay</function>.
+<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XLockDisplay</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLockDisplay</function>
+function locks out all other threads from using the specified display.
+Other threads attempting to use the display will block until
+the display is unlocked by this thread.
+Nested calls to
+<function>XLockDisplay</function>
+work correctly; the display will not actually be unlocked until
+<function>XUnlockDisplay</function>
+has been called the same number of times as
+<function>XLockDisplay</function>.
+This function has no effect unless Xlib was successfully initialized
+for threads using
+<function>XInitThreads</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unlock a display, use
+<function>XUnlockDisplay</function>.
+<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XUnlockDisplay</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnlockDisplay</function>
+function allows other threads to use the specified display again.
+Any threads that have blocked on the display are allowed to continue.
+Nested locking works correctly; if
+<function>XLockDisplay</function>
+has been called multiple times by a thread, then
+<function>XUnlockDisplay</function>
+must be called an equal number of times before the display is
+actually unlocked.
+This function has no effect unless Xlib was successfully initialized
+for threads using
+<function>XInitThreads</function>.
+</para>
+</sect1>
+<sect1 id="Using_Internal_Connections">
+<title>Using Internal Connections</title>
+<!-- .XS -->
+<!-- (SN Using Internal Connections -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In addition to the connection to the X server, an Xlib implementation
+may require connections to other kinds of servers (for example, to
+input method servers as described in chapter 13). Toolkits and clients
+that use multiple displays, or that use displays in combination with
+other inputs, need to obtain these additional connections to correctly
+block until input is available and need to process that input
+when it is available. Simple clients that use a single display and
+block for input in an Xlib event function do not need to use these
+facilities.
+</para>
+<para>
+<!-- .LP -->
+To track internal connections for a display, use
+<function>XAddConnectionWatch</function>.
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>type void XConnectionWatchProc</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>int<parameter> fd</parameter></paramdef>
+ <paramdef>Bool<parameter> opening</parameter></paramdef>
+ <paramdef>XPointer<parameter> *watch_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status XAddConnectionWatch</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddConnectionWatch</function>
+function registers a procedure to be called each time Xlib opens or closes an
+internal connection for the specified display. The procedure is passed the
+display, the specified client_data, the file descriptor for the connection,
+a Boolean indicating whether the connection is being opened or closed, and a
+pointer to a location for private watch data. If opening is
+<function>True</function>,
+the procedure can store a pointer to private data in the location pointed
+to by watch_data;
+when the procedure is later called for this same connection and opening is
+<function>False</function>,
+the location pointed to by watch_data will hold this same private data pointer.
+</para>
+<para>
+<!-- .LP -->
+This function can be called at any time after a display is opened.
+If internal connections already exist, the registered procedure will
+immediately be called for each of them, before
+<function>XAddConnectionWatch</function>
+returns.
+<function>XAddConnectionWatch</function>
+returns a nonzero status if the procedure is successfully registered;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+The registered procedure should not call any Xlib functions.
+If the procedure directly or indirectly causes the state of internal
+connections or watch procedures to change, the result is not defined.
+If Xlib has been initialized for threads, the procedure is called with
+the display locked and the result of a call by the procedure to any
+Xlib function that locks the display is not defined unless the executing
+thread has externally locked the display using
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To stop tracking internal connections for a display, use
+<function>XRemoveConnectionWatch</function>.
+<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+()
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XRemoveConnectionWatch </function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveConnectionWatch</function>
+function removes a previously registered connection watch procedure.
+The client_data must match the client_data used when the procedure
+was initially registered.
+
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To process input on an internal connection, use
+<function>XProcessInternalConnection</function>.
+<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+()
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>XProcessInternalConnection</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> fd</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fd</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file descriptor.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XProcessInternalConnection</function>
+function processes input available on an internal connection.
+This function should be called for an internal connection only
+after an operating system facility (for example,
+<function>select</function>
+or
+<function>poll</function>)
+has indicated that input is available; otherwise,
+the effect is not defined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain all of the current internal connections for a display, use
+<function>XInternalConnectionNumbers</function>.
+<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+()
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XInternalConnectionNumbers </function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int **<parameter> fd</parameter></paramdef>
+ <paramdef>int *<parameter> count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fd_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the file descriptors.
+<!-- .ds Cn file descriptors -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInternalConnectionNumbers</function>
+function returns a list of the file descriptors for all internal
+connections currently open for the specified display.
+When the allocated list is no longer needed,
+free it by using
+<function>XFree</function>.
+This functions returns a nonzero status if the list is successfully allocated;
+otherwise, it returns zero.
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH03 b/libX11/specs/libX11/CH03 deleted file mode 100644 index f7eb2d4c0..000000000 --- a/libX11/specs/libX11/CH03 +++ /dev/null @@ -1,3121 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 3\fP\s-1 - -\s+1\fBWindow Functions\fP\s-1 -.sp 2 -.nr H1 3 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 3: Window Functions -.XE -In the X Window System, -a window is a rectangular area on the screen that lets you -view graphic output. -Client applications -can display overlapping and nested windows on one or more -screens that are driven by X servers on one or more machines. -Clients who want to create windows must first -connect their program to the X server -by calling -.PN XOpenDisplay . -This chapter begins with a discussion of -visual types and window attributes. -The chapter continues with a discussion of the Xlib functions you can use to: -.IP \(bu 5 -Create windows -.IP \(bu 5 -Destroy windows -.IP \(bu 5 -Map windows -.IP \(bu 5 -Unmap windows -.IP \(bu 5 -Configure windows -.IP \(bu 5 -Change window stacking order -.IP \(bu 5 -Change window attributes -.LP -This chapter also identifies the window actions that may generate events. -.LP -Note that it is vital that your application conform to the -established conventions for communicating with window managers -for it to work well with the various window managers in use (see section 14.1). -Toolkits generally adhere to these conventions for you, -relieving you of the burden. -Toolkits also often supersede many functions in this chapter -with versions of their own. -For more information, -refer to the documentation for the toolkit that you are using. -.NH 2 -Visual Types -.XS -\*(SN Visual Types -.XE -.LP -.IN "Visual Type" "" "@DEF@" -On some display hardware, -it may be possible to deal with color resources in more than one way. -For example, you may be able to deal with a screen of either 12-bit depth -with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth -with 8 bits of the pixel dedicated to each of red, green, and blue. -These different ways of dealing with the visual aspects of the screen -are called visuals. -For each screen of the display, there may be a list of valid visual types -supported at different depths of the screen. -Because default windows and visual types are defined for each screen, -most simple applications need not deal with this complexity. -Xlib provides macros and functions that return the default root window, -the default depth of the default root window, and the default visual type -(see sections 2.2.1 and 16.7). -.LP -Xlib uses an opaque -.PN Visual -.IN "Visual" "" "@DEF@" -structure that contains information about the possible color mapping. -The visual utility functions (see section 16.7) use an -.PN XVisualInfo -structure to return this information to an application. -The members of this structure pertinent to this discussion are class, red_mask, -green_mask, blue_mask, bits_per_rgb, and colormap_size. -The class member specifies one of the possible visual classes of the screen -and can be -.IN "Visual Classes" "StaticGray" -.IN "Visual Classes" "StaticColor" -.IN "Visual Classes" "TrueColor" -.IN "Visual Classes" "StaticColor" -.IN "Visual Classes" "GrayScale" -.IN "Visual Classes" "PseudoColor" -.PN StaticGray , -.PN StaticColor , -.PN TrueColor , -.PN GrayScale , -.PN PseudoColor , -or -.PN DirectColor . -.LP -The following concepts may serve to make the explanation of -visual types clearer. -The screen can be color or grayscale, -can have a colormap that is writable or read-only, -and can also have a colormap whose indices are decomposed into separate -RGB pieces, provided one is not on a grayscale screen. -This leads to the following diagram: -.LP -.DS -.TS -center; - c c s c s - c c c c c -| c | c | c | c | c |. - Color Gray-scale - R/O R/W R/O R/W -_ -Undecomposed Static Pseudo Static Gray -Colormap Color Color Gray Scale -_ -.T& -| c | c | c |. -Decomposed True Direct -Colormap Color Color -_ _ _ -.TE -.DE -.LP -Conceptually, -as each pixel is read out of video memory for display on the screen, -it goes through a look-up stage by indexing into a colormap. -Colormaps can be manipulated arbitrarily on some hardware, -in limited ways on other hardware, and not at all on other hardware. -The visual types affect the colormap and -the RGB values in the following ways: -.LP -.IP \(bu 5 -For -.PN PseudoColor , -a pixel value indexes a colormap to produce -independent RGB values, and the RGB values can be changed dynamically. -.IP \(bu 5 -.PN GrayScale -is treated the same way as -.PN PseudoColor -except that the primary that drives the screen is undefined. -Thus, the client should always store the -same value for red, green, and blue in the colormaps. -.IP \(bu 5 -For -.PN DirectColor , -a pixel value is decomposed into separate RGB subfields, and each -subfield separately indexes the colormap for the corresponding value. -The RGB values can be changed dynamically. -.IP \(bu 5 -.PN TrueColor -is treated the same way as -.PN DirectColor -except that the colormap has predefined, read-only RGB values. -These RGB values are server dependent but provide linear or near-linear -ramps in each primary. -.IP \(bu 5 -.PN StaticColor -is treated the same way as -.PN PseudoColor -except that the colormap has predefined, -read-only, server-dependent RGB values. -.IP \(bu 5 -.PN StaticGray -is treated the same way as -.PN StaticColor -except that the RGB values are equal for any single pixel -value, thus resulting in shades of gray. -.PN StaticGray -with a two-entry -colormap can be thought of as monochrome. -.LP -The red_mask, green_mask, and blue_mask members are only defined for -.PN DirectColor -and -.PN TrueColor . -Each has one contiguous set of bits with no -intersections. -The bits_per_rgb member specifies the log base 2 of the -number of distinct color values (individually) of red, green, and blue. -Actual RGB values are unsigned 16-bit numbers. -The colormap_size member defines the number of available colormap entries -in a newly created colormap. -For -.PN DirectColor -and -.PN TrueColor , -this is the size of an individual pixel subfield. -.sp -.LP -To obtain the visual ID from a -.PN Visual , -use -.PN XVisualIDFromVisual . -.IN "XVisualIDFromVisual" "" "@DEF@" -.sM -.FD 0 -VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^) -.br - Visual *\^\fIvisual\fP\^; -.FN -.IP \fIvisual\fP 1i -Specifies the visual type. -.LP -.eM -The -.PN XVisualIDFromVisual -function returns the visual ID for the specified visual type. -.NH 2 -Window Attributes -.XS -\*(SN Window Attributes -.XE -.LP -.IN "Window" -.IN "Window" "attributes" -All -.PN InputOutput -windows have a border width of zero or more pixels, an optional background, -an event suppression mask (which suppresses propagation of events from -children), and a property list (see section 4.3). -The window border and background can be a solid color or a pattern, called -a tile. -All windows except the root have a parent and are clipped by their parent. -If a window is stacked on top of another window, it obscures that other -window for the purpose of input. -If a window has a background (almost all do), it obscures the other -window for purposes of output. -Attempts to output to the obscured area do nothing, -and no input events (for example, pointer motion) are generated for the -obscured area. -.LP -Windows also have associated property lists (see section 4.3). -.LP -Both -.PN InputOutput -and -.PN InputOnly -windows have the following common attributes, -which are the only attributes of an -.PN InputOnly -window: -.IP \(bu 5 -win-gravity -.IP \(bu 5 -event-mask -.IP \(bu 5 -do-not-propagate-mask -.IP \(bu 5 -override-redirect -.IP \(bu 5 -cursor -.LP -If you specify any other attributes for an -.PN InputOnly -window, -a -.PN BadMatch -error results. -.LP -.PN InputOnly -windows are used for controlling input events in situations where -.PN InputOutput -windows are unnecessary. -.PN InputOnly -windows are invisible; can only be used to control such things as -cursors, input event generation, and grabbing; -and cannot be used in any graphics requests. -Note that -.PN InputOnly -windows cannot have -.PN InputOutput -windows as inferiors. -.LP -Windows have borders of a programmable width and pattern -as well as a background pattern or tile. -.IN "Tile" "pixmaps" -Pixel values can be used for solid colors. -.IN "Resource IDs" "freeing" -.IN "Freeing" "resources" -The background and border pixmaps can be destroyed immediately after -creating the window if no further explicit references to them -are to be made. -.IN "Tile" "mode" -The pattern can either be relative to the parent -or absolute. -If -.PN ParentRelative , -the parent's background is used. -.LP -When windows are first created, -they are not visible (not mapped) on the screen. -Any output to a window that is not visible on the screen -and that does not have backing store will be discarded. -.IN "Window" "mapping" -An application may wish to create a window long before it is -mapped to the screen. -When a window is eventually mapped to the screen -(using -.PN XMapWindow ), -.IN "XMapWindow" -the X server generates an -.PN Expose -event for the window if backing store has not been maintained. -.LP -A window manager can override your choice of size, -border width, and position for a top-level window. -Your program must be prepared to use the actual size and position -of the top window. -It is not acceptable for a client application to resize itself -unless in direct response to a human command to do so. -Instead, either your program should use the space given to it, -or if the space is too small for any useful work, your program -might ask the user to resize the window. -The border of your top-level window is considered fair game -for window managers. -.LP -To set an attribute of a window, -set the appropriate member of the -.PN XSetWindowAttributes -structure and OR in the corresponding value bitmask in your subsequent calls to -.PN XCreateWindow -and -.PN XChangeWindowAttributes , -or use one of the other convenience functions that set the appropriate -attribute. -The symbols for the value mask bits and the -.PN XSetWindowAttributes -structure are: -.sM -.LP -/* Window attribute value mask bits */ -.TS -lw(.5i) lw(2.5i) lw(.8i). -T{ -#define -T} T{ -.PN CWBackPixmap -T} T{ -(1L<<0) -T} -T{ -#define -T} T{ -.PN CWBackPixel -T} T{ -(1L<<1) -T} -T{ -#define -T} T{ -.PN CWBorderPixmap -T} T{ -(1L<<2) -T} -T{ -#define -T} T{ -.PN CWBorderPixel -T} T{ -(1L<<3) -T} -T{ -#define -T} T{ -.PN CWBitGravity -T} T{ -(1L<<4) -T} -T{ -#define -T} T{ -.PN CWWinGravity -T} T{ -(1L<<5) -T} -T{ -#define -T} T{ -.PN CWBackingStore -T} T{ -(1L<<6) -T} -T{ -#define -T} T{ -.PN CWBackingPlanes -T} T{ -(1L<<7) -T} -T{ -#define -T} T{ -.PN CWBackingPixel -T} T{ -(1L<<8) -T} -T{ -#define -T} T{ -.PN CWOverrideRedirect -T} T{ -(1L<<9) -T} -T{ -#define -T} T{ -.PN CWSaveUnder -T} T{ -(1L<<10) -T} -T{ -#define -T} T{ -.PN CWEventMask -T} T{ -(1L<<11) -T} -T{ -#define -T} T{ -.PN CWDontPropagate -T} T{ -(1L<<12) -T} -T{ -#define -T} T{ -.PN CWColormap -T} T{ -(1L<<13) -T} -T{ -#define -T} T{ -.PN CWCursor -T} T{ -(1L<<14) -T} -.TE -.IN "XSetWindowAttributes" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -/* Values */ - -typedef struct { - Pixmap background_pixmap; /* background, None, or ParentRelative */ - unsigned long background_pixel; /* background pixel */ - Pixmap border_pixmap; /* border of the window or CopyFromParent */ - unsigned long border_pixel; /* border pixel value */ - int bit_gravity; /* one of bit gravity values */ - int win_gravity; /* one of the window gravity values */ - int backing_store; /* NotUseful, WhenMapped, Always */ - unsigned long backing_planes; /* planes to be preserved if possible */ - unsigned long backing_pixel; /* value to use in restoring planes */ - Bool save_under; /* should bits under be saved? (popups) */ - long event_mask; /* set of events that should be saved */ - long do_not_propagate_mask; /* set of events that should not propagate */ - Bool override_redirect; /* boolean value for override_redirect */ - Colormap colormap; /* color map to be associated with window */ - Cursor cursor; /* cursor to be displayed (or None) */ -} XSetWindowAttributes; -.De -.LP -.eM -The following lists the defaults for each window attribute and indicates -whether the attribute is applicable to -.PN InputOutput -and -.PN InputOnly -windows: -.TS H -l l l l -lw(1.4i) lw(1.3i) cw(.9i) cw(.8i). -_ -.sp 6p -T{ -.B Attribute -T} T{ -.B Default -T} T{ -.PN InputOutput -T} T{ -.PN InputOnly -T} -.sp 6p -_ -.sp 6p -.TH -.R -T{ -background-pixmap -T} T{ -.PN None -T} T{ -Yes -T} T{ -No -T} -background-pixel Undefined Yes No -T{ -border-pixmap -T} T{ -.PN CopyFromParent -T} T{ -Yes -T} T{ -No -T} -border-pixel Undefined Yes No -T{ -bit-gravity -T} T{ -.PN ForgetGravity -T} T{ -Yes -T} T{ -No -T} -T{ -win-gravity -T} T{ -.PN NorthWestGravity -T} T{ -Yes -T} T{ -Yes -T} -T{ -backing-store -T} T{ -.PN NotUseful -T} T{ -Yes -T} T{ -No -T} -backing-planes All ones Yes No -backing-pixel zero Yes No -T{ -save-under -T} T{ -.PN False -T} T{ -Yes -T} T{ -No -T} -event-mask empty set Yes Yes -do-not-propagate-mask empty set Yes Yes -T{ -override-redirect -T} T{ -.PN False -T} T{ -Yes -T} T{ -Yes -T} -T{ -colormap -T} T{ -.PN CopyFromParent -T} T{ -Yes -T} T{ -No -T} -T{ -cursor -T} T{ -.PN None -T} T{ -Yes -T} T{ -Yes -T} -_ -.TE -.NH 3 -Background Attribute -.XS -\*(SN Background Attribute -.XE -.LP -Only -.PN InputOutput -windows can have a background. -You can set the background of an -.PN InputOutput -window by using a pixel or a pixmap. -.LP -The background-pixmap attribute of a window specifies the pixmap to be used for -a window's background. -This pixmap can be of any size, although some sizes may be faster than others. -The background-pixel attribute of a window specifies a pixel value used to paint -a window's background in a single color. -.LP -You can set the background-pixmap to a pixmap, -.PN None -(default), or -.PN ParentRelative . -You can set the background-pixel of a window to any pixel value (no default). -If you specify a background-pixel, -it overrides either the default background-pixmap -or any value you may have set in the background-pixmap. -A pixmap of an undefined size that is filled with the background-pixel is used -for the background. -Range checking is not performed on the background pixel; -it simply is truncated to the appropriate number of bits. -.LP -If you set the background-pixmap, -it overrides the default. -The background-pixmap and the window must have the same depth, -or a -.PN BadMatch -error results. -If you set background-pixmap to -.PN None , -the window has no defined background. -If you set the background-pixmap to -.PN ParentRelative : -.IP \(bu 5 -The parent window's background-pixmap is used. -The child window, however, must have the same depth as -its parent, -or a -.PN BadMatch -error results. -.IP \(bu 5 -If the parent window has a background-pixmap of -.PN None , -the window also has a background-pixmap of -.PN None . -.IP \(bu 5 -A copy of the parent window's background-pixmap is not made. -The parent's background-pixmap is examined each time the child window's -background-pixmap is required. -.IP \(bu 5 -The background tile origin always aligns with the parent window's -background tile origin. -If the background-pixmap is not -.PN ParentRelative , -the background tile origin is the child window's origin. -.LP -Setting a new background, whether by setting background-pixmap or -background-pixel, overrides any previous background. -The background-pixmap can be freed immediately if no further explicit reference -is made to it (the X server will keep a copy to use when needed). -If you later draw into the pixmap used for the background, -what happens is undefined because the -X implementation is free to make a copy of the pixmap or -to use the same pixmap. -.LP -When no valid contents are available for regions of a window -and either the regions are visible or the server is maintaining backing store, -the server automatically tiles the regions with the window's background -unless the window has a background of -.PN None . -If the background is -.PN None , -the previous screen contents from other windows of the same depth as the window -are simply left in place as long as the contents come from the parent of the -window or an inferior of the parent. -Otherwise, the initial contents of the exposed regions are undefined. -.PN Expose -events are then generated for the regions, even if the background-pixmap -is -.PN None -(see section 10.9). -.NH 3 -Border Attribute -.XS -\*(SN Border Attribute -.XE -.LP -Only -.PN InputOutput -windows can have a border. -You can set the border of an -.PN InputOutput -window by using a pixel or a pixmap. -.LP -The border-pixmap attribute of a window specifies the pixmap to be used -for a window's border. -The border-pixel attribute of a window specifies a pixmap of undefined size -filled with that pixel be used for a window's border. -Range checking is not performed on the background pixel; -it simply is truncated to the appropriate number of bits. -The border tile origin is always the same as the background tile origin. -.LP -You can also set the border-pixmap to a pixmap of any size (some may be faster -than others) or to -.PN CopyFromParent -(default). -You can set the border-pixel to any pixel value (no default). -.LP -If you set a border-pixmap, -it overrides the default. -The border-pixmap and the window must have the same depth, -or a -.PN BadMatch -error results. -If you set the border-pixmap to -.PN CopyFromParent , -the parent window's border-pixmap is copied. -Subsequent changes to the parent window's border attribute do not affect -the child window. -However, the child window must have the same depth as the parent window, -or a -.PN BadMatch -error results. -.LP -The border-pixmap can be freed immediately if no further explicit reference -is made to it. -If you later draw into the pixmap used for the border, -what happens is undefined because the -X implementation is free either to make a copy of the pixmap or -to use the same pixmap. -If you specify a border-pixel, -it overrides either the default border-pixmap -or any value you may have set in the border-pixmap. -All pixels in the window's border will be set to the border-pixel. -Setting a new border, whether by setting border-pixel or by setting -border-pixmap, overrides any previous border. -.LP -Output to a window is always clipped to the inside of the window. -Therefore, graphics operations never affect the window border. -.NH 3 -Gravity Attributes -.XS -\*(SN Gravity Attributes -.XE -.LP -The bit gravity of a window defines which region of the window should be -retained when an -.PN InputOutput -window is resized. -The default value for the bit-gravity attribute is -.PN ForgetGravity . -The window gravity of a window allows you to define how the -.PN InputOutput -or -.PN InputOnly -window should be repositioned if its parent is resized. -The default value for the win-gravity attribute is -.PN NorthWestGravity . -.LP -If the inside width or height of a window is not changed -and if the window is moved or its border is changed, -then the contents of the window are not lost but move with the window. -Changing the inside width or height of the window causes its contents to be -moved or lost (depending on the bit-gravity of the window) and causes -children to be reconfigured (depending on their win-gravity). -For a -change of width and height, the (x, y) pairs are defined: -.LP -.TS -l l -l l. -_ -.sp 6p -.B -Gravity Direction Coordinates -.sp 6p -_ -.sp 6p -.R -T{ -.PN NorthWestGravity -T} T{ -(0, 0) -T} -T{ -.PN NorthGravity -T} T{ -(Width/2, 0) -T} -T{ -.PN NorthEastGravity -T} T{ -(Width, 0) -T} -T{ -.PN WestGravity -T} T{ -(0, Height/2) -T} -T{ -.PN CenterGravity -T} T{ -(Width/2, Height/2) -T} -T{ -.PN EastGravity -T} T{ -(Width, Height/2) -T} -T{ -.PN SouthWestGravity -T} T{ -(0, Height) -T} -T{ -.PN SouthGravity -T} T{ -(Width/2, Height) -T} -T{ -.PN SouthEastGravity -T} T{ -(Width, Height) -T} -.sp 6p -_ -.TE -.LP -When a window with one of these bit-gravity values is resized, -the corresponding pair -defines the change in position of each pixel in the window. -When a window with one of these win-gravities has its parent window resized, -the corresponding pair defines the change in position of the window -within the parent. -When a window is so repositioned, a -.PN GravityNotify -event is generated (see section 10.10.5). -.LP -A bit-gravity of -.PN StaticGravity -indicates that the contents or origin should not move relative to the -origin of the root window. -If the change in size of the window is coupled with a change in position (x, y), -then for bit-gravity the change in position of each pixel is (\-x, \-y), and for -win-gravity the change in position of a child when its parent is so resized is -(\-x, \-y). -Note that -.PN StaticGravity -still only takes effect when the width or height of the window is changed, -not when the window is moved. -.LP -A bit-gravity of -.PN ForgetGravity -indicates that the window's contents are always discarded after a size change, -even if a backing store or save under has been requested. -The window is tiled with its background -and zero or more -.PN Expose -events are generated. -If no background is defined, the existing screen contents are not -altered. -Some X servers may also ignore the specified bit-gravity and -always generate -.PN Expose -events. -.LP -The contents and borders of inferiors are not affected by their parent's -bit-gravity. -A server is permitted to ignore the specified bit-gravity and use -.PN Forget -instead. -.LP -A win-gravity of -.PN UnmapGravity -is like -.PN NorthWestGravity -(the window is not moved), -except the child is also -unmapped when the parent is resized, -and an -.PN UnmapNotify -event is -generated. -.NH 3 -Backing Store Attribute -.XS -\*(SN Backing Store Attribute -.XE -.LP -Some implementations of the X server may choose to maintain the contents of -.PN InputOutput -windows. -If the X server maintains the contents of a window, -the off-screen saved pixels -are known as backing store. -The backing store advises the X server on what to do -with the contents of a window. -The backing-store attribute can be set to -.PN NotUseful -(default), -.PN WhenMapped , -or -.PN Always . -.LP -A backing-store attribute of -.PN NotUseful -advises the X server that -maintaining contents is unnecessary, -although some X implementations may -still choose to maintain contents and, therefore, not generate -.PN Expose -events. -A backing-store attribute of -.PN WhenMapped -advises the X server that maintaining contents of -obscured regions when the window is mapped would be beneficial. -In this case, -the server may generate an -.PN Expose -event when the window is created. -A backing-store attribute of -.PN Always -advises the X server that maintaining contents even when -the window is unmapped would be beneficial. -Even if the window is larger than its parent, -this is a request to the X server to maintain complete contents, -not just the region within the parent window boundaries. -While the X server maintains the window's contents, -.PN Expose -events normally are not generated, -but the X server may stop maintaining -contents at any time. -.LP -When the contents of obscured regions of a window are being maintained, -regions obscured by noninferior windows are included in the destination -of graphics requests (and source, when the window is the source). -However, regions obscured by inferior windows are not included. -.NH 3 -Save Under Flag -.XS -\*(SN Save Under Flag -.XE -.IN "Save Unders" -.LP -Some server implementations may preserve contents of -.PN InputOutput -windows under other -.PN InputOutput -windows. -This is not the same as preserving the contents of a window for you. -You may get better visual -appeal if transient windows (for example, pop-up menus) request that the system -preserve the screen contents under them, -so the temporarily obscured applications do not have to repaint. -.LP -You can set the save-under flag to -.PN True -or -.PN False -(default). -If save-under is -.PN True , -the X server is advised that, when this window is mapped, -saving the contents of windows it obscures would be beneficial. -.NH 3 -Backing Planes and Backing Pixel Attributes -.XS -\*(SN Backing Planes and Backing Pixel Attributes -.XE -.LP -You can set backing planes to indicate (with bits set to 1) -which bit planes of an -.PN InputOutput -window hold dynamic data that must be preserved in backing store -and during save unders. -The default value for the backing-planes attribute is all bits set to 1. -You can set backing pixel to specify what bits to use in planes not -covered by backing planes. -The default value for the backing-pixel attribute is all bits set to 0. -The X server is free to save only the specified bit planes in the backing store -or the save under and is free to regenerate the remaining planes with -the specified pixel value. -Any extraneous bits in these values (that is, those bits beyond -the specified depth of the window) may be simply ignored. -If you request backing store or save unders, -you should use these members to minimize the amount of off-screen memory -required to store your window. -.NH 3 -Event Mask and Do Not Propagate Mask Attributes -.XS -\*(SN Event Mask and Do Not Propagate Mask Attributes -.XE -.LP -The event mask defines which events the client is interested in for this -.PN InputOutput -or -.PN InputOnly -window (or, for some event types, inferiors of this window). -The event mask is the bitwise inclusive OR of zero or more of the -valid event mask bits. -You can specify that no maskable events are reported by setting -.PN NoEventMask -(default). -.LP -The do-not-propagate-mask attribute -defines which events should not be propagated to -ancestor windows when no client has the event type selected in this -.PN InputOutput -or -.PN InputOnly -window. -The do-not-propagate-mask is the bitwise inclusive OR of zero or more -of the following masks: -.PN KeyPress , -.PN KeyRelease , -.PN ButtonPress , -.PN ButtonRelease , -.PN PointerMotion , -.PN Button1Motion , -.PN Button2Motion , -.PN Button3Motion , -.PN Button4Motion , -.PN Button5Motion , -and -.PN ButtonMotion . -You can specify that all events are propagated by setting -.PN NoEventMask -(default). -.NH 3 -Override Redirect Flag -.XS -\*(SN Override Redirect Flag -.XE -.LP -To control window placement or to add decoration, -a window manager often needs to intercept (redirect) any map or configure -request. -Pop-up windows, however, often need to be mapped without a window manager -getting in the way. -To control whether an -.PN InputOutput -or -.PN InputOnly -window is to ignore these structure control facilities, -use the override-redirect flag. -.LP -The override-redirect flag specifies whether map and configure requests -on this window should override a -.PN SubstructureRedirectMask -on the parent. -You can set the override-redirect flag to -.PN True -or -.PN False -(default). -Window managers use this information to avoid tampering with pop-up windows -(see also chapter 14). -.NH 3 -Colormap Attribute -.XS -\*(SN Colormap Attribute -.XE -.LP -The colormap attribute specifies which colormap best reflects the true -colors of the -.PN InputOutput -window. -The colormap must have the same visual type as the window, -or a -.PN BadMatch -error results. -X servers capable of supporting multiple -hardware colormaps can use this information, -and window managers can use it for calls to -.PN XInstallColormap . -You can set the colormap attribute to a colormap or to -.PN CopyFromParent -(default). -.LP -If you set the colormap to -.PN CopyFromParent , -the parent window's colormap is copied and used by its child. -However, the child window must have the same visual type as the parent, -or a -.PN BadMatch -error results. -The parent window must not have a colormap of -.PN None , -or a -.PN BadMatch -error results. -The colormap is copied by sharing the colormap object between the child -and parent, not by making a complete copy of the colormap contents. -Subsequent changes to the parent window's colormap attribute do -not affect the child window. -.NH 3 -Cursor Attribute -.XS -\*(SN Cursor Attribute -.XE -.LP -The cursor attribute specifies which cursor is to be used when the pointer is -in the -.PN InputOutput -or -.PN InputOnly -window. -You can set the cursor to a cursor or -.PN None -(default). -.LP -If you set the cursor to -.PN None , -the parent's cursor is used when the -pointer is in the -.PN InputOutput -or -.PN InputOnly -window, and any change in the parent's cursor will cause an -immediate change in the displayed cursor. -By calling -.PN XFreeCursor , -the cursor can be freed immediately as long as no further explicit reference -to it is made. -.NH 2 -Creating Windows -.XS -\*(SN Creating Windows -.XE -.LP -Xlib provides basic ways for creating windows, -and toolkits often supply higher-level functions specifically for -creating and placing top-level windows, -which are discussed in the appropriate toolkit documentation. -If you do not use a toolkit, however, -you must provide some standard information or hints for the window -manager by using the Xlib inter-client communication functions -(see chapter 14). -.LP -If you use Xlib to create your own top-level windows -(direct children of the root window), -you must observe the following rules so that all applications interact -reasonably across the different styles of window management: -.IP \(bu 5 -You must never fight with the window manager for the size or -placement of your top-level window. -.IP \(bu 5 -You must be able to deal with whatever size window you get, -even if this means that your application just prints a message -like ``Please make me bigger'' in its window. -.IP \(bu 5 -You should only attempt to resize or move top-level windows in -direct response to a user request. -If a request to change the size of a top-level window fails, -you must be prepared to live with what you get. -You are free to resize or move the children of top-level -windows as necessary. -(Toolkits often have facilities for automatic relayout.) -.IP \(bu 5 -If you do not use a toolkit that automatically sets standard window properties, -you should set these properties for top-level windows before mapping them. -.LP -For further information, -see chapter 14 and the \fIInter-Client Communication Conventions Manual\fP. -.LP -.PN XCreateWindow -is the more general function that allows you to set specific window attributes -when you create a window. -.PN XCreateSimpleWindow -creates a window that inherits its attributes from its parent window. -.LP -.IN "Window" "InputOnly" -The X server acts as if -.PN InputOnly -windows do not exist for -the purposes of graphics requests, exposure processing, and -.PN VisibilityNotify -events. -An -.PN InputOnly -window cannot be used as a -drawable (that is, as a source or destination for graphics requests). -.PN InputOnly -and -.PN InputOutput -windows act identically in other respects (properties, -grabs, input control, and so on). -Extension packages can define other classes of windows. -.LP -To create an unmapped window and set its window attributes, use -.PN XCreateWindow . -.IN "XCreateWindow" "" "@DEF@" -.sM -.FD 0 -Window XCreateWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, \fIdepth\fP\^, -.br - \fIclass\fP\^, \fIvisual\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIparent\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned int \fIborder_width\fP\^; -.br - int \fIdepth\fP\^; -.br - unsigned int \fIclass\fP\^; -.br - Visual *\fIvisual\fP\^; -.br - unsigned long \fIvaluemask\fP\^; -.br - XSetWindowAttributes *\fIattributes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIparent\fP 1i -Specifies the parent window. -.ds Xy , which are the top-left outside corner of the created window's \ -borders and are relative to the inside of the parent window's borders -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which are the created window's inside dimensions \ -and do not include the created window's borders -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -The dimensions must be nonzero, -or a -.PN BadValue -error results. -.IP \fIborder_width\fP 1i -Specifies the width of the created window's border in pixels. -.IP \fIdepth\fP 1i -Specifies the window's depth. -A depth of -.PN CopyFromParent -means the depth is taken from the parent. -.IP \fIclass\fP 1i -Specifies the created window's class. -You can pass -.PN InputOutput , -.PN InputOnly , -or -.PN CopyFromParent . -A class of -.PN CopyFromParent -means the class -is taken from the parent. -.IP \fIvisual\fP 1i -Specifies the visual type. -A visual of -.PN CopyFromParent -means the visual type is taken from the -parent. -.IP \fIvaluemask\fP 1i -Specifies which window attributes are defined in the attributes -argument. -This mask is the bitwise inclusive OR of the valid attribute mask bits. -If valuemask is zero, -the attributes are ignored and are not referenced. -.IP \fIattributes\fP 1i -Specifies the structure from which the values (as specified by the value mask) -are to be taken. -The value mask should have the appropriate bits -set to indicate which attributes have been set in the structure. -.LP -.eM -The -.PN XCreateWindow -function creates an unmapped subwindow for a specified parent window, -returns the window ID of the created window, -and causes the X server to generate a -.PN CreateNotify -event. -The created window is placed on top in the stacking order -with respect to siblings. -.LP -The coordinate system has the X axis horizontal and the Y axis vertical -with the origin [0, 0] at the upper-left corner. -Coordinates are integral, -in terms of pixels, -and coincide with pixel centers. -Each window and pixmap has its own coordinate system. -For a window, -the origin is inside the border at the inside, upper-left corner. -.LP -The border_width for an -.PN InputOnly -window must be zero, or a -.PN BadMatch -error results. -For class -.PN InputOutput , -the visual type and depth must be a combination supported for the screen, -or a -.PN BadMatch -error results. -The depth need not be the same as the parent, -but the parent must not be a window of class -.PN InputOnly , -or a -.PN BadMatch -error results. -For an -.PN InputOnly -window, -the depth must be zero, and the visual must be one supported by the screen. -If either condition is not met, -a -.PN BadMatch -error results. -The parent window, however, may have any depth and class. -If you specify any invalid window attribute for a window, a -.PN BadMatch -error results. -.LP -The created window is not yet displayed (mapped) on the user's display. -To display the window, call -.PN XMapWindow . -The new window initially uses the same cursor as -its parent. -A new cursor can be defined for the new window by calling -.PN XDefineCursor . -.IN "Cursor" "Initial State" -.IN "XDefineCursor" -The window will not be visible on the screen unless it and all of its -ancestors are mapped and it is not obscured by any of its ancestors. -.LP -.PN XCreateWindow -can generate -.PN BadAlloc , -.PN BadColor , -.PN BadCursor , -.PN BadMatch , -.PN BadPixmap , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To create an unmapped -.PN InputOutput -subwindow of a given parent window, use -.PN XCreateSimpleWindow . -.IN "XCreateSimpleWindow" "" "@DEF@" -.sM -.FD 0 -Window XCreateSimpleWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, -.br - \fIborder\fP\^, \fIbackground\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIparent\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned int \fIborder_width\fP\^; -.br - unsigned long \fIborder\fP\^; -.br - unsigned long \fIbackground\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIparent\fP 1i -Specifies the parent window. -.ds Xy , which are the top-left outside corner of the new window's borders \ -and are relative to the inside of the parent window's borders -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which are the created window's inside dimensions \ -and do not include the created window's borders -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -The dimensions must be nonzero, -or a -.PN BadValue -error results. -.IP \fIborder_width\fP 1i -Specifies the width of the created window's border in pixels. -.IP \fIborder\fP 1i -Specifies the border pixel value of the window. -.IP \fIbackground\fP 1i -Specifies the background pixel value of the window. - -.LP -.eM -The -.PN XCreateSimpleWindow -function creates an unmapped -.PN InputOutput -subwindow for a specified parent window, returns the -window ID of the created window, and causes the X server to generate a -.PN CreateNotify -event. -The created window is placed on top in the stacking order with respect to -siblings. -Any part of the window that extends outside its parent window is clipped. -The border_width for an -.PN InputOnly -window must be zero, or a -.PN BadMatch -error results. -.PN XCreateSimpleWindow -inherits its depth, class, and visual from its parent. -All other window attributes, except background and border, -have their default values. -.LP -.PN XCreateSimpleWindow -can generate -.PN BadAlloc , -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.NH 2 -Destroying Windows -.XS -\*(SN Destroying Windows -.XE -.LP -Xlib provides functions that you can use to destroy a window or destroy all -subwindows of a window. -.LP -.sp -To destroy a window and all of its subwindows, use -.PN XDestroyWindow . -.IN "XDestroyWindow" "" "@DEF@" -.sM -.FD 0 -XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XDestroyWindow -function destroys the specified window as well as all of its subwindows and causes -the X server to generate a -.PN DestroyNotify -event for each window. -The window should never be referenced again. -If the window specified by the w argument is mapped, -it is unmapped automatically. -The ordering of the -.PN DestroyNotify -events is such that for any given window being destroyed, -.PN DestroyNotify -is generated on any inferiors of the window before being generated on -the window itself. -The ordering among siblings and across subhierarchies is not otherwise -constrained. -If the window you specified is a root window, no windows are destroyed. -Destroying a mapped window will generate -.PN Expose -events on other windows that were obscured by the window being destroyed. -.LP -.PN XDestroyWindow -can generate a -.PN BadWindow -error. -.LP -.sp -To destroy all subwindows of a specified window, use -.PN XDestroySubwindows . -.IN "XDestroySubwindows" "" "@DEF@" -.sM -.FD 0 -XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XDestroySubwindows -function destroys all inferior windows of the specified window, -in bottom-to-top stacking order. -It causes the X server to generate a -.PN DestroyNotify -event for each window. -If any mapped -subwindows were actually destroyed, -.PN XDestroySubwindows -causes the X server to generate -.PN Expose -events on the specified window. -This is much more efficient than deleting many windows -one at a time because much of the work need be performed only once for all -of the windows, rather than for each window. -The subwindows should never be referenced again. -.LP -.PN XDestroySubwindows -can generate a -.PN BadWindow -error. -.NH 2 -Mapping Windows -.XS -\*(SN Mapping Windows -.XE -.LP -A window is considered mapped if an -.PN XMapWindow -call has been made on it. -It may not be visible on the screen for one of the following reasons: -.IP \(bu 5 -It is obscured by another opaque window. -.IP \(bu 5 -One of its ancestors is not mapped. -.IP \(bu 5 -It is entirely clipped by an ancestor. -.LP -.PN Expose -events are generated for the window when part or all of -it becomes visible on the screen. -A client receives the -.PN Expose -events only if it has asked for them. -Windows retain their position in the stacking order when they are unmapped. -.LP -A window manager may want to control the placement of subwindows. -If -.PN SubstructureRedirectMask -has been selected by a window manager -on a parent window (usually a root window), -a map request initiated by other clients on a child window is not performed, -and the window manager is sent a -.PN MapRequest -event. -However, if the override-redirect flag on the child had been set to -.PN True -(usually only on pop-up menus), -the map request is performed. -.LP -A tiling window manager might decide to reposition and resize other clients' -windows and then decide to map the window to its final location. -A window manager that wants to provide decoration might -reparent the child into a frame first. -For further information, -see sections 3.2.8 and 10.10. -Only a single client at a time can select for -.PN SubstructureRedirectMask . -.LP -Similarly, a single client can select for -.PN ResizeRedirectMask -on a parent window. -Then, any attempt to resize the window by another client is suppressed, and -the client receives a -.PN ResizeRequest -event. -.LP -.sp -To map a given window, use -.PN XMapWindow . -.IN "XMapWindow" "" "@DEF@" -.sM -.FD 0 -XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XMapWindow -function -maps the window and all of its -subwindows that have had map requests. -Mapping a window that has an unmapped ancestor does not display the -window but marks it as eligible for display when the ancestor becomes -mapped. -Such a window is called unviewable. -When all its ancestors are mapped, -the window becomes viewable -and will be visible on the screen if it is not obscured by another window. -This function has no effect if the window is already mapped. -.LP -If the override-redirect of the window is -.PN False -and if some other client has selected -.PN SubstructureRedirectMask -on the parent window, then the X server generates a -.PN MapRequest -event, and the -.PN XMapWindow -function does not map the window. -Otherwise, the window is mapped, and the X server generates a -.PN MapNotify -event. -.LP -If the window becomes viewable and no earlier contents for it are remembered, -the X server tiles the window with its background. -If the window's background is undefined, -the existing screen contents are not -altered, and the X server generates zero or more -.PN Expose -events. -If backing-store was maintained while the window was unmapped, no -.PN Expose -events -are generated. -If backing-store will now be maintained, -a full-window exposure is always generated. -Otherwise, only visible regions may be reported. -Similar tiling and exposure take place for any newly viewable inferiors. -.LP -.IN "XMapWindow" -If the window is an -.PN InputOutput -window, -.PN XMapWindow -generates -.PN Expose -events on each -.PN InputOutput -window that it causes to be displayed. -If the client maps and paints the window -and if the client begins processing events, -the window is painted twice. -To avoid this, -first ask for -.PN Expose -events and then map the window, -so the client processes input events as usual. -The event list will include -.PN Expose -for each -window that has appeared on the screen. -The client's normal response to -an -.PN Expose -event should be to repaint the window. -This method usually leads to simpler programs and to proper interaction -with window managers. -.LP -.PN XMapWindow -can generate a -.PN BadWindow -error. -.LP -.sp -To map and raise a window, use -.PN XMapRaised . -.IN "XMapRaised" "" "@DEF@" -.sM -.FD 0 -XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XMapRaised -function -essentially is similar to -.PN XMapWindow -in that it maps the window and all of its -subwindows that have had map requests. -However, it also raises the specified window to the top of the stack. -For additional information, -see -.PN XMapWindow . -.LP -.PN XMapRaised -can generate multiple -.PN BadWindow -errors. -.LP -.sp -To map all subwindows for a specified window, use -.PN XMapSubwindows . -.IN "XMapSubwindows" "" "@DEF@" -.sM -.FD 0 -XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XMapSubwindows -.IN "XMapSubwindows" -function maps all subwindows for a specified window in top-to-bottom stacking -order. -The X server generates -.PN Expose -events on each newly displayed window. -This may be much more efficient than mapping many windows -one at a time because the server needs to perform much of the work -only once, for all of the windows, rather than for each window. -.LP -.PN XMapSubwindows -can generate a -.PN BadWindow -error. -.NH 2 -Unmapping Windows -.XS -\*(SN Unmapping Windows -.XE -.LP -Xlib provides functions that you can use to unmap a window or all subwindows. -.LP -.sp -To unmap a window, use -.PN XUnmapWindow . -.IN "XUnmapWindow" "" "@DEF@" -.sM -.FD 0 -XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XUnmapWindow -function unmaps the specified window and causes the X server to generate an -.PN UnmapNotify -.IN "UnmapNotify Event" -.IN "XUnmapWindow" -event. -If the specified window is already unmapped, -.PN XUnmapWindow -has no effect. -Normal exposure processing on formerly obscured windows is performed. -Any child window will no longer be visible until another map call is -made on the parent. -In other words, the subwindows are still mapped but are not visible -until the parent is mapped. -Unmapping a window will generate -.PN Expose -events on windows that were formerly obscured by it. -.LP -.PN XUnmapWindow -can generate a -.PN BadWindow -error. -.LP -.sp -To unmap all subwindows for a specified window, use -.PN XUnmapSubwindows . -.IN "XUnmapSubwindows" "" "@DEF@" -.sM -.FD 0 -XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XUnmapSubwindows -function unmaps all subwindows for the specified window in bottom-to-top -stacking order. -It causes the X server to generate an -.PN UnmapNotify -event on each subwindow and -.PN Expose -events on formerly obscured windows. -.IN "UnmapNotify Event" -Using this function is much more efficient than unmapping multiple windows -one at a time because the server needs to perform much of the work -only once, for all of the windows, rather than for each window. -.LP -.PN XUnmapSubwindows -can generate a -.PN BadWindow -error. -.NH 2 -Configuring Windows -.XS -\*(SN Configuring Windows -.XE -.LP -.LP -Xlib provides functions that you can use to -move a window, resize a window, move and resize a window, or -change a window's border width. -To change one of these parameters, -set the appropriate member of the -.PN XWindowChanges -structure and OR in the corresponding value mask in subsequent calls to -.PN XConfigureWindow . -The symbols for the value mask bits and the -.PN XWindowChanges -structure are: -.sM -.LP -/* Configure window value mask bits */ -.TS -lw(.5i) lw(2.5i) lw(.8i). -T{ -#define -T} T{ -.PN CWX -T} T{ -(1<<0) -T} -T{ -#define -T} T{ -.PN CWY -T} T{ -(1<<1) -T} -T{ -#define -T} T{ -.PN CWWidth -T} T{ -(1<<2) -T} -T{ -#define -T} T{ -.PN CWHeight -T} T{ -(1<<3) -T} -T{ -#define -T} T{ -.PN CWBorderWidth -T} T{ -(1<<4) -T} -T{ -#define -T} T{ -.PN CWSibling -T} T{ -(1<<5) -T} -T{ -#define -T} T{ -.PN CWStackMode -T} T{ -(1<<6) -T} -.TE -.IN "XWindowChanges" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -/* Values */ - -typedef struct { - int x, y; - int width, height; - int border_width; - Window sibling; - int stack_mode; -} XWindowChanges; -.De -.LP -.eM -The x and y members are used to set the window's x and y coordinates, -which are relative to the parent's origin -and indicate the position of the upper-left outer corner of the window. -The width and height members are used to set the inside size of the window, -not including the border, and must be nonzero, or a -.PN BadValue -error results. -Attempts to configure a root window have no effect. -.LP -The border_width member is used to set the width of the border in pixels. -Note that setting just the border width leaves the outer-left corner of the window -in a fixed position but moves the absolute position of the window's origin. -If you attempt to set the border-width attribute of an -.PN InputOnly -window nonzero, a -.PN BadMatch -error results. -.LP -The sibling member is used to set the sibling window for stacking operations. -The stack_mode member is used to set how the window is to be restacked -and can be set to -.PN Above , -.PN Below , -.PN TopIf , -.PN BottomIf , -or -.PN Opposite . -.LP -If the override-redirect flag of the window is -.PN False -and if some other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates a -.PN ConfigureRequest -event, and no further processing is performed. -Otherwise, -if some other client has selected -.PN ResizeRedirectMask -on the window and the inside -width or height of the window is being changed, -a -.PN ResizeRequest -event is generated, and the current inside width and height are -used instead. -Note that the override-redirect flag of the window has no effect -on -.PN ResizeRedirectMask -and that -.PN SubstructureRedirectMask -on the parent has precedence over -.PN ResizeRedirectMask -on the window. -.LP -When the geometry of the window is changed as specified, -the window is restacked among siblings, and a -.PN ConfigureNotify -event is generated if the state of the window actually changes. -.PN GravityNotify -events are generated after -.PN ConfigureNotify -events. -If the inside width or height of the window has actually changed, -children of the window are affected as specified. -.LP -If a window's size actually changes, -the window's subwindows move according to their window gravity. -Depending on the window's bit gravity, -the contents of the window also may be moved (see section 3.2.3). -.LP -If regions of the window were obscured but now are not, -exposure processing is performed on these formerly obscured windows, -including the window itself and its inferiors. -As a result of increasing the width or height, -exposure processing is also performed on any new regions of the window -and any regions where window contents are lost. -.LP -The restack check (specifically, the computation for -.PN BottomIf , -.PN TopIf , -and -.PN Opposite ) -is performed with respect to the window's final size and position (as -controlled by the other arguments of the request), not its initial position. -If a sibling is specified without a stack_mode, -a -.PN BadMatch -error results. -.LP -If a sibling and a stack_mode are specified, -the window is restacked as follows: -.TS -lw(1i) lw(5i). -T{ -.PN Above -T} T{ -The window is placed just above the sibling. -T} -.sp 6p -T{ -.PN Below -T} T{ -The window is placed just below the sibling. -T} -.sp 6p -T{ -.PN TopIf -T} T{ -If the sibling occludes the window, the window is placed -at the top of the stack. -T} -.sp 6p -T{ -.PN BottomIf -T} T{ -If the window occludes the sibling, the window is -placed at the bottom of the stack. -T} -.sp 6p -T{ -.PN Opposite -T} T{ -If the sibling occludes the window, the window -is placed at the top of the stack. -If the window occludes the sibling, -the window is placed at the bottom of the stack. -T} -.TE -.LP -If a stack_mode is specified but no sibling is specified, -the window is restacked as follows: -.TS -lw(1i) lw(5i). -T{ -.PN Above -T} T{ -The window is placed at the top of the stack. -T} -.sp 6p -T{ -.PN Below -T} T{ -The window is placed at the bottom of the stack. -T} -.sp 6p -T{ -.PN TopIf -T} T{ -If any sibling occludes the window, the window is placed at -the top of the stack. -T} -.sp 6p -T{ -.PN BottomIf -T} T{ -If the window occludes any sibling, the window is placed at -the bottom of the stack. -T} -.sp 6p -T{ -.PN Opposite -T} T{ -If any sibling occludes the window, the window -is placed at the top of the stack. -If the window occludes any sibling, -the window is placed at the bottom of the stack. -T} -.TE -.LP -Attempts to configure a root window have no effect. -.LP -.sp -To configure a window's size, location, stacking, or border, use -.PN XConfigureWindow . -.IN "XConfigureWindow" "" "@DEF@" -.sM -.FD 0 -XConfigureWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvalue_mask\fP\^, \fIvalues\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - unsigned int \fIvalue_mask\fP\^; -.br - XWindowChanges *\fIvalues\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi to be reconfigured -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIvalue_mask\fP 1i -Specifies which values are to be set using information in -the values structure. -This mask is the bitwise inclusive OR of the valid configure window values bits. -.IP \fIvalues\fP 1i -Specifies the -.PN XWindowChanges -structure. -.LP -.eM -The -.PN XConfigureWindow -function uses the values specified in the -.PN XWindowChanges -structure to reconfigure a window's size, position, border, and stacking order. -Values not specified are taken from the existing geometry of the window. -.LP -If a sibling is specified without a stack_mode or if the window -is not actually a sibling, -a -.PN BadMatch -error results. -Note that the computations for -.PN BottomIf , -.PN TopIf , -and -.PN Opposite -are performed with respect to the window's final geometry (as controlled by the -other arguments passed to -.PN XConfigureWindow ), -not its initial geometry. -Any backing store contents of the window, its -inferiors, and other newly visible windows are either discarded or -changed to reflect the current screen contents -(depending on the implementation). -.LP -.PN XConfigureWindow -can generate -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To move a window without changing its size, use -.PN XMoveWindow . -.IN "XMoveWindow" "" "@DEF@" -.sM -.FD 0 -XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi to be moved -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.ds Xy , which define the new location of the top-left pixel \ -of the window's border or the window itself if it has no border -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.LP -.eM -The -.PN XMoveWindow -function moves the specified window to the specified x and y coordinates, -but it does not change the window's size, raise the window, or -change the mapping state of the window. -Moving a mapped window may or may not lose the window's contents -depending on if the window is obscured by nonchildren -and if no backing store exists. -If the contents of the window are lost, -the X server generates -.PN Expose -events. -Moving a mapped window generates -.PN Expose -events on any formerly obscured windows. -.LP -If the override-redirect flag of the window is -.PN False -and some -other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates a -.PN ConfigureRequest -event, and no further processing is -performed. -Otherwise, the window is moved. -.LP -.PN XMoveWindow -can generate a -.PN BadWindow -error. -.LP -.sp -To change a window's size without changing the upper-left coordinate, use -.PN XResizeWindow . -.IN "XResizeWindow" "" "@DEF@" -.sM -.FD 0 -XResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwidth\fP\^, \fIheight\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.ds Wh , which are the interior dimensions of the window \ -after the call completes -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.LP -.eM -The -.PN XResizeWindow -function changes the inside dimensions of the specified window, not including -its borders. -This function does not change the window's upper-left coordinate or -the origin and does not restack the window. -Changing the size of a mapped window may lose its contents and generate -.PN Expose -events. -If a mapped window is made smaller, -changing its size generates -.PN Expose -events on windows that the mapped window formerly obscured. -.LP -If the override-redirect flag of the window is -.PN False -and some -other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates a -.PN ConfigureRequest -event, and no further processing is performed. -If either width or height is zero, -a -.PN BadValue -error results. -.LP -.PN XResizeWindow -can generate -.PN BadValue -and -.PN BadWindow -errors. -.LP -.sp -To change the size and location of a window, use -.PN XMoveResizeWindow . -.IN "XMoveResizeWindow" "" "@DEF@" -.sM -.FD 0 -XMoveResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi to be reconfigured -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.ds Xy , which define the new position of the window relative to its parent -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which define the interior size of the window -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.LP -.eM -The -.PN XMoveResizeWindow -function changes the size and location of the specified window -without raising it. -Moving and resizing a mapped window may generate an -.PN Expose -event on the window. -Depending on the new size and location parameters, -moving and resizing a window may generate -.PN Expose -events on windows that the window formerly obscured. -.LP -If the override-redirect flag of the window is -.PN False -and some -other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates a -.PN ConfigureRequest -event, and no further processing is performed. -Otherwise, the window size and location are changed. -.LP -.PN XMoveResizeWindow -can generate -.PN BadValue -and -.PN BadWindow -errors. -.LP -.sp -To change the border width of a given window, use -.PN XSetWindowBorderWidth . -.IN "XSetWindowBorderWidth" "" "@DEF@" -.sM -.FD 0 -XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - unsigned int \fIwidth\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwidth\fP 1i -Specifies the width of the window border. -.LP -.eM -The -.PN XSetWindowBorderWidth -function sets the specified window's border width to the specified width. -.LP -.PN XSetWindowBorderWidth -can generate a -.PN BadWindow -error. -.NH 2 -Changing Window Stacking Order -.XS -\*(SN Changing Window Stacking Order -.XE -.LP -.LP -Xlib provides functions that you can use to raise, lower, circulate, -or restack windows. -.LP -.sp -To raise a window so that no sibling window obscures it, use -.PN XRaiseWindow . -.IN "XRaiseWindow" "" "@DEF@" -.sM -.FD 0 -XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XRaiseWindow -function -raises the specified window to the top of the stack so that no sibling window -obscures it. -If the windows are regarded as overlapping sheets of paper stacked -on a desk, -then raising a window is analogous to moving the sheet to the top of -the stack but leaving its x and y location on the desk constant. -Raising a mapped window may generate -.PN Expose -events for the window and any mapped subwindows that were formerly obscured. -.LP -If the override-redirect attribute of the window is -.PN False -and some -other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates a -.PN ConfigureRequest -event, and no processing is performed. -Otherwise, the window is raised. -.LP -.PN XRaiseWindow -can generate a -.PN BadWindow -error. -.LP -.sp -To lower a window so that it does not obscure any sibling windows, use -.PN XLowerWindow . -.IN "XLowerWindow" "" "@DEF@" -.sM -.FD 0 -XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XLowerWindow -function lowers the specified window to the bottom of the stack -so that it does not obscure any sibling -windows. -If the windows are regarded as overlapping sheets of paper -stacked on a desk, then lowering a window is analogous to moving the -sheet to the bottom of the stack but leaving its x and y location on -the desk constant. -Lowering a mapped window will generate -.PN Expose -events on any windows it formerly obscured. -.LP -If the override-redirect attribute of the window is -.PN False -and some -other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates a -.PN ConfigureRequest -event, and no processing is performed. -Otherwise, the window is lowered to the bottom of the -stack. -.LP -.PN XLowerWindow -can generate a -.PN BadWindow -error. -.LP -.sp -To circulate a subwindow up or down, use -.PN XCirculateSubwindows . -.IN "XCirculateSubwindows" "" "@DEF@" -.sM -.FD 0 -XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIdirection\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIdirection\fP 1i -Specifies the direction (up or down) that you want to circulate -the window. -You can pass -.PN RaiseLowest -or -.PN LowerHighest . -.LP -.eM -The -.PN XCirculateSubwindows -function circulates children of the specified window in the specified -direction. -If you specify -.PN RaiseLowest , -.PN XCirculateSubwindows -raises the lowest mapped child (if any) that is occluded -by another child to the top of the stack. -If you specify -.PN LowerHighest , -.PN XCirculateSubwindows -lowers the highest mapped child (if any) that occludes another child -to the bottom of the stack. -Exposure processing is then performed on formerly obscured windows. -If some other client has selected -.PN SubstructureRedirectMask -on the window, the X server generates a -.PN CirculateRequest -event, and no further processing is performed. -If a child is actually restacked, -the X server generates a -.PN CirculateNotify -event. -.LP -.PN XCirculateSubwindows -can generate -.PN BadValue -and -.PN BadWindow -errors. -.LP -.sp -To raise the lowest mapped child of a window that is partially or completely -occluded by another child, use -.PN XCirculateSubwindowsUp . -.IN "XCirculateSubwindowsUp" "" "@DEF@" -.sM -.FD 0 -XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XCirculateSubwindowsUp -function raises the lowest mapped child of the specified window that -is partially -or completely -occluded by another child. -Completely unobscured children are not affected. -This is a convenience function equivalent to -.PN XCirculateSubwindows -with -.PN RaiseLowest -specified. -.LP -.PN XCirculateSubwindowsUp -can generate a -.PN BadWindow -error. -.LP -.sp -To lower the highest mapped child of a window that partially or -completely occludes another child, use -.PN XCirculateSubwindowsDown . -.IN "XCirculateSubwindowsDown" "" "@DEF@" -.sM -.FD 0 -XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XCirculateSubwindowsDown -function lowers the highest mapped child of the specified window that partially -or completely occludes another child. -Completely unobscured children are not affected. -This is a convenience function equivalent to -.PN XCirculateSubwindows -with -.PN LowerHighest -specified. -.LP -.PN XCirculateSubwindowsDown -can generate a -.PN BadWindow -error. -.LP -.sp -To restack a set of windows from top to bottom, use -.PN XRestackWindows . -.IN "XRestackWindows" "" "@DEF@" -.sM -.FD 0 -XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^); -.br - Display *\fIdisplay\fP\^; -.br - Window \fIwindows\fP\^[]; -.br - int \fInwindows\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIwindows\fP 1i -Specifies an array containing the windows to be restacked. -.IP \fInwindows\fP 1i -Specifies the number of windows to be restacked. -.LP -.eM -The -.PN XRestackWindows -function restacks the windows in the order specified, -from top to bottom. -The stacking order of the first window in the windows array is unaffected, -but the other windows in the array are stacked underneath the first window, -in the order of the array. -The stacking order of the other windows is not affected. -For each window in the window array that is not a child of the specified window, -a -.PN BadMatch -error results. -.LP -If the override-redirect attribute of a window is -.PN False -and some -other client has selected -.PN SubstructureRedirectMask -on the parent, the X server generates -.PN ConfigureRequest -events for each window whose override-redirect flag is not set, -and no further processing is performed. -Otherwise, the windows will be restacked in top-to-bottom order. -.LP -.PN XRestackWindows -can generate a -.PN BadWindow -error. -.NH 2 -Changing Window Attributes -.XS -\*(SN Changing Window Attributes -.XE -.LP -.LP -Xlib provides functions that you can use to set window attributes. -.PN XChangeWindowAttributes -is the more general function that allows you to set one or more window -attributes provided by the -.PN XSetWindowAttributes -structure. -The other functions described in this section allow you to set one specific -window attribute, such as a window's background. -.LP -.sp -To change one or more attributes for a given window, use -.PN XChangeWindowAttributes . -.IN "XChangeWindowAttributes" "" "@DEF@" -.sM -.FD 0 -XChangeWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - unsigned long \fIvaluemask\fP\^; -.br - XSetWindowAttributes *\fIattributes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIvaluemask\fP 1i -Specifies which window attributes are defined in the attributes -argument. -This mask is the bitwise inclusive OR of the valid attribute mask bits. -If valuemask is zero, -the attributes are ignored and are not referenced. -The values and restrictions are -the same as for -.PN XCreateWindow . -.IP -.IP \fIattributes\fP 1i -Specifies the structure from which the values (as specified by the value mask) -are to be taken. -The value mask should have the appropriate bits -set to indicate which attributes have been set in the structure -(see section 3.2). -.LP -.eM -Depending on the valuemask, -the -.PN XChangeWindowAttributes -function uses the window attributes in the -.PN XSetWindowAttributes -structure to change the specified window attributes. -Changing the background does not cause the window contents to be -changed. -To repaint the window and its background, use -.PN XClearWindow . -Setting the border or changing the background such that the -border tile origin changes causes the border to be repainted. -Changing the background of a root window to -.PN None -or -.PN ParentRelative -restores the default background pixmap. -Changing the border of a root window to -.PN CopyFromParent -restores the default border pixmap. -Changing the win-gravity does not affect the current position of the -window. -Changing the backing-store of an obscured window to -.PN WhenMapped -or -.PN Always , -or changing the backing-planes, backing-pixel, or -save-under of a mapped window may have no immediate effect. -Changing the colormap of a window (that is, defining a new map, not -changing the contents of the existing map) generates a -.PN ColormapNotify -event. -Changing the colormap of a visible window may have no -immediate effect on the screen because the map may not be installed -(see -.PN XInstallColormap ). -Changing the cursor of a root window to -.PN None -restores the default -cursor. -Whenever possible, you are encouraged to share colormaps. -.LP -Multiple clients can select input on the same window. -Their event masks are maintained separately. -When an event is generated, -it is reported to all interested clients. -However, only one client at a time can select for -.PN SubstructureRedirectMask , -.PN ResizeRedirectMask , -and -.PN ButtonPressMask . -If a client attempts to select any of these event masks -and some other client has already selected one, -a -.PN BadAccess -error results. -There is only one do-not-propagate-mask for a window, -not one per client. -.LP -.PN XChangeWindowAttributes -can generate -.PN BadAccess , -.PN BadColor , -.PN BadCursor , -.PN BadMatch , -.PN BadPixmap , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To set the background of a window to a given pixel, use -.PN XSetWindowBackground . -.IN "XSetWindowBackground" "" "@DEF@" -.sM -.FD 0 -XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - unsigned long \fIbackground_pixel\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIbackground_pixel\fP 1i -Specifies the pixel that is to be used for the background. -.LP -.eM -The -.PN XSetWindowBackground -function sets the background of the window to the specified pixel value. -Changing the background does not cause the window contents to be changed. -.PN XSetWindowBackground -uses a pixmap of undefined size filled with the pixel value you passed. -If you try to change the background of an -.PN InputOnly -window, a -.PN BadMatch -error results. -.LP -.PN XSetWindowBackground -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.LP -.sp -.LP -To set the background of a window to a given pixmap, use -.PN XSetWindowBackgroundPixmap . -.IN "Window" "background" -.IN "XSetWindowBackgroundPixmap" "" "@DEF@" -.sM -.FD 0 -XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Pixmap \fIbackground_pixmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIbackground_pixmap\fP 1i -Specifies the background pixmap, -.PN ParentRelative , -or -.PN None . -.LP -.eM -.IN "Resource IDs" "freeing" -.IN "Freeing" "resources" -The -.PN XSetWindowBackgroundPixmap -function sets the background pixmap of the window to the specified pixmap. -The background pixmap can immediately be freed if no further explicit -references to it are to be made. -If -.PN ParentRelative -is specified, -the background pixmap of the window's parent is used, -or on the root window, the default background is restored. -If you try to change the background of an -.PN InputOnly -window, a -.PN BadMatch -error results. -If the background is set to -.PN None , -the window has no defined background. -.LP -.PN XSetWindowBackgroundPixmap -can generate -.PN BadMatch , -.PN BadPixmap , -and -.PN BadWindow -errors. -.NT Note -.PN XSetWindowBackground -and -.PN XSetWindowBackgroundPixmap -do not change the current contents of the window. -.NE -.LP -.sp -To change and repaint a window's border to a given pixel, use -.PN XSetWindowBorder . -.IN "XSetWindowBorder" "" "@DEF@" -.sM -.FD 0 -XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - unsigned long \fIborder_pixel\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIborder_pixel\fP 1i -Specifies the entry in the colormap. -.LP -.eM -The -.PN XSetWindowBorder -function sets the border of the window to the pixel value you specify. -If you attempt to perform this on an -.PN InputOnly -window, a -.PN BadMatch -error results. -.LP -.PN XSetWindowBorder -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.LP -.sp -To change and repaint the border tile of a given window, use -.PN XSetWindowBorderPixmap . -.IN "XSetWindowBorderPixmap" "" "@DEF@" -.sM -.FD 0 -XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Pixmap \fIborder_pixmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIborder_pixmap\fP 1i -Specifies the border pixmap or -.PN CopyFromParent . -.LP -.eM -The -.PN XSetWindowBorderPixmap -function sets the border pixmap of the window to the pixmap you specify. -The border pixmap can be freed immediately if no further explicit -references to it are to be made. -If you specify -.PN CopyFromParent , -a copy of the parent window's border pixmap is used. -If you attempt to perform this on an -.PN InputOnly -window, a -.PN BadMatch -error results. -.IN "Resource IDs" "freeing" -.IN "Freeing" "resources" -.LP -.PN XSetWindowBorderPixmap -can generate -.PN BadMatch , -.PN BadPixmap , -and -.PN BadWindow -errors. -.LP -.sp -To set the colormap of a given window, use -.PN XSetWindowColormap . -.IN "XSetWindowColormap" "" "@DEF@" -.sM -.FD 0 -XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XSetWindowColormap -function sets the specified colormap of the specified window. -The colormap must have the same visual type as the window, -or a -.PN BadMatch -error results. -.LP -.PN XSetWindowColormap -can generate -.PN BadColor , -.PN BadMatch , -and -.PN BadWindow -errors. -.LP -.sp -To define which cursor will be used in a window, use -.PN XDefineCursor . -.IN "Window" "defining the cursor" -.IN "XDefineCursor" "" "@DEF@" -.sM -.FD 0 -XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Cursor \fIcursor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIcursor\fP 1i -Specifies the cursor that is to be displayed or -.PN None . -.LP -.eM -If a cursor is set, it will be used when the pointer is in the window. -If the cursor is -.PN None , -it is equivalent to -.PN XUndefineCursor . -.LP -.PN XDefineCursor -can generate -.PN BadCursor -and -.PN BadWindow -errors. -.LP -.sp -To undefine the cursor in a given window, use -.PN XUndefineCursor . -.IN "Window" "undefining the cursor" -.IN "XUndefineCursor" "" "@DEF@" -.sM -.FD 0 -XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XUndefineCursor -function undoes the effect of a previous -.PN XDefineCursor -for this window. -When the pointer is in the window, -the parent's cursor will now be used. -On the root window, -the default cursor is restored. -.LP -.PN XUndefineCursor -can generate a -.PN BadWindow -error. -.bp diff --git a/libX11/specs/libX11/CH03.xml b/libX11/specs/libX11/CH03.xml new file mode 100644 index 000000000..a90a06821 --- /dev/null +++ b/libX11/specs/libX11/CH03.xml @@ -0,0 +1,4162 @@ +<chapter id="window_functions"><title>Window Functions</title>
+<sect1 id="Visual_Types">
+<title>Visual Types</title>
+<!-- .XS -->
+<!-- (SN Visual Types -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Visual Type</primary></indexterm>
+On some display hardware,
+it may be possible to deal with color resources in more than one way.
+For example, you may be able to deal with a screen of either 12-bit depth
+with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth
+with 8 bits of the pixel dedicated to each of red, green, and blue.
+These different ways of dealing with the visual aspects of the screen
+are called visuals.
+For each screen of the display, there may be a list of valid visual types
+supported at different depths of the screen.
+Because default windows and visual types are defined for each screen,
+most simple applications need not deal with this complexity.
+Xlib provides macros and functions that return the default root window,
+the default depth of the default root window, and the default visual type
+(see sections 2.2.1 and 16.7).
+</para>
+<para>
+<!-- .LP -->
+Xlib uses an opaque
+<function>Visual </function>
+<indexterm significance="preferred"><primary>Visual</primary></indexterm>
+structure that contains information about the possible color mapping.
+The visual utility functions (see section 16.7) use an
+<function>XVisualInfo</function>
+structure to return this information to an application.
+The members of this structure pertinent to this discussion are class, red_mask,
+green_mask, blue_mask, bits_per_rgb, and colormap_size.
+The class member specifies one of the possible visual classes of the screen
+and can be
+<indexterm><primary>Visual Classes</primary><secondary>StaticGray</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>TrueColor</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>GrayScale</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>PseudoColor</secondary></indexterm>
+<function>StaticGray</function>,
+<function>StaticColor</function>,
+<function>TrueColor</function>,
+<function>GrayScale</function>,
+<function>PseudoColor</function>,
+or
+<function>DirectColor</function>.
+</para>
+<para>
+<!-- .LP -->
+The following concepts may serve to make the explanation of
+visual types clearer.
+The screen can be color or grayscale,
+can have a colormap that is writable or read-only,
+and can also have a colormap whose indices are decomposed into separate
+<acronym>RGB</acronym> pieces, provided one is not on a grayscale screen.
+This leads to the following diagram:
+</para>
+
+<literallayout class="monospaced">
+ Color Gray-Scale
+ R/O R/W R/O R/W
+----------------------------------------------
+ Undecomposed Static Pseudo Static Gray
+ Colormap Color Color Gray Scale
+
+ Decomposed True Direct
+ Colormap Color Color
+----------------------------------------------
+</literallayout>
+
+<para>
+<!-- .LP -->
+Conceptually,
+as each pixel is read out of video memory for display on the screen,
+it goes through a look-up stage by indexing into a colormap.
+Colormaps can be manipulated arbitrarily on some hardware,
+in limited ways on other hardware, and not at all on other hardware.
+The visual types affect the colormap and
+the <acronym>RGB</acronym> values in the following ways:
+</para>
+<para>
+<!-- .LP -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+For
+<function>PseudoColor</function>,
+a pixel value indexes a colormap to produce
+independent <acronym>RGB</acronym> values, and the <acronym>RGB</acronym> values can be changed dynamically.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>GrayScale </function>
+is treated the same way as
+<function>PseudoColor </function>
+except that the primary that drives the screen is undefined.
+Thus, the client should always store the
+same value for red, green, and blue in the colormaps.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For
+<function>DirectColor</function>,
+a pixel value is decomposed into separate <acronym>RGB</acronym> subfields, and each
+subfield separately indexes the colormap for the corresponding value.
+The <acronym>RGB</acronym> values can be changed dynamically.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>TrueColor</function>
+is treated the same way as
+<function>DirectColor </function>
+except that the colormap has predefined, read-only <acronym>RGB</acronym> values.
+These <acronym>RGB</acronym> values are server dependent but provide linear or near-linear
+ramps in each primary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>StaticColor</function>
+is treated the same way as
+<function>PseudoColor </function>
+except that the colormap has predefined,
+read-only, server-dependent <acronym>RGB</acronym> values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>StaticGray </function>
+is treated the same way as
+<function>StaticColor </function>
+except that the <acronym>RGB</acronym> values are equal for any single pixel
+value, thus resulting in shades of gray.
+<function>StaticGray </function>
+with a two-entry
+colormap can be thought of as monochrome.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The red_mask, green_mask, and blue_mask members are only defined for
+<function>DirectColor</function>
+and
+<function>TrueColor</function>.
+Each has one contiguous set of bits with no
+intersections.
+The bits_per_rgb member specifies the log base 2 of the
+number of distinct color values (individually) of red, green, and blue.
+Actual <acronym>RGB</acronym> values are unsigned 16-bit numbers.
+The colormap_size member defines the number of available colormap entries
+in a newly created colormap.
+For
+<function>DirectColor </function>
+and
+<function>TrueColor</function>,
+this is the size of an individual pixel subfield.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the visual ID from a
+<function>Visual</function>,
+use
+<function>XVisualIDFromVisual</function>.
+<indexterm significance="preferred"><primary>XVisualIDFromVisual</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>VisualID<function> XVisualIDFromVisual</function></funcdef>
+ <paramdef>Visual<parameter> *\^visual</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual type.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XVisualIDFromVisual</function>
+function returns the visual ID for the specified visual type.
+</para>
+</sect1>
+<sect1 id="Window_Attributes">
+<title>Window Attributes</title>
+<!-- .XS -->
+<!-- (SN Window Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Window</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>attributes</secondary></indexterm>
+All
+<function>InputOutput</function>
+windows have a border width of zero or more pixels, an optional background,
+an event suppression mask (which suppresses propagation of events from
+children), and a property list (see section 4.3).
+The window border and background can be a solid color or a pattern, called
+a tile.
+All windows except the root have a parent and are clipped by their parent.
+If a window is stacked on top of another window, it obscures that other
+window for the purpose of input.
+If a window has a background (almost all do), it obscures the other
+window for purposes of output.
+Attempts to output to the obscured area do nothing,
+and no input events (for example, pointer motion) are generated for the
+obscured area.
+</para>
+<para>
+<!-- .LP -->
+Windows also have associated property lists (see section 4.3).
+</para>
+<para>
+<!-- .LP -->
+Both
+<function>InputOutput</function>
+and
+<function>InputOnly</function>
+windows have the following common attributes,
+which are the only attributes of an
+<function>InputOnly</function>
+window:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+win-gravity
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+event-mask
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+do-not-propagate-mask
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+override-redirect
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+cursor
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If you specify any other attributes for an
+<function>InputOnly</function>
+window,
+a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>InputOnly</function>
+windows are used for controlling input events in situations where
+<function>InputOutput</function>
+windows are unnecessary.
+<function>InputOnly</function>
+windows are invisible; can only be used to control such things as
+cursors, input event generation, and grabbing;
+and cannot be used in any graphics requests.
+Note that
+<function>InputOnly</function>
+windows cannot have
+<function>InputOutput</function>
+windows as inferiors.
+</para>
+<para>
+<!-- .LP -->
+Windows have borders of a programmable width and pattern
+as well as a background pattern or tile.
+<indexterm><primary>Tile</primary><secondary>pixmaps</secondary></indexterm>
+Pixel values can be used for solid colors.
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+The background and border pixmaps can be destroyed immediately after
+creating the window if no further explicit references to them
+are to be made.
+<indexterm ><primary>Tile</primary><secondary>mode</secondary></indexterm>
+The pattern can either be relative to the parent
+or absolute.
+If
+<function>ParentRelative</function>,
+the parent's background is used.
+</para>
+<para>
+<!-- .LP -->
+When windows are first created,
+they are not visible (not mapped) on the screen.
+Any output to a window that is not visible on the screen
+and that does not have backing store will be discarded.
+<indexterm><primary>Window</primary><secondary>mapping</secondary></indexterm>
+An application may wish to create a window long before it is
+mapped to the screen.
+When a window is eventually mapped to the screen
+(using
+<function>XMapWindow</function>),
+<indexterm><primary>XMapWindow</primary></indexterm>
+the X server generates an
+<function>Expose </function>
+event for the window if backing store has not been maintained.
+</para>
+<para>
+<!-- .LP -->
+A window manager can override your choice of size,
+border width, and position for a top-level window.
+Your program must be prepared to use the actual size and position
+of the top window.
+It is not acceptable for a client application to resize itself
+unless in direct response to a human command to do so.
+Instead, either your program should use the space given to it,
+or if the space is too small for any useful work, your program
+might ask the user to resize the window.
+The border of your top-level window is considered fair game
+for window managers.
+</para>
+<para>
+<!-- .LP -->
+To set an attribute of a window,
+set the appropriate member of the
+<function>XSetWindowAttributes</function>
+structure and OR in the corresponding value bitmask in your subsequent calls to
+<function>XCreateWindow</function>
+and
+<function>XChangeWindowAttributes</function>,
+or use one of the other convenience functions that set the appropriate
+attribute.
+The symbols for the value mask bits and the
+<function>XSetWindowAttributes</function>
+structure are:
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+/* Window attribute value mask bits */
+
+
+<literallayout class="monospaced">
+/* Window attribute value mask bits */
+#define CWBackPixmap (1L<<0)
+#define CWBackPixel (1L<<1)
+#define CWBorderPixmap (1L<<2)
+#define CWBorderPixel (1L<<3)
+#define CWBitGravity (1L<<4)
+#define CWWinGravity (1L<<5)
+#define CWBackingStore (1L<<6)
+#define CWBackingPlanes (1L<<7)
+#define CWBackingPixel (1L<<8)
+#define CWOverrideRedirect (1L<<9)
+#define CWSaveUnder (1L<<10)
+#define CWEventMask (1L<<11)
+#define CWDontPropagate (1L<<12)
+#define CWColormap (1L<<13)
+#define CWCursor (1L<<14)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XSetWindowAttributes</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* Values */
+
+typedef struct {
+ Pixmap background_pixmap; /* background, None, or ParentRelative */
+ unsigned long background_pixel; /* background pixel */
+ Pixmap border_pixmap; /* border of the window or CopyFromParent */
+ unsigned long border_pixel; /* border pixel value */
+ int bit_gravity; /* one of bit gravity values */
+ int win_gravity; /* one of the window gravity values */
+ int backing_store; /* NotUseful, WhenMapped, Always */
+ unsigned long backing_planes; /* planes to be preserved if possible */
+ unsigned long backing_pixel; /* value to use in restoring planes */
+ Bool save_under; /* should bits under be saved? (popups) */
+ long event_mask; /* set of events that should be saved */
+ long do_not_propagate_mask; /* set of events that should not propagate */
+ Bool override_redirect; /* boolean value for override_redirect */
+ Colormap colormap; /* color map to be associated with window */
+ Cursor cursor; /* cursor to be displayed (or None) */
+} XSetWindowAttributes;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The following lists the defaults for each window attribute and indicates
+whether the attribute is applicable to
+<function>InputOutput</function>
+and
+<function>InputOnly</function>
+windows:
+</para>
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Default</entry>
+ <entry>InputOutput</entry>
+ <entry>nputOnly</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>background-pixmap</entry>
+ <entry><function>None</function></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>background-pixel</entry>
+ <entry>Undefined</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>border-pixmap</entry>
+ <entry><function>CopyFromParent</function></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>border-pixel</entry>
+ <entry>Undefined</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>bit-gravity</entry>
+ <entry><function>ForgetGravity</function></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>win-gravity</entry>
+ <entry><function>NorthWestGravity</function></entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>backing-store</entry>
+ <entry><function>NotUseful</function></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>backing-planes</entry>
+ <entry>All ones</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>backing-pixel</entry>
+ <entry>zero</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>save-under</entry>
+ <entry><function>False</function></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>event-mask</entry>
+ <entry>empty set</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>do-not-propagate-mask</entry>
+ <entry>empty set</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>override-redirect</entry>
+ <entry><function>False</function></entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry><function>CopyFromParent</function></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry><function>None</function></entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<sect2 id="Background_Attribute">
+<title>Background Attribute</title>
+<!-- .XS -->
+<!-- (SN Background Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Only
+<function>InputOutput</function>
+windows can have a background.
+You can set the background of an
+<function>InputOutput</function>
+window by using a pixel or a pixmap.
+</para>
+<para>
+<!-- .LP -->
+The background-pixmap attribute of a window specifies the pixmap to be used for
+a window's background.
+This pixmap can be of any size, although some sizes may be faster than others.
+The background-pixel attribute of a window specifies a pixel value used to paint
+a window's background in a single color.
+</para>
+<para>
+<!-- .LP -->
+You can set the background-pixmap to a pixmap,
+<function>None </function>
+(default), or
+<function>ParentRelative</function>.
+You can set the background-pixel of a window to any pixel value (no default).
+If you specify a background-pixel,
+it overrides either the default background-pixmap
+or any value you may have set in the background-pixmap.
+A pixmap of an undefined size that is filled with the background-pixel is used
+for the background.
+Range checking is not performed on the background pixel;
+it simply is truncated to the appropriate number of bits.
+</para>
+<para>
+<!-- .LP -->
+If you set the background-pixmap,
+it overrides the default.
+The background-pixmap and the window must have the same depth,
+or a
+<function>BadMatch</function>
+error results.
+If you set background-pixmap to
+<function>None</function>,
+the window has no defined background.
+If you set the background-pixmap to
+<function>ParentRelative :</function>
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The parent window's background-pixmap is used.
+The child window, however, must have the same depth as
+its parent,
+or a
+<function>BadMatch</function>
+error results.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent window has a background-pixmap of
+<function>None</function>,
+the window also has a background-pixmap of
+<function>None</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A copy of the parent window's background-pixmap is not made.
+The parent's background-pixmap is examined each time the child window's
+background-pixmap is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The background tile origin always aligns with the parent window's
+background tile origin.
+If the background-pixmap is not
+<function>ParentRelative</function>,
+the background tile origin is the child window's origin.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Setting a new background, whether by setting background-pixmap or
+background-pixel, overrides any previous background.
+The background-pixmap can be freed immediately if no further explicit reference
+is made to it (the X server will keep a copy to use when needed).
+If you later draw into the pixmap used for the background,
+what happens is undefined because the
+X implementation is free to make a copy of the pixmap or
+to use the same pixmap.
+</para>
+<para>
+<!-- .LP -->
+When no valid contents are available for regions of a window
+and either the regions are visible or the server is maintaining backing store,
+the server automatically tiles the regions with the window's background
+unless the window has a background of
+<function>None</function>.
+If the background is
+<function>None</function>,
+the previous screen contents from other windows of the same depth as the window
+are simply left in place as long as the contents come from the parent of the
+window or an inferior of the parent.
+Otherwise, the initial contents of the exposed regions are undefined.
+<function>Expose </function>
+events are then generated for the regions, even if the background-pixmap
+is
+<function>None </function>
+(see section 10.9).
+</para>
+</sect2>
+<sect2 id="Border_Attribute">
+<title>Border Attribute</title>
+<!-- .XS -->
+<!-- (SN Border Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Only
+<function>InputOutput</function>
+windows can have a border.
+You can set the border of an
+<function>InputOutput</function>
+window by using a pixel or a pixmap.
+</para>
+<para>
+<!-- .LP -->
+The border-pixmap attribute of a window specifies the pixmap to be used
+for a window's border.
+The border-pixel attribute of a window specifies a pixmap of undefined size
+filled with that pixel be used for a window's border.
+Range checking is not performed on the background pixel;
+it simply is truncated to the appropriate number of bits.
+The border tile origin is always the same as the background tile origin.
+</para>
+<para>
+<!-- .LP -->
+You can also set the border-pixmap to a pixmap of any size (some may be faster
+than others) or to
+<function>CopyFromParent </function>
+(default).
+You can set the border-pixel to any pixel value (no default).
+</para>
+<para>
+<!-- .LP -->
+If you set a border-pixmap,
+it overrides the default.
+The border-pixmap and the window must have the same depth,
+or a
+<function>BadMatch</function>
+error results.
+If you set the border-pixmap to
+<function>CopyFromParent</function>,
+the parent window's border-pixmap is copied.
+Subsequent changes to the parent window's border attribute do not affect
+the child window.
+However, the child window must have the same depth as the parent window,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The border-pixmap can be freed immediately if no further explicit reference
+is made to it.
+If you later draw into the pixmap used for the border,
+what happens is undefined because the
+X implementation is free either to make a copy of the pixmap or
+to use the same pixmap.
+If you specify a border-pixel,
+it overrides either the default border-pixmap
+or any value you may have set in the border-pixmap.
+All pixels in the window's border will be set to the border-pixel.
+Setting a new border, whether by setting border-pixel or by setting
+border-pixmap, overrides any previous border.
+</para>
+<para>
+<!-- .LP -->
+Output to a window is always clipped to the inside of the window.
+Therefore, graphics operations never affect the window border.
+</para>
+</sect2>
+<sect2 id="Gravity_Attributes">
+<title>Gravity Attributes</title>
+<!-- .XS -->
+<!-- (SN Gravity Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The bit gravity of a window defines which region of the window should be
+retained when an
+<function>InputOutput</function>
+window is resized.
+The default value for the bit-gravity attribute is
+<function>ForgetGravity</function>.
+The window gravity of a window allows you to define how the
+<function>InputOutput</function>
+or
+<function>InputOnly</function>
+window should be repositioned if its parent is resized.
+The default value for the win-gravity attribute is
+<function>NorthWestGravity</function>.
+</para>
+<para>
+<!-- .LP -->
+If the inside width or height of a window is not changed
+and if the window is moved or its border is changed,
+then the contents of the window are not lost but move with the window.
+Changing the inside width or height of the window causes its contents to be
+moved or lost (depending on the bit-gravity of the window) and causes
+children to be reconfigured (depending on their win-gravity).
+For a
+change of width and height, the (x, y) pairs are defined:
+</para>
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Gravity Direction</entry>
+ <entry>Coordinates</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>NorthWestGravity</function></entry>
+ <entry>(0, 0)</entry>
+ </row>
+ <row>
+ <entry><function>NorthGravity</function></entry>
+ <entry>(Width/2, 0)</entry>
+ </row>
+ <row>
+ <entry><function>NorthEastGravity</function></entry>
+ <entry>(Width, 0)</entry>
+ </row>
+ <row>
+ <entry><function>WestGravity</function></entry>
+ <entry>(0, Height/2)</entry>
+ </row>
+ <row>
+ <entry><function>CenterGravity</function></entry>
+ <entry>(Width/2, Height/2)</entry>
+ </row>
+ <row>
+ <entry><function>EastGravity</function></entry>
+ <entry>(Width, Height/2)</entry>
+ </row>
+ <row>
+ <entry><function>SouthWestGravity</function></entry>
+ <entry>(0, Height)</entry>
+ </row>
+ <row>
+ <entry><function>SouthGravity</function></entry>
+ <entry>(Width/2, Height)</entry>
+ </row>
+ <row>
+ <entry><function>SouthEastGravity</function></entry>
+ <entry>(Width, Height)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+When a window with one of these bit-gravity values is resized,
+the corresponding pair
+defines the change in position of each pixel in the window.
+When a window with one of these win-gravities has its parent window resized,
+the corresponding pair defines the change in position of the window
+within the parent.
+When a window is so repositioned, a
+<function>GravityNotify</function>
+event is generated (see section 10.10.5).
+</para>
+<para>
+<!-- .LP -->
+A bit-gravity of
+<function>StaticGravity </function>
+indicates that the contents or origin should not move relative to the
+origin of the root window.
+If the change in size of the window is coupled with a change in position (x, y),
+then for bit-gravity the change in position of each pixel is (\-x, \-y), and for
+win-gravity the change in position of a child when its parent is so resized is
+(\-x, \-y).
+Note that
+<function>StaticGravity</function>
+still only takes effect when the width or height of the window is changed,
+not when the window is moved.
+</para>
+<para>
+<!-- .LP -->
+A bit-gravity of
+<function>ForgetGravity </function>
+indicates that the window's contents are always discarded after a size change,
+even if a backing store or save under has been requested.
+The window is tiled with its background
+and zero or more
+<function>Expose </function>
+events are generated.
+If no background is defined, the existing screen contents are not
+altered.
+Some X servers may also ignore the specified bit-gravity and
+always generate
+<function>Expose</function>
+events.
+</para>
+<para>
+<!-- .LP -->
+The contents and borders of inferiors are not affected by their parent's
+bit-gravity.
+A server is permitted to ignore the specified bit-gravity and use
+<function>Forget</function>
+instead.
+</para>
+<para>
+<!-- .LP -->
+A win-gravity of
+<function>UnmapGravity </function>
+is like
+<function>NorthWestGravity</function>
+(the window is not moved),
+except the child is also
+unmapped when the parent is resized,
+and an
+<function>UnmapNotify </function>
+event is
+generated.
+</para>
+</sect2>
+<sect2 id="Backing_Store_Attribute">
+<title>Backing Store Attribute</title>
+<!-- .XS -->
+<!-- (SN Backing Store Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some implementations of the X server may choose to maintain the contents of
+<function>InputOutput</function>
+windows.
+If the X server maintains the contents of a window,
+the off-screen saved pixels
+are known as backing store.
+The backing store advises the X server on what to do
+with the contents of a window.
+The backing-store attribute can be set to
+<function>NotUseful </function>
+(default),
+<function>WhenMapped</function>,
+or
+<function>Always</function>.
+</para>
+<para>
+<!-- .LP -->
+A backing-store attribute of
+<function>NotUseful </function>
+advises the X server that
+maintaining contents is unnecessary,
+although some X implementations may
+still choose to maintain contents and, therefore, not generate
+<function>Expose</function>
+events.
+A backing-store attribute of
+<function>WhenMapped </function>
+advises the X server that maintaining contents of
+obscured regions when the window is mapped would be beneficial.
+In this case,
+the server may generate an
+<function>Expose </function>
+event when the window is created.
+A backing-store attribute of
+<function>Always </function>
+advises the X server that maintaining contents even when
+the window is unmapped would be beneficial.
+Even if the window is larger than its parent,
+this is a request to the X server to maintain complete contents,
+not just the region within the parent window boundaries.
+While the X server maintains the window's contents,
+<function>Expose </function>
+events normally are not generated,
+but the X server may stop maintaining
+contents at any time.
+</para>
+<para>
+<!-- .LP -->
+When the contents of obscured regions of a window are being maintained,
+regions obscured by noninferior windows are included in the destination
+of graphics requests (and source, when the window is the source).
+However, regions obscured by inferior windows are not included.
+</para>
+</sect2>
+<sect2 id="Save_Under_Flag">
+<title>Save Under Flag</title>
+<!-- .XS -->
+<!-- (SN Save Under Flag -->
+<!-- .XE -->
+<indexterm><primary>Save Unders</primary></indexterm>
+<para>
+<!-- .LP -->
+Some server implementations may preserve contents of
+<function>InputOutput</function>
+windows under other
+<function>InputOutput</function>
+windows.
+This is not the same as preserving the contents of a window for you.
+You may get better visual
+appeal if transient windows (for example, pop-up menus) request that the system
+preserve the screen contents under them,
+so the temporarily obscured applications do not have to repaint.
+</para>
+<para>
+<!-- .LP -->
+You can set the save-under flag to
+<function>True</function>
+or
+<function>False </function>
+(default).
+If save-under is
+<function>True</function>,
+the X server is advised that, when this window is mapped,
+saving the contents of windows it obscures would be beneficial.
+</para>
+</sect2>
+<sect2 id="Backing_Planes_and_Backing_Pixel_Attributes">
+<title>Backing Planes and Backing Pixel Attributes</title>
+<!-- .XS -->
+<!-- (SN Backing Planes and Backing Pixel Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can set backing planes to indicate (with bits set to 1)
+which bit planes of an
+<function>InputOutput</function>
+window hold dynamic data that must be preserved in backing store
+and during save unders.
+The default value for the backing-planes attribute is all bits set to 1.
+You can set backing pixel to specify what bits to use in planes not
+covered by backing planes.
+The default value for the backing-pixel attribute is all bits set to 0.
+The X server is free to save only the specified bit planes in the backing store
+or the save under and is free to regenerate the remaining planes with
+the specified pixel value.
+Any extraneous bits in these values (that is, those bits beyond
+the specified depth of the window) may be simply ignored.
+If you request backing store or save unders,
+you should use these members to minimize the amount of off-screen memory
+required to store your window.
+</para>
+</sect2>
+<sect2 id="Event_Mask_and_Do_Not_Propagate_Mask_Attributes">
+<title>Event Mask and Do Not Propagate Mask Attributes</title>
+<!-- .XS -->
+<!-- (SN Event Mask and Do Not Propagate Mask Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The event mask defines which events the client is interested in for this
+<function>InputOutput</function>
+or
+<function>InputOnly</function>
+window (or, for some event types, inferiors of this window).
+The event mask is the bitwise inclusive OR of zero or more of the
+valid event mask bits.
+You can specify that no maskable events are reported by setting
+<function>NoEventMask </function>
+(default).
+</para>
+<para>
+<!-- .LP -->
+The do-not-propagate-mask attribute
+defines which events should not be propagated to
+ancestor windows when no client has the event type selected in this
+<function>InputOutput</function>
+or
+<function>InputOnly</function>
+window.
+The do-not-propagate-mask is the bitwise inclusive OR of zero or more
+of the following masks:
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+<function>PointerMotion</function>,
+<function>Button1Motion</function>,
+<function>Button2Motion</function>,
+<function>Button3Motion</function>,
+<function>Button4Motion</function>,
+<function>Button5Motion</function>,
+and
+<function>ButtonMotion</function>.
+You can specify that all events are propagated by setting
+<function>NoEventMask </function>
+(default).
+</para>
+</sect2>
+<sect2 id="Override_Redirect_Flag">
+<title>Override Redirect Flag</title>
+<!-- .XS -->
+<!-- (SN Override Redirect Flag -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To control window placement or to add decoration,
+a window manager often needs to intercept (redirect) any map or configure
+request.
+Pop-up windows, however, often need to be mapped without a window manager
+getting in the way.
+To control whether an
+<function>InputOutput</function>
+or
+<function>InputOnly</function>
+window is to ignore these structure control facilities,
+use the override-redirect flag.
+</para>
+<para>
+<!-- .LP -->
+The override-redirect flag specifies whether map and configure requests
+on this window should override a
+<function>SubstructureRedirectMask </function>
+on the parent.
+You can set the override-redirect flag to
+<function>True</function>
+or
+<function>False </function>
+(default).
+Window managers use this information to avoid tampering with pop-up windows
+(see also chapter 14).
+</para>
+</sect2>
+<sect2 id="Colormap_Attribute">
+<title>Colormap Attribute</title>
+<!-- .XS -->
+<!-- (SN Colormap Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The colormap attribute specifies which colormap best reflects the true
+colors of the
+<function>InputOutput</function>
+window.
+The colormap must have the same visual type as the window,
+or a
+<function>BadMatch </function>
+error results.
+X servers capable of supporting multiple
+hardware colormaps can use this information,
+and window managers can use it for calls to
+<function>XInstallColormap</function>.
+You can set the colormap attribute to a colormap or to
+<function>CopyFromParent</function>
+(default).
+</para>
+<para>
+<!-- .LP -->
+If you set the colormap to
+<function>CopyFromParent</function>,
+the parent window's colormap is copied and used by its child.
+However, the child window must have the same visual type as the parent,
+or a
+<function>BadMatch </function>
+error results.
+The parent window must not have a colormap of
+<function>None</function>,
+or a
+<function>BadMatch </function>
+error results.
+The colormap is copied by sharing the colormap object between the child
+and parent, not by making a complete copy of the colormap contents.
+Subsequent changes to the parent window's colormap attribute do
+not affect the child window.
+</para>
+</sect2>
+<sect2 id="Cursor_Attribute">
+<title>Cursor Attribute</title>
+<!-- .XS -->
+<!-- (SN Cursor Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The cursor attribute specifies which cursor is to be used when the pointer is
+in the
+<function>InputOutput</function>
+or
+<function>InputOnly</function>
+window.
+You can set the cursor to a cursor or
+<function>None</function>
+(default).
+</para>
+<para>
+<!-- .LP -->
+If you set the cursor to
+<function>None</function>,
+the parent's cursor is used when the
+pointer is in the
+<function>InputOutput</function>
+or
+<function>InputOnly</function>
+window, and any change in the parent's cursor will cause an
+immediate change in the displayed cursor.
+By calling
+<function>XFreeCursor</function>,
+the cursor can be freed immediately as long as no further explicit reference
+to it is made.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Creating_Windows">
+<title>Creating Windows</title>
+<!-- .XS -->
+<!-- (SN Creating Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides basic ways for creating windows,
+and toolkits often supply higher-level functions specifically for
+creating and placing top-level windows,
+which are discussed in the appropriate toolkit documentation.
+If you do not use a toolkit, however,
+you must provide some standard information or hints for the window
+manager by using the Xlib inter-client communication functions
+(see chapter 14).
+</para>
+<para>
+<!-- .LP -->
+If you use Xlib to create your own top-level windows
+(direct children of the root window),
+you must observe the following rules so that all applications interact
+reasonably across the different styles of window management:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+You must never fight with the window manager for the size or
+placement of your top-level window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+You must be able to deal with whatever size window you get,
+even if this means that your application just prints a message
+like ``Please make me bigger'' in its window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+You should only attempt to resize or move top-level windows in
+direct response to a user request.
+If a request to change the size of a top-level window fails,
+you must be prepared to live with what you get.
+You are free to resize or move the children of top-level
+windows as necessary.
+(Toolkits often have facilities for automatic relayout.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If you do not use a toolkit that automatically sets standard window properties,
+you should set these properties for top-level windows before mapping them.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For further information,
+see chapter 14 and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateWindow</function>
+is the more general function that allows you to set specific window attributes
+when you create a window.
+<function>XCreateSimpleWindow </function>
+creates a window that inherits its attributes from its parent window.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Window</primary><secondary>InputOnly</secondary></indexterm>
+The X server acts as if
+<function>InputOnly </function>
+windows do not exist for
+the purposes of graphics requests, exposure processing, and
+<function>VisibilityNotify </function>
+events.
+An
+<function>InputOnly </function>
+window cannot be used as a
+drawable (that is, as a source or destination for graphics requests).
+<function>InputOnly</function>
+and
+<function>InputOutput </function>
+windows act identically in other respects (properties,
+grabs, input control, and so on).
+Extension packages can define other classes of windows.
+</para>
+<para>
+<!-- .LP -->
+To create an unmapped window and set its window attributes, use
+<function>XCreateWindow</function>.
+<indexterm significance="preferred"><primary>XCreateWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window<function> XCreateWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> parent</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint<parameter> border_width</parameter></paramdef>
+ <paramdef>int<parameter> depth</parameter></paramdef>
+ <paramdef>unsignedint<parameter> class</parameter></paramdef>
+ <paramdef>Visual<parameter> *visual</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+ <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent window.
+<!-- .ds Xy , which are the top-left outside corner of the created window's \ -->
+borders and are relative to the inside of the parent window's borders
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the created window's inside dimensions \ -->
+and do not include the created window's borders
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+The dimensions must be nonzero,
+or a
+<function>BadValue</function>
+error results.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width of the created window's border in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window's depth.
+A depth of
+<function>CopyFromParent</function>
+means the depth is taken from the parent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the created window's class.
+You can pass
+<function>InputOutput</function>,
+<function>InputOnly</function>,
+or
+<function>CopyFromParent</function>.
+A class of
+<function>CopyFromParent</function>
+means the class
+is taken from the parent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual type.
+A visual of
+<function>CopyFromParent </function>
+means the visual type is taken from the
+parent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>valuemask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which window attributes are defined in the attributes
+argument.
+This mask is the bitwise inclusive OR of the valid attribute mask bits.
+If valuemask is zero,
+the attributes are ignored and are not referenced.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>attributes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the structure from which the values (as specified by the value mask)
+are to be taken.
+The value mask should have the appropriate bits
+set to indicate which attributes have been set in the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateWindow</function>
+function creates an unmapped subwindow for a specified parent window,
+returns the window ID of the created window,
+and causes the X server to generate a
+<function>CreateNotify</function>
+event.
+The created window is placed on top in the stacking order
+with respect to siblings.
+</para>
+<para>
+<!-- .LP -->
+The coordinate system has the X axis horizontal and the Y axis vertical
+with the origin [0, 0] at the upper-left corner.
+Coordinates are integral,
+in terms of pixels,
+and coincide with pixel centers.
+Each window and pixmap has its own coordinate system.
+For a window,
+the origin is inside the border at the inside, upper-left corner.
+</para>
+<para>
+<!-- .LP -->
+The border_width for an
+<function>InputOnly</function>
+window must be zero, or a
+<function>BadMatch</function>
+error results.
+For class
+<function>InputOutput</function>,
+the visual type and depth must be a combination supported for the screen,
+or a
+<function>BadMatch</function>
+error results.
+The depth need not be the same as the parent,
+but the parent must not be a window of class
+<function>InputOnly</function>,
+or a
+<function>BadMatch</function>
+error results.
+For an
+<function>InputOnly</function>
+window,
+the depth must be zero, and the visual must be one supported by the screen.
+If either condition is not met,
+a
+<function>BadMatch</function>
+error results.
+The parent window, however, may have any depth and class.
+If you specify any invalid window attribute for a window, a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The created window is not yet displayed (mapped) on the user's display.
+To display the window, call
+<function>XMapWindow</function>.
+The new window initially uses the same cursor as
+its parent.
+A new cursor can be defined for the new window by calling
+<function>XDefineCursor</function>.
+<indexterm><primary>Cursor</primary><secondary>Initial State</secondary></indexterm>
+<indexterm><primary>XDefineCursor</primary></indexterm>
+The window will not be visible on the screen unless it and all of its
+ancestors are mapped and it is not obscured by any of its ancestors.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateWindow</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadColor</function>,
+<function>BadCursor</function>,
+<function>BadMatch</function>,
+<function>BadPixmap</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an unmapped
+<function>InputOutput</function>
+subwindow of a given parent window, use
+<function>XCreateSimpleWindow</function>.
+<indexterm significance="preferred"><primary>XCreateSimpleWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window<function> XCreateSimpleWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> parent</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint<parameter> border_width</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> border</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> background</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent window.
+<!-- .ds Xy , which are the top-left outside corner of the new window's borders \ -->
+and are relative to the inside of the parent window's borders
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the created window's inside dimensions \ -->
+and do not include the created window's borders
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+The dimensions must be nonzero,
+or a
+<function>BadValue</function>
+error results.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width of the created window's border in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the border pixel value of the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the background pixel value of the window.
+
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateSimpleWindow</function>
+function creates an unmapped
+<function>InputOutput</function>
+subwindow for a specified parent window, returns the
+window ID of the created window, and causes the X server to generate a
+<function>CreateNotify</function>
+event.
+The created window is placed on top in the stacking order with respect to
+siblings.
+Any part of the window that extends outside its parent window is clipped.
+The border_width for an
+<function>InputOnly</function>
+window must be zero, or a
+<function>BadMatch</function>
+error results.
+<function>XCreateSimpleWindow</function>
+inherits its depth, class, and visual from its parent.
+All other window attributes, except background and border,
+have their default values.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateSimpleWindow</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Destroying_Windows">
+<title>Destroying Windows</title>
+<!-- .XS -->
+<!-- (SN Destroying Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to destroy a window or destroy all
+subwindows of a window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a window and all of its subwindows, use
+<function>XDestroyWindow</function>.
+<indexterm significance="preferred"><primary>XDestroyWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDestroyWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroyWindow</function>
+function destroys the specified window as well as all of its subwindows and causes
+the X server to generate a
+<function>DestroyNotify</function>
+event for each window.
+The window should never be referenced again.
+If the window specified by the w argument is mapped,
+it is unmapped automatically.
+The ordering of the
+<function>DestroyNotify</function>
+events is such that for any given window being destroyed,
+<function>DestroyNotify</function>
+is generated on any inferiors of the window before being generated on
+the window itself.
+The ordering among siblings and across subhierarchies is not otherwise
+constrained.
+If the window you specified is a root window, no windows are destroyed.
+Destroying a mapped window will generate
+<function>Expose </function>
+events on other windows that were obscured by the window being destroyed.
+</para>
+<para>
+<!-- .LP -->
+<function>XDestroyWindow</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy all subwindows of a specified window, use
+<function>XDestroySubwindows</function>.
+<indexterm significance="preferred"><primary>XDestroySubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDestroySubwindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroySubwindows</function>
+function destroys all inferior windows of the specified window,
+in bottom-to-top stacking order.
+It causes the X server to generate a
+<function>DestroyNotify</function>
+event for each window.
+If any mapped
+subwindows were actually destroyed,
+<function>XDestroySubwindows</function>
+causes the X server to generate
+<function>Expose </function>
+events on the specified window.
+This is much more efficient than deleting many windows
+one at a time because much of the work need be performed only once for all
+of the windows, rather than for each window.
+The subwindows should never be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XDestroySubwindows</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Mapping_Windows_">
+<title>Mapping Windows </title>
+<!-- .XS -->
+<!-- (SN Mapping Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A window is considered mapped if an
+<function>XMapWindow</function>
+call has been made on it.
+It may not be visible on the screen for one of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It is obscured by another opaque window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+One of its ancestors is not mapped.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It is entirely clipped by an ancestor.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Expose </function>
+events are generated for the window when part or all of
+it becomes visible on the screen.
+A client receives the
+<function>Expose </function>
+events only if it has asked for them.
+Windows retain their position in the stacking order when they are unmapped.
+</para>
+<para>
+<!-- .LP -->
+A window manager may want to control the placement of subwindows.
+If
+<function>SubstructureRedirectMask </function>
+has been selected by a window manager
+on a parent window (usually a root window),
+a map request initiated by other clients on a child window is not performed,
+and the window manager is sent a
+<function>MapRequest </function>
+event.
+However, if the override-redirect flag on the child had been set to
+<function>True</function>
+(usually only on pop-up menus),
+the map request is performed.
+</para>
+<para>
+<!-- .LP -->
+A tiling window manager might decide to reposition and resize other clients'
+windows and then decide to map the window to its final location.
+A window manager that wants to provide decoration might
+reparent the child into a frame first.
+For further information,
+see sections 3.2.8 and 10.10.
+Only a single client at a time can select for
+<function>SubstructureRedirectMask</function>.
+</para>
+<para>
+<!-- .LP -->
+Similarly, a single client can select for
+<function>ResizeRedirectMask </function>
+on a parent window.
+Then, any attempt to resize the window by another client is suppressed, and
+the client receives a
+<function>ResizeRequest </function>
+event.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a given window, use
+<function>XMapWindow</function>.
+<indexterm significance="preferred"><primary>XMapWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMapWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMapWindow</function>
+function
+maps the window and all of its
+subwindows that have had map requests.
+Mapping a window that has an unmapped ancestor does not display the
+window but marks it as eligible for display when the ancestor becomes
+mapped.
+Such a window is called unviewable.
+When all its ancestors are mapped,
+the window becomes viewable
+and will be visible on the screen if it is not obscured by another window.
+This function has no effect if the window is already mapped.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect of the window is
+<function>False </function>
+and if some other client has selected
+<function>SubstructureRedirectMask</function>
+on the parent window, then the X server generates a
+<function>MapRequest</function>
+event, and the
+<function>XMapWindow</function>
+function does not map the window.
+Otherwise, the window is mapped, and the X server generates a
+<function>MapNotify</function>
+event.
+</para>
+<para>
+<!-- .LP -->
+If the window becomes viewable and no earlier contents for it are remembered,
+the X server tiles the window with its background.
+If the window's background is undefined,
+the existing screen contents are not
+altered, and the X server generates zero or more
+<function>Expose</function>
+events.
+If backing-store was maintained while the window was unmapped, no
+<function>Expose</function>
+events
+are generated.
+If backing-store will now be maintained,
+a full-window exposure is always generated.
+Otherwise, only visible regions may be reported.
+Similar tiling and exposure take place for any newly viewable inferiors.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XMapWindow</primary></indexterm>
+If the window is an
+<function>InputOutput </function>
+window,
+<function>XMapWindow</function>
+generates
+<function>Expose </function>
+events on each
+<function>InputOutput</function>
+window that it causes to be displayed.
+If the client maps and paints the window
+and if the client begins processing events,
+the window is painted twice.
+To avoid this,
+first ask for
+<function>Expose </function>
+events and then map the window,
+so the client processes input events as usual.
+The event list will include
+<function>Expose </function>
+for each
+window that has appeared on the screen.
+The client's normal response to
+an
+<function>Expose </function>
+event should be to repaint the window.
+This method usually leads to simpler programs and to proper interaction
+with window managers.
+</para>
+<para>
+<!-- .LP -->
+<function>XMapWindow</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map and raise a window, use
+<function>XMapRaised</function>.
+<indexterm significance="preferred"><primary>XMapRaised</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMapRaised</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMapRaised</function>
+function
+essentially is similar to
+<function>XMapWindow</function>
+in that it maps the window and all of its
+subwindows that have had map requests.
+However, it also raises the specified window to the top of the stack.
+For additional information,
+see
+<function>XMapWindow</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XMapRaised</function>
+can generate multiple
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map all subwindows for a specified window, use
+<function>XMapSubwindows</function>.
+<indexterm significance="preferred"><primary>XMapSubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMapSubwindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMapSubwindows</function>
+<indexterm><primary>XMapSubwindows</primary></indexterm>
+function maps all subwindows for a specified window in top-to-bottom stacking
+order.
+The X server generates
+<function>Expose</function>
+events on each newly displayed window.
+This may be much more efficient than mapping many windows
+one at a time because the server needs to perform much of the work
+only once, for all of the windows, rather than for each window.
+</para>
+<para>
+<!-- .LP -->
+<function>XMapSubwindows</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Unmapping_Windows">
+<title>Unmapping Windows</title>
+<!-- .XS -->
+<!-- (SN Unmapping Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to unmap a window or all subwindows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unmap a window, use
+<function>XUnmapWindow</function>.
+<indexterm significance="preferred"><primary>XUnmapWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUnmapWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnmapWindow</function>
+function unmaps the specified window and causes the X server to generate an
+<function>UnmapNotify</function>
+<indexterm><primary>UnmapNotify Event</primary></indexterm>
+<indexterm><primary>XUnmapWindow</primary></indexterm>
+event.
+If the specified window is already unmapped,
+<function>XUnmapWindow </function>
+has no effect.
+Normal exposure processing on formerly obscured windows is performed.
+Any child window will no longer be visible until another map call is
+made on the parent.
+In other words, the subwindows are still mapped but are not visible
+until the parent is mapped.
+Unmapping a window will generate
+<function>Expose </function>
+events on windows that were formerly obscured by it.
+</para>
+<para>
+<!-- .LP -->
+<function>XUnmapWindow</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unmap all subwindows for a specified window, use
+<function>XUnmapSubwindows</function>.
+<indexterm significance="preferred"><primary>XUnmapSubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUnmapSubwindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnmapSubwindows</function>
+function unmaps all subwindows for the specified window in bottom-to-top
+stacking order.
+It causes the X server to generate an
+<function>UnmapNotify</function>
+event on each subwindow and
+<function>Expose </function>
+events on formerly obscured windows.
+<indexterm><primary>UnmapNotify Event</primary></indexterm>
+Using this function is much more efficient than unmapping multiple windows
+one at a time because the server needs to perform much of the work
+only once, for all of the windows, rather than for each window.
+</para>
+<para>
+<!-- .LP -->
+<function>XUnmapSubwindows</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Configuring_Windows">
+<title>Configuring Windows</title>
+<!-- .XS -->
+<!-- (SN Configuring Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to
+move a window, resize a window, move and resize a window, or
+change a window's border width.
+To change one of these parameters,
+set the appropriate member of the
+<function>XWindowChanges</function>
+structure and OR in the corresponding value mask in subsequent calls to
+<function>XConfigureWindow</function>.
+The symbols for the value mask bits and the
+<function>XWindowChanges</function>
+structure are:
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+
+<literallayout class="monospaced">
+/* Configure window value mask bits */
+#define CWX (1<<0)
+#define CWY (1<<1)
+#define CWWidth (1<<2)
+#define CWHeight (1<<3)
+#define CWBorderWidth (1<<4)
+#define CWSibling (1<<5)
+#define CWStackMode (1<<6)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XWindowChanges</primary></indexterm>
+<literallayout class="monospaced">
+/* Values */
+
+typedef struct {
+ int x, y;
+ int width, height;
+ int border_width;
+ Window sibling;
+ int stack_mode;
+} XWindowChanges;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x and y members are used to set the window's x and y coordinates,
+which are relative to the parent's origin
+and indicate the position of the upper-left outer corner of the window.
+The width and height members are used to set the inside size of the window,
+not including the border, and must be nonzero, or a
+<function>BadValue</function>
+error results.
+Attempts to configure a root window have no effect.
+</para>
+<para>
+<!-- .LP -->
+The border_width member is used to set the width of the border in pixels.
+Note that setting just the border width leaves the outer-left corner of the window
+in a fixed position but moves the absolute position of the window's origin.
+If you attempt to set the border-width attribute of an
+<function>InputOnly</function>
+window nonzero, a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The sibling member is used to set the sibling window for stacking operations.
+The stack_mode member is used to set how the window is to be restacked
+and can be set to
+<function>Above</function>,
+<function>Below</function>,
+<function>TopIf</function>,
+<function>BottomIf</function>,
+or
+<function>Opposite</function>.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is
+<function>False </function>
+and if some other client has selected
+<function>SubstructureRedirectMask</function>
+on the parent, the X server generates a
+<function>ConfigureRequest</function>
+event, and no further processing is performed.
+Otherwise,
+if some other client has selected
+<function>ResizeRedirectMask </function>
+on the window and the inside
+width or height of the window is being changed,
+a
+<function>ResizeRequest</function>
+event is generated, and the current inside width and height are
+used instead.
+Note that the override-redirect flag of the window has no effect
+on
+<function>ResizeRedirectMask </function>
+and that
+<function>SubstructureRedirectMask</function>
+on the parent has precedence over
+<function>ResizeRedirectMask </function>
+on the window.
+</para>
+<para>
+<!-- .LP -->
+When the geometry of the window is changed as specified,
+the window is restacked among siblings, and a
+<function>ConfigureNotify </function>
+event is generated if the state of the window actually changes.
+<function>GravityNotify</function>
+events are generated after
+<function>ConfigureNotify </function>
+events.
+If the inside width or height of the window has actually changed,
+children of the window are affected as specified.
+</para>
+<para>
+<!-- .LP -->
+If a window's size actually changes,
+the window's subwindows move according to their window gravity.
+Depending on the window's bit gravity,
+the contents of the window also may be moved (see section 3.2.3).
+</para>
+<para>
+<!-- .LP -->
+If regions of the window were obscured but now are not,
+exposure processing is performed on these formerly obscured windows,
+including the window itself and its inferiors.
+As a result of increasing the width or height,
+exposure processing is also performed on any new regions of the window
+and any regions where window contents are lost.
+</para>
+<para>
+<!-- .LP -->
+The restack check (specifically, the computation for
+<function>BottomIf</function>,
+<function>TopIf</function>,
+and
+<function>Opposite</function>)
+is performed with respect to the window's final size and position (as
+controlled by the other arguments of the request), not its initial position.
+If a sibling is specified without a stack_mode,
+a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If a sibling and a stack_mode are specified,
+the window is restacked as follows:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>Above</function></entry>
+ <entry>The window is placed just above the sibling.</entry>
+ </row>
+ <row>
+ <entry><function>Below</function></entry>
+ <entry>The window is placed just below the sibling.</entry>
+ </row>
+ <row>
+ <entry><function>TopIf</function></entry>
+ <entry>If the sibling occludes the window, the window is placed at the top of the stack.</entry>
+ </row>
+ <row>
+ <entry><function>BottomIf</function></entry>
+ <entry>If the window occludes the sibling, the window is placed at the bottom of the stack.</entry>
+ </row>
+ <row>
+ <entry><function>Opposite</function></entry>
+ <entry>
+If the sibling occludes the window, the window is placed at the top of the stack.
+If the window occludes the sibling,
+the window is placed at the bottom of the stack.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+If a stack_mode is specified but no sibling is specified,
+the window is restacked as follows:
+</para>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>Above</function></entry>
+ <entry>The window is placed at the top of the stack.</entry>
+ </row>
+ <row>
+ <entry><function>Below</function></entry>
+ <entry>The window is placed at the bottom of the stack.</entry>
+ </row>
+ <row>
+ <entry><function>TopIf</function></entry>
+ <entry>
+If any sibling occludes the window, the window is placed at
+the top of the stack.
+ </entry>
+ </row>
+ <row>
+ <entry>
+If the window occludes any sibling, the window is placed at
+the bottom of the stack.
+ </entry>
+ </row>
+ <row>
+ <entry><function>Opposite</function></entry>
+ <entry>
+If any sibling occludes the window, the window
+is placed at the top of the stack.
+If the window occludes any sibling,
+the window is placed at the bottom of the stack.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Attempts to configure a root window have no effect.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To configure a window's size, location, stacking, or border, use
+<function>XConfigureWindow</function>.
+<indexterm significance="preferred"><primary>XConfigureWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XConfigureWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>
+ <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi to be reconfigured -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWindowChanges </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XConfigureWindow</function>
+function uses the values specified in the
+<function>XWindowChanges</function>
+structure to reconfigure a window's size, position, border, and stacking order.
+Values not specified are taken from the existing geometry of the window.
+</para>
+<para>
+<!-- .LP -->
+If a sibling is specified without a stack_mode or if the window
+is not actually a sibling,
+a
+<function>BadMatch</function>
+error results.
+Note that the computations for
+<function>BottomIf</function>,
+<function>TopIf</function>,
+and
+<function>Opposite</function>
+are performed with respect to the window's final geometry (as controlled by the
+other arguments passed to
+<function>XConfigureWindow</function>),
+not its initial geometry.
+Any backing store contents of the window, its
+inferiors, and other newly visible windows are either discarded or
+changed to reflect the current screen contents
+(depending on the implementation).
+</para>
+<para>
+<!-- .LP -->
+<function>XConfigureWindow</function>
+can generate
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To move a window without changing its size, use
+<function>XMoveWindow</function>.
+<indexterm significance="preferred"><primary>XMoveWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMoveWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi to be moved -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+<!-- .ds Xy , which define the new location of the top-left pixel \ -->
+of the window's border or the window itself if it has no border
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMoveWindow</function>
+function moves the specified window to the specified x and y coordinates,
+but it does not change the window's size, raise the window, or
+change the mapping state of the window.
+Moving a mapped window may or may not lose the window's contents
+depending on if the window is obscured by nonchildren
+and if no backing store exists.
+If the contents of the window are lost,
+the X server generates
+<function>Expose </function>
+events.
+Moving a mapped window generates
+<function>Expose </function>
+events on any formerly obscured windows.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is
+<function>False </function>
+and some
+other client has selected
+<function>SubstructureRedirectMask </function>
+on the parent, the X server generates a
+<function>ConfigureRequest </function>
+event, and no further processing is
+performed.
+Otherwise, the window is moved.
+</para>
+<para>
+<!-- .LP -->
+<function>XMoveWindow</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change a window's size without changing the upper-left coordinate, use
+<function>XResizeWindow</function>.
+<indexterm significance="preferred"><primary>XResizeWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XResizeWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+<!-- .ds Wh , which are the interior dimensions of the window \ -->
+after the call completes
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XResizeWindow</function>
+function changes the inside dimensions of the specified window, not including
+its borders.
+This function does not change the window's upper-left coordinate or
+the origin and does not restack the window.
+Changing the size of a mapped window may lose its contents and generate
+<function>Expose </function>
+events.
+If a mapped window is made smaller,
+changing its size generates
+<function>Expose </function>
+events on windows that the mapped window formerly obscured.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is
+<function>False </function>
+and some
+other client has selected
+<function>SubstructureRedirectMask </function>
+on the parent, the X server generates a
+<function>ConfigureRequest </function>
+event, and no further processing is performed.
+If either width or height is zero,
+a
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XResizeWindow</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the size and location of a window, use
+<function>XMoveResizeWindow</function>.
+<indexterm significance="preferred"><primary>XMoveResizeWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMoveResizeWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi to be reconfigured -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+<!-- .ds Xy , which define the new position of the window relative to its parent -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which define the interior size of the window -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMoveResizeWindow</function>
+function changes the size and location of the specified window
+without raising it.
+Moving and resizing a mapped window may generate an
+<function>Expose </function>
+event on the window.
+Depending on the new size and location parameters,
+moving and resizing a window may generate
+<function>Expose </function>
+events on windows that the window formerly obscured.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is
+<function>False </function>
+and some
+other client has selected
+<function>SubstructureRedirectMask </function>
+on the parent, the X server generates a
+<function>ConfigureRequest </function>
+event, and no further processing is performed.
+Otherwise, the window size and location are changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XMoveResizeWindow</function>
+can generate
+<function>BadValue </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the border width of a given window, use
+<function>XSetWindowBorderWidth</function>.
+<indexterm significance="preferred"><primary>XSetWindowBorderWidth</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWindowBorderWidth</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>unsignedint<parameter> width</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width of the window border.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBorderWidth</function>
+function sets the specified window's border width to the specified width.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBorderWidth</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Changing_Window_Stacking_Order">
+<title>Changing Window Stacking Order</title>
+<!-- .XS -->
+<!-- (SN Changing Window Stacking Order -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to raise, lower, circulate,
+or restack windows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To raise a window so that no sibling window obscures it, use
+<function>XRaiseWindow</function>.
+<indexterm significance="preferred"><primary>XRaiseWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRaiseWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRaiseWindow</function>
+function
+raises the specified window to the top of the stack so that no sibling window
+obscures it.
+If the windows are regarded as overlapping sheets of paper stacked
+on a desk,
+then raising a window is analogous to moving the sheet to the top of
+the stack but leaving its x and y location on the desk constant.
+Raising a mapped window may generate
+<function>Expose</function>
+events for the window and any mapped subwindows that were formerly obscured.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect attribute of the window is
+<function>False </function>
+and some
+other client has selected
+<function>SubstructureRedirectMask </function>
+on the parent, the X server generates a
+<function>ConfigureRequest </function>
+event, and no processing is performed.
+Otherwise, the window is raised.
+</para>
+<para>
+<!-- .LP -->
+<function>XRaiseWindow</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lower a window so that it does not obscure any sibling windows, use
+<function>XLowerWindow</function>.
+<indexterm significance="preferred"><primary>XLowerWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XLowerWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLowerWindow</function>
+function lowers the specified window to the bottom of the stack
+so that it does not obscure any sibling
+windows.
+If the windows are regarded as overlapping sheets of paper
+stacked on a desk, then lowering a window is analogous to moving the
+sheet to the bottom of the stack but leaving its x and y location on
+the desk constant.
+Lowering a mapped window will generate
+<function>Expose </function>
+events on any windows it formerly obscured.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect attribute of the window is
+<function>False </function>
+and some
+other client has selected
+<function>SubstructureRedirectMask </function>
+on the parent, the X server generates a
+<function>ConfigureRequest </function>
+event, and no processing is performed.
+Otherwise, the window is lowered to the bottom of the
+stack.
+</para>
+<para>
+<!-- .LP -->
+<function>XLowerWindow</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To circulate a subwindow up or down, use
+<function>XCirculateSubwindows</function>.
+<indexterm significance="preferred"><primary>XCirculateSubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XCirculateSubwindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> direction</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>direction</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the direction (up or down) that you want to circulate
+the window.
+You can pass
+<function>RaiseLowest</function>
+or
+<function>LowerHighest</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCirculateSubwindows</function>
+function circulates children of the specified window in the specified
+direction.
+If you specify
+<function>RaiseLowest</function>,
+<function>XCirculateSubwindows</function>
+raises the lowest mapped child (if any) that is occluded
+by another child to the top of the stack.
+If you specify
+<function>LowerHighest</function>,
+<function>XCirculateSubwindows</function>
+lowers the highest mapped child (if any) that occludes another child
+to the bottom of the stack.
+Exposure processing is then performed on formerly obscured windows.
+If some other client has selected
+<function>SubstructureRedirectMask </function>
+on the window, the X server generates a
+<function>CirculateRequest </function>
+event, and no further processing is performed.
+If a child is actually restacked,
+the X server generates a
+<function>CirculateNotify</function>
+event.
+</para>
+<para>
+<!-- .LP -->
+<function>XCirculateSubwindows</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To raise the lowest mapped child of a window that is partially or completely
+occluded by another child, use
+<function>XCirculateSubwindowsUp</function>.
+<indexterm significance="preferred"><primary>XCirculateSubwindowsUp</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XCirculateSubwindowsUp</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCirculateSubwindowsUp</function>
+function raises the lowest mapped child of the specified window that
+is partially
+or completely
+occluded by another child.
+Completely unobscured children are not affected.
+This is a convenience function equivalent to
+<function>XCirculateSubwindows</function>
+with
+<function>RaiseLowest</function>
+specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XCirculateSubwindowsUp</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lower the highest mapped child of a window that partially or
+completely occludes another child, use
+<function>XCirculateSubwindowsDown</function>.
+<indexterm significance="preferred"><primary>XCirculateSubwindowsDown</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XCirculateSubwindowsDown</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCirculateSubwindowsDown</function>
+function lowers the highest mapped child of the specified window that partially
+or completely occludes another child.
+Completely unobscured children are not affected.
+This is a convenience function equivalent to
+<function>XCirculateSubwindows</function>
+with
+<function>LowerHighest</function>
+specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XCirculateSubwindowsDown</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To restack a set of windows from top to bottom, use
+<function>XRestackWindows</function>.
+<indexterm significance="preferred"><primary>XRestackWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRestackWindows</function></funcdef>
+ <paramdef>XRestackWindows\^(\^display,windows,<parameter> \^nwindows)</parameter></paramdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> windows[]</parameter></paramdef>
+ <paramdef>int<parameter> nwindows</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>windows</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array containing the windows to be restacked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nwindows</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of windows to be restacked.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRestackWindows</function>
+function restacks the windows in the order specified,
+from top to bottom.
+The stacking order of the first window in the windows array is unaffected,
+but the other windows in the array are stacked underneath the first window,
+in the order of the array.
+The stacking order of the other windows is not affected.
+For each window in the window array that is not a child of the specified window,
+a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect attribute of a window is
+<function>False </function>
+and some
+other client has selected
+<function>SubstructureRedirectMask </function>
+on the parent, the X server generates
+<function>ConfigureRequest </function>
+events for each window whose override-redirect flag is not set,
+and no further processing is performed.
+Otherwise, the windows will be restacked in top-to-bottom order.
+</para>
+<para>
+<!-- .LP -->
+<function>XRestackWindows</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Changing_Window_Attributes">
+<title>Changing Window Attributes</title>
+<!-- .XS -->
+<!-- (SN Changing Window Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set window attributes.
+<function>XChangeWindowAttributes</function>
+is the more general function that allows you to set one or more window
+attributes provided by the
+<function>XSetWindowAttributes</function>
+structure.
+The other functions described in this section allow you to set one specific
+window attribute, such as a window's background.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change one or more attributes for a given window, use
+<function>XChangeWindowAttributes</function>.
+<indexterm significance="preferred"><primary>XChangeWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeWindowAttributes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+ <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>valuemask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which window attributes are defined in the attributes
+argument.
+This mask is the bitwise inclusive OR of the valid attribute mask bits.
+If valuemask is zero,
+the attributes are ignored and are not referenced.
+The values and restrictions are
+the same as for
+<function>XCreateWindow</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>attributes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the structure from which the values (as specified by the value mask)
+are to be taken.
+The value mask should have the appropriate bits
+set to indicate which attributes have been set in the structure
+(see section 3.2).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Depending on the valuemask,
+the
+<function>XChangeWindowAttributes</function>
+function uses the window attributes in the
+<function>XSetWindowAttributes</function>
+structure to change the specified window attributes.
+Changing the background does not cause the window contents to be
+changed.
+To repaint the window and its background, use
+<function>XClearWindow</function>.
+Setting the border or changing the background such that the
+border tile origin changes causes the border to be repainted.
+Changing the background of a root window to
+<function>None </function>
+or
+<function>ParentRelative</function>
+restores the default background pixmap.
+Changing the border of a root window to
+<function>CopyFromParent</function>
+restores the default border pixmap.
+Changing the win-gravity does not affect the current position of the
+window.
+Changing the backing-store of an obscured window to
+<function>WhenMapped </function>
+or
+<function>Always</function>,
+or changing the backing-planes, backing-pixel, or
+save-under of a mapped window may have no immediate effect.
+Changing the colormap of a window (that is, defining a new map, not
+changing the contents of the existing map) generates a
+<function>ColormapNotify</function>
+event.
+Changing the colormap of a visible window may have no
+immediate effect on the screen because the map may not be installed
+(see
+<function>XInstallColormap</function>).
+Changing the cursor of a root window to
+<function>None </function>
+restores the default
+cursor.
+Whenever possible, you are encouraged to share colormaps.
+</para>
+<para>
+<!-- .LP -->
+Multiple clients can select input on the same window.
+Their event masks are maintained separately.
+When an event is generated,
+it is reported to all interested clients.
+However, only one client at a time can select for
+<function>SubstructureRedirectMask</function>,
+<function>ResizeRedirectMask</function>,
+and
+<function>ButtonPressMask</function>.
+If a client attempts to select any of these event masks
+and some other client has already selected one,
+a
+<function>BadAccess</function>
+error results.
+There is only one do-not-propagate-mask for a window,
+not one per client.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeWindowAttributes</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+<function>BadCursor</function>,
+<function>BadMatch</function>,
+<function>BadPixmap</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the background of a window to a given pixel, use
+<function>XSetWindowBackground</function>.
+<indexterm significance="preferred"><primary>XSetWindowBackground</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWindowBackground</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> background_pixel</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background_pixel</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pixel that is to be used for the background.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBackground</function>
+function sets the background of the window to the specified pixel value.
+Changing the background does not cause the window contents to be changed.
+<function>XSetWindowBackground</function>
+uses a pixmap of undefined size filled with the pixel value you passed.
+If you try to change the background of an
+<function>InputOnly</function>
+window, a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBackground</function>
+can generate
+<function>BadMatch</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the background of a window to a given pixmap, use
+<function>XSetWindowBackgroundPixmap</function>.
+<indexterm><primary>Window</primary><secondary>background</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetWindowBackgroundPixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWindowBackgroundPixmap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Pixmap<parameter> background_pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background_pixmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the background pixmap,
+<function>ParentRelative</function>,
+or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+The
+<function>XSetWindowBackgroundPixmap</function>
+function sets the background pixmap of the window to the specified pixmap.
+The background pixmap can immediately be freed if no further explicit
+references to it are to be made.
+If
+<function>ParentRelative</function>
+is specified,
+the background pixmap of the window's parent is used,
+or on the root window, the default background is restored.
+If you try to change the background of an
+<function>InputOnly</function>
+window, a
+<function>BadMatch</function>
+error results.
+If the background is set to
+<function>None</function>,
+the window has no defined background.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBackgroundPixmap</function>
+can generate
+<function>BadMatch</function>,
+<function>BadPixmap</function>,
+and
+<function>BadWindow </function>
+errors.
+<!-- .NT Note -->
+<function>XSetWindowBackground</function>
+and
+<function>XSetWindowBackgroundPixmap</function>
+do not change the current contents of the window.
+<!-- .NE -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change and repaint a window's border to a given pixel, use
+<function>XSetWindowBorder</function>.
+<indexterm significance="preferred"><primary>XSetWindowBorder</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWindowBorder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> border_pixel</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_pixel</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the entry in the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBorder</function>
+function sets the border of the window to the pixel value you specify.
+If you attempt to perform this on an
+<function>InputOnly</function>
+window, a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBorder</function>
+can generate
+<function>BadMatch </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change and repaint the border tile of a given window, use
+<function>XSetWindowBorderPixmap</function>.
+<indexterm significance="preferred"><primary>XSetWindowBorderPixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWindowBorderPixmap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Pixmap<parameter> border_pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_pixmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the border pixmap or
+<function>CopyFromParent</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBorderPixmap</function>
+function sets the border pixmap of the window to the pixmap you specify.
+The border pixmap can be freed immediately if no further explicit
+references to it are to be made.
+If you specify
+<function>CopyFromParent</function>,
+a copy of the parent window's border pixmap is used.
+If you attempt to perform this on an
+<function>InputOnly</function>
+window, a
+<function>BadMatch</function>
+error results.
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBorderPixmap</function>
+can generate
+<function>BadMatch</function>,
+<function>BadPixmap</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the colormap of a given window, use
+<function>XSetWindowColormap</function>.
+<indexterm significance="preferred"><primary>XSetWindowColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWindowColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowColormap</function>
+function sets the specified colormap of the specified window.
+The colormap must have the same visual type as the window,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowColormap</function>
+can generate
+<function>BadColor</function>,
+<function>BadMatch</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To define which cursor will be used in a window, use
+<function>XDefineCursor</function>.
+<indexterm><primary>Window</primary><secondary>defining the cursor</secondary></indexterm>
+<indexterm significance="preferred"><primary>XDefineCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDefineCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If a cursor is set, it will be used when the pointer is in the window.
+If the cursor is
+<function>None</function>,
+it is equivalent to
+<function>XUndefineCursor</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XDefineCursor</function>
+can generate
+<function>BadCursor</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To undefine the cursor in a given window, use
+<function>XUndefineCursor</function>.
+<indexterm><primary>Window</primary><secondary>undefining the cursor</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUndefineCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUndefineCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUndefineCursor</function>
+function undoes the effect of a previous
+<function>XDefineCursor</function>
+for this window.
+When the pointer is in the window,
+the parent's cursor will now be used.
+On the root window,
+the default cursor is restored.
+</para>
+<para>
+<!-- .LP -->
+<function>XUndefineCursor</function>
+can generate a
+<function>BadWindow </function>
+error.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH04 b/libX11/specs/libX11/CH04 deleted file mode 100644 index b964198c2..000000000 --- a/libX11/specs/libX11/CH04 +++ /dev/null @@ -1,1595 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 4\fP\s-1 - -\s+1\fBWindow Information Functions\fP\s-1 -.sp 2 -.nr H1 4 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 4: Window Information Functions -.XE -After you connect the display to the X server and create a window, -you can use the Xlib window information functions to: -.IP \(bu 5 -Obtain information about a window -.IP \(bu 5 -Translate screen coordinates -.IP \(bu 5 -Manipulate property lists -.IP \(bu 5 -Obtain and change window properties -.IP \(bu 5 -Manipulate selections -.NH 2 -Obtaining Window Information -.XS -\*(SN Obtaining Window Information -.XE -.LP -Xlib provides functions that you can use to obtain information about -the window tree, the window's current attributes, -the window's current geometry, or the current pointer coordinates. -Because they are most frequently used by window managers, -these functions all return a status to indicate whether the window still -exists. -.LP -.sp -To obtain the parent, a list of children, and number of children for -a given window, use -.PN XQueryTree . -.IN "Child Window" -.IN "Parent Window" -.IN "XQueryTree" "" "@DEF@" -.sM -.FD 0 -Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window *\fIroot_return\fP\^; -.br - Window *\fIparent_return\fP\^; -.br - Window **\fIchildren_return\fP\^; -.br - unsigned int *\fInchildren_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose list of children, root, parent, and number of children \ -you want to obtain -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIroot_return\fP 1i -Returns the root window. -.IP \fIparent_return\fP 1i -Returns the parent window. -.IP \fIchildren_return\fP 1i -Returns the list of children. -.IP \fInchildren_return\fP 1i -Returns the number of children. -.LP -.eM -The -.PN XQueryTree -function returns the root ID, the parent window ID, -a pointer to the list of children windows -(NULL when there are no children), -and the number of children in the list for the specified window. -The children are listed in current stacking order, from bottom-most -(first) to top-most (last). -.PN XQueryTree -returns zero if it fails and nonzero if it succeeds. -To free a non-NULL children list when it is no longer needed, use -.PN XFree . -.LP -.PN XQueryTree -can generate a -.PN BadWindow -error. -.LP -.sp -To obtain the current attributes of a given window, use -.PN XGetWindowAttributes . -.IN "XGetWindowAttributes" "" "@DEF@" -.sM -.FD 0 -Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XWindowAttributes *\fIwindow_attributes_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose current attributes you want to obtain -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIwindow_attributes_return\fP 1i -Returns the specified window's attributes in the -.PN XWindowAttributes -structure. -.LP -.eM -The -.PN XGetWindowAttributes -function returns the current attributes for the specified window to an -.PN XWindowAttributes -structure. -.LP -.IN "XWindowAttributes" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int x, y; /* location of window */ - int width, height; /* width and height of window */ - int border_width; /* border width of window */ - int depth; /* depth of window */ - Visual *visual; /* the associated visual structure */ - Window root; /* root of screen containing window */ - int class; /* InputOutput, InputOnly*/ - int bit_gravity; /* one of the bit gravity values */ - int win_gravity; /* one of the window gravity values */ - int backing_store; /* NotUseful, WhenMapped, Always */ - unsigned long backing_planes; /* planes to be preserved if possible */ - unsigned long backing_pixel; /* value to be used when restoring planes */ - Bool save_under; /* boolean, should bits under be saved? */ - Colormap colormap; /* color map to be associated with window */ - Bool map_installed; /* boolean, is color map currently installed*/ - int map_state; /* IsUnmapped, IsUnviewable, IsViewable */ - long all_event_masks; /* set of events all people have interest in*/ - long your_event_mask; /* my event mask */ - long do_not_propagate_mask; /* set of events that should not propagate */ - Bool override_redirect; /* boolean value for override-redirect */ - Screen *screen; /* back pointer to correct screen */ -} XWindowAttributes; -.De -.LP -.eM -The x and y members are set to the upper-left outer -corner relative to the parent window's origin. -The width and height members are set to the inside size of the window, -not including the border. -The border_width member is set to the window's border width in pixels. -The depth member is set to the depth of the window -(that is, bits per pixel for the object). -The visual member is a pointer to the screen's associated -.PN Visual -structure. -The root member is set to the root window of the screen containing the window. -The class member is set to the window's class and can be either -.PN InputOutput -or -.PN InputOnly . -.LP -The bit_gravity member is set to the window's bit gravity -and can be one of the following: -.LP -.TS -lw(1.5i) lw(1.5i). -T{ -.PN ForgetGravity -T} T{ -.PN EastGravity -T} -T{ -.PN NorthWestGravity -T} T{ -.PN SouthWestGravity -T} -T{ -.PN NorthGravity -T} T{ -.PN SouthGravity -T} -T{ -.PN NorthEastGravity -T} T{ -.PN SouthEastGravity -T} -T{ -.PN WestGravity -T} T{ -.PN StaticGravity -T} -.PN CenterGravity -.TE -.LP -The win_gravity member is set to the window's window gravity -and can be one of the following: -.LP -.TS -lw(1.5i) lw(1.5i). -T{ -.PN UnmapGravity -T} T{ -.PN EastGravity -T} -T{ -.PN NorthWestGravity -T} T{ -.PN SouthWestGravity -T} -T{ -.PN NorthGravity -T} T{ -.PN SouthGravity -T} -T{ -.PN NorthEastGravity -T} T{ -.PN SouthEastGravity -T} -T{ -.PN WestGravity -T} T{ -.PN StaticGravity -T} -.PN CenterGravity -.TE -.LP -For additional information on gravity, -see section 3.2.3. -.LP -The backing_store member is set to indicate how the X server should maintain -the contents of a window -and can be -.PN WhenMapped , -.PN Always , -or -.PN NotUseful . -The backing_planes member is set to indicate (with bits set to 1) which bit -planes of the window hold dynamic data that must be preserved in backing_stores -and during save_unders. -The backing_pixel member is set to indicate what values to use -for planes not set in backing_planes. -.LP -The save_under member is set to -.PN True -or -.PN False . -The colormap member is set to the colormap for the specified window and can be -a colormap ID or -.PN None . -The map_installed member is set to indicate whether the colormap is -currently installed and can be -.PN True -or -.PN False . -The map_state member is set to indicate the state of the window and can be -.PN IsUnmapped , -.PN IsUnviewable , -or -.PN IsViewable . -.PN IsUnviewable -is used if the window is mapped but some ancestor is unmapped. -.LP -The all_event_masks member is set to the bitwise inclusive OR of all event -masks selected on the window by all clients. -The your_event_mask member is set to the bitwise inclusive OR of all event -masks selected by the querying client. -The do_not_propagate_mask member is set to the bitwise inclusive OR of the -set of events that should not propagate. -.LP -The override_redirect member is set to indicate whether this window overrides -structure control facilities and can be -.PN True -or -.PN False . -Window manager clients should ignore the window if this member is -.PN True . -.LP -The screen member is set to a screen pointer that gives you a back pointer -to the correct screen. -This makes it easier to obtain the screen information without -having to loop over the root window fields to see which field matches. -.LP -.PN XGetWindowAttributes -can generate -.PN BadDrawable -and -.PN BadWindow -errors. -.LP -.sp -To obtain the current geometry of a given drawable, use -.PN XGetGeometry . -.IN "XGetGeometry" "" "@DEF@" -.sM -.FD 0 -Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, -.br - \fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - Window *\fIroot_return\fP\^; -.br - int *\fIx_return\fP\^, *\fIy_return\fP\^; -.br - unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; -.br - unsigned int *\fIborder_width_return\fP\^; -.br - unsigned int *\fIdepth_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Dr , which can be a window or a pixmap -.IP \fId\fP 1i -Specifies the drawable\*(Dr. -.IP \fIroot_return\fP 1i -Returns the root window. -.IP \fIx_return\fP 1i -.br -.ns -.IP \fIy_return\fP 1i -Return the x and y coordinates that define the location of the drawable. -For a window, -these coordinates specify the upper-left outer corner relative to -its parent's origin. -For pixmaps, these coordinates are always zero. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the drawable's dimensions (width and height). -For a window, -these dimensions specify the inside size, not including the border. -.IP \fIborder_width_return\fP 1i -Returns the border width in pixels. -If the drawable is a pixmap, it returns zero. -.IP \fIdepth_return\fP 1i -Returns the depth of the drawable (bits per pixel for the object). -.LP -.eM -The -.PN XGetGeometry -function returns the root window and the current geometry of the drawable. -The geometry of the drawable includes the x and y coordinates, width and height, -border width, and depth. -These are described in the argument list. -It is legal to pass to this function a window whose class is -.PN InputOnly . -.LP -.PN XGetGeometry -can generate a -.PN BadDrawable -error. -.NH 2 -Translating Screen Coordinates -.XS -\*(SN Translating Screen Coordinates -.XE -.LP -Applications sometimes -need to perform a coordinate transformation from the coordinate -space of one window to another window or need to determine which -window the pointing device is in. -.PN XTranslateCoordinates -and -.PN XQueryPointer -fulfill these needs (and avoid any race conditions) by -asking the X server to perform these operations. -.LP -.sp -To translate a coordinate in one window to the coordinate -space of another window, use -.PN XTranslateCoordinates . -.IN "XTranslateCoordinates" "" "@DEF@" -.sM -.FD 0 -Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^, -.br - \fIdest_y_return\fP\^, \fIchild_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIsrc_w\fP\^, \fIdest_w\fP\^; -.br - int \fIsrc_x\fP\^, \fIsrc_y\fP\^; -.br - int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^; -.br - Window *\fIchild_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsrc_w\fP 1i -Specifies the source window. -.IP \fIdest_w\fP 1i -Specifies the destination window. -.IP \fIsrc_x\fP 1i -.br -.ns -.IP \fIsrc_y\fP 1i -Specify the x and y coordinates within the source window. -.IP \fIdest_x_return\fP 1i -.br -.ns -.IP \fIdest_y_return\fP 1i -Return the x and y coordinates within the destination window. -.IP \fIchild_return\fP 1i -Returns the child if the coordinates are contained in a mapped child of the -destination window. -.LP -.eM -If -.PN XTranslateCoordinates -returns -.PN True , -it takes the src_x and src_y coordinates relative -to the source window's origin and returns these coordinates to -dest_x_return and dest_y_return -relative to the destination window's origin. -If -.PN XTranslateCoordinates -returns -.PN False , -src_w and dest_w are on different screens, -and dest_x_return and dest_y_return are zero. -If the coordinates are contained in a mapped child of dest_w, -that child is returned to child_return. -Otherwise, child_return is set to -.PN None . -.LP -.PN XTranslateCoordinates -can generate a -.PN BadWindow -error. -.LP -.sp -To obtain the screen coordinates of the pointer -or to determine the pointer coordinates relative to a specified window, use -.PN XQueryPointer . -.IN "XQueryPointer" "" "@DEF@" -.sM -.FD 0 -Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^, -.br - \fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window *\fIroot_return\fP\^, *\fIchild_return\fP\^; -.br - int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^; -.br - int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^; -.br - unsigned int *\fImask_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.ds Ro that the pointer is in -.IP \fIroot_return\fP 1i -Returns the root window \*(Ro. -.IP \fIchild_return\fP 1i -Returns the child window that the pointer is located in, if any. -.IP \fIroot_x_return\fP 1i -.br -.ns -.IP \fIroot_y_return\fP 1i -Return the pointer coordinates relative to the root window's origin. -.IP \fIwin_x_return\fP 1i -.br -.ns -.IP \fIwin_y_return\fP 1i -Return the pointer coordinates relative to the specified window. -.IP \fImask_return\fP 1i -Returns the current state of the modifier keys and pointer buttons. -.LP -.eM -The -.PN XQueryPointer -function returns the root window the pointer is logically on and the pointer -coordinates relative to the root window's origin. -If -.PN XQueryPointer -returns -.PN False , -the pointer is not on the same screen as the specified window, and -.PN XQueryPointer -returns -.PN None -to child_return and zero to win_x_return and win_y_return. -If -.PN XQueryPointer -returns -.PN True , -the pointer coordinates returned to win_x_return and win_y_return -are relative to the origin of the specified window. -In this case, -.PN XQueryPointer -returns the child that contains the pointer, if any, -or else -.PN None -to child_return. -.LP -.PN XQueryPointer -returns the current logical state of the keyboard buttons -and the modifier keys in mask_return. -It sets mask_return to the bitwise inclusive OR of one or more -of the button or modifier key bitmasks to match -the current state of the mouse buttons and the modifier keys. -.LP -Note that the logical state of a device (as seen through Xlib) -may lag the physical state if device event processing is frozen -(see section 12.1). -.LP -.PN XQueryPointer -can generate a -.PN BadWindow -error. -.NH 2 -Properties and Atoms -.XS -\*(SN Properties and Atoms -.XE -.LP -A property is a collection of named, typed data. -The window system has a set of predefined properties -.IN "Atom" "predefined" -(for example, the name of a window, size hints, and so on), and users can -define any other arbitrary information and associate it with windows. -Each property has a name, -which is an ISO Latin-1 string. -For each named property, -a unique identifier (atom) is associated with it. -A property also has a type, for example, string or integer. -These types are also indicated using atoms, so arbitrary new -types can be defined. -Data of only one type may be associated with a single -property name. -Clients can store and retrieve properties associated with windows. -For efficiency reasons, -an atom is used rather than a character string. -.PN XInternAtom -can be used to obtain the atom for property names. -.IN "Atom" -.LP -A property is also stored in one of several possible formats. -The X server can store the information as 8-bit quantities, 16-bit -quantities, or 32-bit quantities. -This permits the X server to present the data in the byte order that the -client expects. -.NT Note -If you define further properties of complex type, -you must encode and decode them yourself. -These functions must be carefully written if they are to be portable. -For further information about how to write a library extension, -see appendix C. -.NE -The type of a property is defined by an atom, which allows for -arbitrary extension in this type scheme. -.IN "Atom" -.LP -Certain property names are -predefined in the server for commonly used functions. -The atoms for these properties are defined in -.hN X11/Xatom.h . -To avoid name clashes with user symbols, the -.PN #define -name for each atom has the XA_ prefix. -For an explanation of the functions that let you get and set -much of the information stored in these predefined properties, -see chapter 14. -.LP -The core protocol imposes no semantics on these property names, -but semantics are specified in other X Consortium standards, -such as the \fIInter-Client Communication Conventions Manual\fP -and the \fIX Logical Font Description Conventions\fP. -.LP -You can use properties to communicate other information between -applications. -The functions described in this section let you define new properties -and get the unique atom IDs in your applications. -.LP -Although any particular atom can have some client interpretation -within each of the name spaces, -atoms occur in five distinct name spaces within the protocol: -.IP \(bu 5 -Selections -.IP \(bu 5 -Property names -.IP \(bu 5 -Property types -.IP \(bu 5 -Font properties -.IP \(bu 5 -Type of a -.PN ClientMessage -event (none are built into the X server) -.LP -.LP -The built-in selection property names are: -.LP -.Ds 0 -.TA .5i 1.5i 3i -.ta .5i 1.5i 3i -.R -PRIMARY -SECONDARY -.De -.LP -The built-in property names are: -.TS -lw(2i) lw(2i). -.sp 6p -CUT_BUFFER0 RESOURCE_MANAGER -CUT_BUFFER1 WM_CLASS -CUT_BUFFER2 WM_CLIENT_MACHINE -CUT_BUFFER3 WM_COLORMAP_WINDOWS -CUT_BUFFER4 WM_COMMAND -CUT_BUFFER5 WM_HINTS -CUT_BUFFER6 WM_ICON_NAME -CUT_BUFFER7 WM_ICON_SIZE -RGB_BEST_MAP WM_NAME -RGB_BLUE_MAP WM_NORMAL_HINTS -RGB_DEFAULT_MAP WM_PROTOCOLS -RGB_GRAY_MAP WM_STATE -RGB_GREEN_MAP WM_TRANSIENT_FOR -RGB_RED_MAP WM_ZOOM_HINTS -.sp 6p -.TE -.LP -The built-in property types are: -.LP -.TS -lw(2i) lw(2i). -.sp 6p -ARC POINT -ATOM RGB_COLOR_MAP -BITMAP RECTANGLE -CARDINAL STRING -COLORMAP VISUALID -CURSOR WINDOW -DRAWABLE WM_HINTS -FONT WM_SIZE_HINTS -INTEGER -PIXMAP -.sp 6p -.TE -.LP -The built-in font property names are: -.TS -lw(2i) lw(2i). -.sp 6p -MIN_SPACE STRIKEOUT_DESCENT -NORM_SPACE STRIKEOUT_ASCENT -MAX_SPACE ITALIC_ANGLE -END_SPACE X_HEIGHT -SUPERSCRIPT_X QUAD_WIDTH -SUPERSCRIPT_Y WEIGHT -SUBSCRIPT_X POINT_SIZE -SUBSCRIPT_Y RESOLUTION -UNDERLINE_POSITION COPYRIGHT -UNDERLINE_THICKNESS NOTICE -FONT_NAME FAMILY_NAME -FULL_NAME CAP_HEIGHT -.sp 6p -.TE -.LP -For further information about font properties, -see section 8.5. -.LP -.sp -To return an atom for a given name, use -.PN XInternAtom . -.IN "Atom" "interning" -.IN "XInternAtom" "" "@DEF@" -.sM -.FD 0 -Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIatom_name\fP\^; -.br - Bool \fIonly_if_exists\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIatom_name\fP 1i -Specifies the name associated with the atom you want returned. -.IP \fIonly_if_exists\fP 1i -Specifies a Boolean value that indicates whether the atom must be created. -.LP -.eM -The -.PN XInternAtom -function returns the atom identifier associated with the specified atom_name -string. -If only_if_exists is -.PN False , -the atom is created if it does not exist. -Therefore, -.PN XInternAtom -can return -.PN None . -If the atom name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Uppercase and lowercase matter; -the strings ``thing'', ``Thing'', and ``thinG'' -all designate different atoms. -The atom will remain defined even after the client's connection closes. -It will become undefined only when the last connection to -the X server closes. -.LP -.PN XInternAtom -can generate -.PN BadAlloc -and -.PN BadValue -errors. -.LP -.sp -To return atoms for an array of names, use -.PN XInternAtoms . -.IN "Atom" "interning" -.IN "XInternAtoms" "" "@DEF@" -.sM -.FD 0 -Status XInternAtoms\^(\^\fIdisplay\fP, \fInames\fP\^, \fIcount\fP\^, \fIonly_if_exists\fP, \fIatoms_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char **\fInames\fP\^; -.br - int \fIcount\fP\^; -.br - Bool \fIonly_if_exists\fP\^; -.br - Atom *\fIatoms_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInames\fP 1i -Specifies the array of atom names. -.ds Cn atom names in the array -.IP \fIcount\fP 1i -Specifies the number of \*(Cn. -.IP \fIonly_if_exists\fP 1i -Specifies a Boolean value that indicates whether the atom must be created. -.IP \fIatoms_return\fP 1i -Returns the atoms. -.LP -.eM -The -.PN XInternAtoms -function returns the atom identifiers associated with the specified names. -The atoms are stored in the atoms_return array supplied by the caller. -Calling this function is equivalent to calling -.PN XInternAtom -for each of the names in turn with the specified value of only_if_exists, -but this function minimizes the number of round-trip protocol exchanges -between the client and the X server. -.LP -This function returns a nonzero status if atoms are returned for -all of the names; -otherwise, it returns zero. -.LP -.PN XInternAtoms -can generate -.PN BadAlloc -and -.PN BadValue -errors. -.LP -.sp -To return a name for a given atom identifier, use -.PN XGetAtomName . -.IN "Atom" "getting name" -.IN "XGetAtomName" "" "@DEF@" -.sM -.FD 0 -char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Atom \fIatom\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIatom\fP 1i -Specifies the atom for the property name you want returned. -.LP -.eM -The -.PN XGetAtomName -function returns the name associated with the specified atom. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned string is in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -To free the resulting string, -call -.PN XFree . -.LP -.PN XGetAtomName -can generate a -.PN BadAtom -error. -.LP -.sp -To return the names for an array of atom identifiers, use -.PN XGetAtomNames . -.IN "Atom" "getting name" -.IN "XGetAtomNames" "" "@DEF@" -.sM -.FD 0 -Status XGetAtomNames\^(\^\fIdisplay\fP, \fIatoms\fP, \fIcount\fP\^, \fInames_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Atom *\fIatoms\fP\^; -.br - int \fIcount\fP\^; -.br - char **\fInames_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIatoms\fP 1i -Specifies the array of atoms. -.ds Cn atoms in the array -.IP \fIcount\fP 1i -Specifies the number of \*(Cn. -.IP \fInames_return\fP 1i -Returns the atom names. -.LP -.eM -The -.PN XGetAtomNames -function returns the names associated with the specified atoms. -The names are stored in the names_return array supplied by the caller. -Calling this function is equivalent to calling -.PN XGetAtomName -for each of the atoms in turn, -but this function minimizes the number of round-trip protocol exchanges -between the client and the X server. -.LP -This function returns a nonzero status if names are returned for -all of the atoms; -otherwise, it returns zero. -.LP -.PN XGetAtomNames -can generate a -.PN BadAtom -error. -.NH 2 -Obtaining and Changing Window Properties -.XS -\*(SN Obtaining and Changing Window Properties -.XE -.LP -You can attach a property list to every window. -Each property has a name, a type, and a value (see section 4.3). -The value is an array of 8-bit, 16-bit, or 32-bit quantities, -whose interpretation is left to the clients. The type -.PN char -is used to represent 8-bit quantities, the type -.PN short -is used to represent 16-bit quantities, and the type -.PN long -is used to represent 32-bit quantities. -.LP -Xlib provides functions that you can use to obtain, -change, update, or interchange window properties. -In addition, Xlib provides other utility functions for inter-client -communication (see chapter 14). -.LP -.sp -To obtain the type, format, and value of a property of a given window, use -.PN XGetWindowProperty . -.IN "Property" "getting" -.LP -.IN "XGetWindowProperty" "" "@DEF@" -.sM -.FD 0 -int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^, -.br - \fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^, -.br - \fIprop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Atom \fIproperty\fP\^; -.br - long \fIlong_offset\fP\^, \fIlong_length\fP\^; -.br - Bool \fIdelete\fP\^; -.br - Atom \fIreq_type\fP\^; -.br - Atom *\fIactual_type_return\fP\^; -.br - int *\fIactual_format_return\fP\^; -.br - unsigned long *\fInitems_return\fP\^; -.br - unsigned long *\fIbytes_after_return\fP\^; -.br - unsigned char **\fIprop_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose property you want to obtain -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIproperty\fP 1i -Specifies the property name. -.IP \fIlong_offset\fP 1i -Specifies the offset in the specified property (in 32-bit quantities) -where the data is to be retrieved. -.IP \fIlong_length\fP 1i -Specifies the length in 32-bit multiples of the data to be retrieved. -.IP \fIdelete\fP 1i -Specifies a Boolean value that determines whether the property is deleted. -.IP \fIreq_type\fP 1i -Specifies the atom identifier associated with the property type or -.PN AnyPropertyType . -.IP \fIactual_type_return\fP 1i -Returns the atom identifier that defines the actual type of the property. -.IP \fIactual_format_return\fP 1i -Returns the actual format of the property. -.IP \fInitems_return\fP 1i -Returns the actual number of 8-bit, 16-bit, or 32-bit items -stored in the prop_return data. -.IP \fIbytes_after_return\fP 1i -Returns the number of bytes remaining to be read in the property if -a partial read was performed. -.IP \fIprop_return\fP 1i -Returns the data in the specified format. -.LP -.eM -The -.PN XGetWindowProperty -function returns the actual type of the property; the actual format of the property; -the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining -to be read in the property; and a pointer to the data actually returned. -.PN XGetWindowProperty -sets the return arguments as follows: -.IP \(bu 5 -If the specified property does not exist for the specified window, -.PN XGetWindowProperty -returns -.PN None -to actual_type_return and the value zero to -actual_format_return and bytes_after_return. -The nitems_return argument is empty. -In this case, the delete argument is ignored. -.IP \(bu 5 -If the specified property exists -but its type does not match the specified type, -.PN XGetWindowProperty -returns the actual property type to actual_type_return, -the actual property format (never zero) to actual_format_return, -and the property length in bytes -(even if the actual_format_return is 16 or 32) -to bytes_after_return. -It also ignores the delete argument. -The nitems_return argument is empty. -.IP \(bu 5 -If the specified property exists and either you assign -.PN AnyPropertyType -to the req_type argument or the specified type matches the actual property type, -.PN XGetWindowProperty -returns the actual property type to actual_type_return and the actual -property format (never zero) to actual_format_return. -It also returns a value to bytes_after_return and nitems_return, by -defining the following -values: -.IP -.nf - N = actual length of the stored property in bytes - (even if the format is 16 or 32) - I = 4 * long_offset - T = N - I - L = MINIMUM(T, 4 * long_length) - A = N - (I + L) -.fi -.IP -The returned value starts at byte index I in the property (indexing -from zero), and its length in bytes is L. -If the value for long_offset causes L to be negative, -a -.PN BadValue -error results. -The value of bytes_after_return is A, -giving the number of trailing unread bytes in the stored property. -.LP -If the returned format is 8, the returned data is represented as a -.PN char -array. -If the returned format is 16, the returned data is represented as a -.PN short -array and should be cast to that type to obtain the elements. -If the returned format is 32, the returned data is represented as a -.PN long -array and should be cast to that type to obtain the elements. -.LP -.PN XGetWindowProperty -always allocates one extra byte in prop_return -(even if the property is zero length) -and sets it to zero so that simple properties consisting of characters -do not have to be copied into yet another string before use. -.LP -If delete is -.PN True -and bytes_after_return is zero, -.PN XGetWindowProperty -deletes the property -from the window and generates a -.PN PropertyNotify -event on the window. -.LP -The function returns -.PN Success -if it executes successfully. -To free the resulting data, -use -.PN XFree . -.LP -.PN XGetWindowProperty -can generate -.PN BadAtom , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To obtain a given window's property list, use -.PN XListProperties . -.IN "Property" "listing" -.IN "XListProperties" "" "@DEF@" -.sM -.FD 0 -Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int *\fInum_prop_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose property list you want to obtain -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fInum_prop_return\fP 1i -Returns the length of the properties array. -.LP -.eM -The -.PN XListProperties -function returns a pointer to an array of atom properties that are defined for -the specified window or returns NULL if no properties were found. -To free the memory allocated by this function, use -.PN XFree . -.LP -.PN XListProperties -can generate a -.PN BadWindow -error. -.LP -.sp -To change a property of a given window, use -.PN XChangeProperty . -.IN "Property" "changing" -.IN "Property" "appending" -.IN "Property" "prepending" -.IN "Property" "replacing" -.IN "Property" "format" -.IN "Property" "type" -.IN "XChangeProperty" "" "@DEF@" -.sM -.FD 0 -XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Atom \fIproperty\fP\^, \fItype\fP\^; -.br - int \fIformat\fP\^; -.br - int \fImode\fP\^; -.br - unsigned char *\fIdata\fP\^; -.br - int \fInelements\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose property you want to change -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIproperty\fP 1i -Specifies the property name. -.IP \fItype\fP 1i -Specifies the type of the property. -The X server does not interpret the type but simply -passes it back to an application that later calls -.PN XGetWindowProperty . -.IP \fIformat\fP 1i -Specifies whether the data should be viewed as a list -of 8-bit, 16-bit, or 32-bit quantities. -Possible values are 8, 16, and 32. -This information allows the X server to correctly perform -byte-swap operations as necessary. -If the format is 16-bit or 32-bit, -you must explicitly cast your data pointer to an (unsigned char *) in the call -to -.PN XChangeProperty . -.\" Changed name of this file to prop_mode.a on 1/13/87 -.IP \fImode\fP 1i -Specifies the mode of the operation. -You can pass -.PN PropModeReplace , -.PN PropModePrepend , -or -.PN PropModeAppend . -.IP \fIdata\fP 1i -Specifies the property data. -.IP \fInelements\fP 1i -Specifies the number of elements of the specified data format. -.LP -.eM -The -.PN XChangeProperty -function alters the property for the specified window and -causes the X server to generate a -.PN PropertyNotify -event on that window. -.PN XChangeProperty -performs the following: -.IP \(bu 5 -If mode is -.PN PropModeReplace , -.PN XChangeProperty -discards the previous property value and stores the new data. -.IP \(bu 5 -If mode is -.PN PropModePrepend -or -.PN PropModeAppend , -.PN XChangeProperty -inserts the specified data before the beginning of the existing data -or onto the end of the existing data, respectively. -The type and format must match the existing property value, -or a -.PN BadMatch -error results. -If the property is undefined, -it is treated as defined with the correct type and -format with zero-length data. -.LP -If the specified format is 8, the property data must be a -.PN char -array. -If the specified format is 16, the property data must be a -.PN short -array. -If the specified format is 32, the property data must be a -.PN long -array. -.LP -The lifetime of a property is not tied to the storing client. -Properties remain until explicitly deleted, until the window is destroyed, -or until the server resets. -For a discussion of what happens when the connection to the X server is closed, -see section 2.6. -The maximum size of a property is server dependent and can vary dynamically -depending on the amount of memory the server has available. -(If there is insufficient space, a -.PN BadAlloc -error results.) -.LP -.PN XChangeProperty -can generate -.PN BadAlloc , -.PN BadAtom , -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To rotate a window's property list, use -.PN XRotateWindowProperties . -.LP -.IN "XRotateWindowProperties" "" "@DEF@" -.sM -.FD 0 -XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Atom \fIproperties\fP\^[]\^; -.br - int \fInum_prop\fP\^; -.br - int \fInpositions\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIproperties\fP 1i -Specifies the array of properties that are to be rotated. -.IP \fInum_prop\fP 1i -Specifies the length of the properties array. -.IP \fInpositions\fP 1i -Specifies the rotation amount. -.LP -.eM -The -.PN XRotateWindowProperties -function allows you to rotate properties on a window and causes -the X server to generate -.PN PropertyNotify -events. -If the property names in the properties array are viewed as being numbered -starting from zero and if there are num_prop property names in the list, -then the value associated with property name I becomes the value associated -with property name (I + npositions) mod N for all I from zero to N \- 1. -The effect is to rotate the states by npositions places around the virtual ring -of property names (right for positive npositions, -left for negative npositions). -If npositions mod N is nonzero, -the X server generates a -.PN PropertyNotify -event for each property in the order that they are listed in the array. -If an atom occurs more than once in the list or no property with that -name is defined for the window, -a -.PN BadMatch -error results. -If a -.PN BadAtom -or -.PN BadMatch -error results, -no properties are changed. -.LP -.PN XRotateWindowProperties -can generate -.PN BadAtom , -.PN BadMatch , -and -.PN BadWindow -errors. -.LP -.sp -To delete a property on a given window, use -.PN XDeleteProperty . -.IN "Property" "deleting" -.IN "XDeleteProperty" "" "@DEF@" -.sM -.FD 0 -XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose property you want to delete -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XDeleteProperty -function deletes the specified property only if the -property was defined on the specified window -and causes the X server to generate a -.PN PropertyNotify -event on the window unless the property does not exist. -.LP -.PN XDeleteProperty -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.NH 2 -Selections -.XS -\*(SN Selections -.XE -.LP -.IN "Selection" -Selections are one method used by applications to exchange data. -By using the property mechanism, -applications can exchange data of arbitrary types and can negotiate -the type of the data. -A selection can be thought of as an indirect property with a dynamic type. -That is, rather than having the property stored in the X server, -the property is maintained by some client (the owner). -A selection is global in nature (considered to belong to the user -but be maintained by clients) rather than being private to a particular -window subhierarchy or a particular set of clients. -.LP -Xlib provides functions that you can use to set, get, or request conversion -of selections. -This allows applications to implement the notion of current selection, -which requires that notification be sent to applications when they no -longer own the selection. -Applications that support selection often highlight the current selection -and so must be informed when another application has -acquired the selection so that they can unhighlight the selection. -.LP -When a client asks for the contents of -a selection, it specifies a selection target type. -This target type -can be used to control the transmitted representation of the contents. -For example, if the selection is ``the last thing the user clicked on'' -and that is currently an image, then the target type might specify -whether the contents of the image should be sent in XY format or Z format. -.LP -The target type can also be used to control the class of -contents transmitted, for example, -asking for the ``looks'' (fonts, line -spacing, indentation, and so forth) of a paragraph selection, not the -text of the paragraph. -The target type can also be used for other -purposes. -The protocol does not constrain the semantics. -.LP -.sp -To set the selection owner, use -.PN XSetSelectionOwner . -.IN "Selection" "setting the owner" -.IN "XSetSelectionOwner" "" "@DEF@" -.sM -.FD 0 -XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Atom \fIselection\fP\^; -.br - Window \fIowner\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIselection\fP 1i -Specifies the selection atom. -.IP \fIowner\fP 1i -Specifies the owner of the specified selection atom. -You can pass a window or -.PN None . -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XSetSelectionOwner -function changes the owner and last-change time for the specified selection -and has no effect if the specified time is earlier than the current -last-change time of the specified selection -or is later than the current X server time. -Otherwise, the last-change time is set to the specified time, -with -.PN CurrentTime -replaced by the current server time. -If the owner window is specified as -.PN None , -then the owner of the selection becomes -.PN None -(that is, no owner). -Otherwise, the owner of the selection becomes the client executing -the request. -.LP -If the new owner (whether a client or -.PN None ) -is not -the same as the current owner of the selection and the current -owner is not -.PN None , -the current owner is sent a -.PN SelectionClear -event. -If the client that is the owner of a selection is later -terminated (that is, its connection is closed) -or if the owner window it has specified in the request is later -destroyed, -the owner of the selection automatically -reverts to -.PN None , -but the last-change time is not affected. -The selection atom is uninterpreted by the X server. -.PN XGetSelectionOwner -returns the owner window, which is reported in -.PN SelectionRequest -and -.PN SelectionClear -events. -Selections are global to the X server. -.LP -.PN XSetSelectionOwner -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.LP -.sp -To return the selection owner, use -.PN XGetSelectionOwner . -.IN "Selection" "getting the owner" -.IN "XGetSelectionOwner" "" "@DEF@" -.sM -.FD 0 -Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Atom \fIselection\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Se whose owner you want returned -.IP \fIselection\fP 1i -Specifies the selection atom \*(Se. -.LP -.eM -The -.PN XGetSelectionOwner -function -returns the window ID associated with the window that currently owns the -specified selection. -If no selection was specified, the function returns the constant -.PN None . -If -.PN None -is returned, -there is no owner for the selection. -.LP -.PN XGetSelectionOwner -can generate a -.PN BadAtom -error. -.LP -.sp -To request conversion of a selection, use -.PN XConvertSelection . -.IN "Selection" "converting" -.IN "XConvertSelection" "" "@DEF@" -.sM -.FD 0 -XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Atom \fIselection\fP\^, \fItarget\fP\^; -.br - Atom \fIproperty\fP\^; -.br - Window \fIrequestor\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIselection\fP 1i -Specifies the selection atom. -.IP \fItarget\fP 1i -Specifies the target atom. -.IP \fIproperty\fP 1i -Specifies the property name. -You also can pass -.PN None . -.IP \fIrequestor\fP 1i -Specifies the requestor. -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -.PN XConvertSelection -requests that the specified selection be converted to the specified target -type: -.IP \(bu 5 -If the specified selection has an owner, the X server sends a -.PN SelectionRequest -event to that owner. -.IP \(bu 5 -If no owner for the specified -selection exists, the X server generates a -.PN SelectionNotify -event to the -requestor with property -.PN None . -.LP -The arguments are passed on unchanged in either of the events. -There are two predefined selection atoms: PRIMARY and SECONDARY. -.LP -.PN XConvertSelection -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.bp diff --git a/libX11/specs/libX11/CH04.xml b/libX11/specs/libX11/CH04.xml new file mode 100644 index 000000000..ed8bd2427 --- /dev/null +++ b/libX11/specs/libX11/CH04.xml @@ -0,0 +1,2647 @@ +<chapter id="window_information_functions">
+<title>Window Information Functions</title>
+
+<para>
+After you connect the display to the X server and create a window, you can use the Xlib window
+information functions to:
+</para>
+<itemizedlist>
+ <listitem><para>Obtain information about a window</para></listitem>
+ <listitem><para>Translate screen coordinates</para></listitem>
+ <listitem><para>Manipulate property lists</para></listitem>
+ <listitem><para>Obtain and change window properties</para></listitem>
+ <listitem><para>Manipulate selections</para></listitem>
+</itemizedlist>
+
+<sect1 id="Obtaining_Window_Information">
+<title>Obtaining Window Information</title>
+<!-- .XS -->
+<!-- (SN Obtaining Window Information -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to obtain information about
+the window tree, the window's current attributes,
+the window's current geometry, or the current pointer coordinates.
+Because they are most frequently used by window managers,
+these functions all return a status to indicate whether the window still
+exists.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the parent, a list of children, and number of children for
+a given window, use
+<function>XQueryTree</function>.
+<indexterm><primary>Child Window</primary></indexterm>
+<indexterm><primary>Parent Window</primary></indexterm>
+<indexterm significance="preferred"><primary>XQueryTree</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XQueryTree</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> *root_return</parameter></paramdef>
+ <paramdef>Window<parameter> *parent_return</parameter></paramdef>
+ <paramdef>Window<parameter> **children_return</parameter></paramdef>
+ <paramdef>unsignedint<parameter> *nchildren_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose list of children, root, parent, and number of children \ -->
+you want to obtain
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the root window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the parent window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>children_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of children.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nchildren_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of children.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryTree</function>
+function returns the root ID, the parent window ID,
+a pointer to the list of children windows
+(NULL when there are no children),
+and the number of children in the list for the specified window.
+The children are listed in current stacking order, from bottom-most
+(first) to top-most (last).
+<function>XQueryTree</function>
+returns zero if it fails and nonzero if it succeeds.
+To free a non-NULL children list when it is no longer needed, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryTree</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current attributes of a given window, use
+<function>XGetWindowAttributes</function>.
+<indexterm significance="preferred"><primary>XGetWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWindowAttributes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XWindowAttributes<parameter> *window_attributes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose current attributes you want to obtain -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_attributes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the specified window's attributes in the
+<function>XWindowAttributes</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWindowAttributes</function>
+function returns the current attributes for the specified window to an
+<function>XWindowAttributes</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int x, y; /* location of window */
+ int width, height; /* width and height of window */
+ int border_width; /* border width of window */
+ int depth; /* depth of window */
+ Visual *visual; /* the associated visual structure */
+ Window root; /* root of screen containing window */
+ int class; /* InputOutput, InputOnly*/
+ int bit_gravity; /* one of the bit gravity values */
+ int win_gravity; /* one of the window gravity values */
+ int backing_store; /* NotUseful, WhenMapped, Always */
+ unsigned long backing_planes; /* planes to be preserved if possible */
+ unsigned long backing_pixel; /* value to be used when restoring planes */
+ Bool save_under; /* boolean, should bits under be saved? */
+ Colormap colormap; /* color map to be associated with window */
+ Bool map_installed; /* boolean, is color map currently installed*/
+ int map_state; /* IsUnmapped, IsUnviewable, IsViewable */
+ long all_event_masks; /* set of events all people have interest in*/
+ long your_event_mask; /* my event mask */
+ long do_not_propagate_mask; /* set of events that should not propagate */
+ Bool override_redirect; /* boolean value for override-redirect */
+ Screen *screen; /* back pointer to correct screen */
+} XWindowAttributes;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x and y members are set to the upper-left outer
+corner relative to the parent window's origin.
+The width and height members are set to the inside size of the window,
+not including the border.
+The border_width member is set to the window's border width in pixels.
+The depth member is set to the depth of the window
+(that is, bits per pixel for the object).
+The visual member is a pointer to the screen's associated
+<function>Visual</function>
+structure.
+The root member is set to the root window of the screen containing the window.
+The class member is set to the window's class and can be either
+<function>InputOutput</function>
+or
+<function>InputOnly</function>.
+</para>
+<para>
+<!-- .LP -->
+The bit_gravity member is set to the window's bit gravity
+and can be one of the following:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>ForgetGravity</function></entry>
+ <entry><function>EastGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>NorthWestGravity</function></entry>
+ <entry><function>SouthWestGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>NorthGravity</function></entry>
+ <entry><function>SouthGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>NorthEastGravity</function></entry>
+ <entry><function>SouthEastGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>WestGravity</function></entry>
+ <entry><function>StaticGravity</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<para>
+<!-- .LP -->
+The win_gravity member is set to the window's window gravity
+and can be one of the following:
+</para>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>UnmapGravity</function></entry>
+ <entry><function>EastGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>NorthWestGravity</function></entry>
+ <entry><function>SouthWestGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>NorthGravity</function></entry>
+ <entry><function>SouthGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>NorthEastGravity</function></entry>
+ <entry><function>SouthEastGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>WestGravity</function></entry>
+ <entry><function>StaticGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>CenterGravity</function></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<para>
+<!-- .LP -->
+For additional information on gravity,
+see section 3.2.3. <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+The backing_store member is set to indicate how the X server should maintain
+the contents of a window
+and can be
+<function>WhenMapped</function>,
+<function>Always</function>,
+or
+<function>NotUseful</function>.
+The backing_planes member is set to indicate (with bits set to 1) which bit
+planes of the window hold dynamic data that must be preserved in backing_stores
+and during save_unders.
+The backing_pixel member is set to indicate what values to use
+for planes not set in backing_planes.
+</para>
+<para>
+<!-- .LP -->
+The save_under member is set to
+<function>True</function>
+or
+<function>False</function>.
+The colormap member is set to the colormap for the specified window and can be
+a colormap ID or
+<function>None</function>.
+The map_installed member is set to indicate whether the colormap is
+currently installed and can be
+<function>True</function>
+or
+<function>False</function>.
+The map_state member is set to indicate the state of the window and can be
+<function>IsUnmapped</function>,
+<function>IsUnviewable</function>,
+or
+<function>IsViewable</function>.
+<function>IsUnviewable</function>
+is used if the window is mapped but some ancestor is unmapped.
+</para>
+<para>
+<!-- .LP -->
+The all_event_masks member is set to the bitwise inclusive OR of all event
+masks selected on the window by all clients.
+The your_event_mask member is set to the bitwise inclusive OR of all event
+masks selected by the querying client.
+The do_not_propagate_mask member is set to the bitwise inclusive OR of the
+set of events that should not propagate.
+</para>
+<para>
+<!-- .LP -->
+The override_redirect member is set to indicate whether this window overrides
+structure control facilities and can be
+<function>True</function>
+or
+<function>False</function>.
+Window manager clients should ignore the window if this member is
+<function>True</function>.
+</para>
+<para>
+<!-- .LP -->
+The screen member is set to a screen pointer that gives you a back pointer
+to the correct screen.
+This makes it easier to obtain the screen information without
+having to loop over the root window fields to see which field matches.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWindowAttributes</function>
+can generate
+<function>BadDrawable</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current geometry of a given drawable, use
+<function>XGetGeometry</function>.
+<indexterm significance="preferred"><primary>XGetGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetGeometry</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>Window<parameter> *root_return</parameter></paramdef>
+ <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+ <paramdef>unsignedint<parameter> *border_width_return</parameter></paramdef>
+ <paramdef>unsignedint<parameter> *depth_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Dr , which can be a window or a pixmap -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable(Dr.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the root window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the x and y coordinates that define the location of the drawable.
+For a window,
+these coordinates specify the upper-left outer corner relative to
+its parent's origin.
+For pixmaps, these coordinates are always zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the drawable's dimensions (width and height).
+For a window,
+these dimensions specify the inside size, not including the border.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the border width in pixels.
+If the drawable is a pixmap, it returns zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the depth of the drawable (bits per pixel for the object).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetGeometry</function>
+function returns the root window and the current geometry of the drawable.
+The geometry of the drawable includes the x and y coordinates, width and height,
+border width, and depth.
+These are described in the argument list.
+It is legal to pass to this function a window whose class is
+<function>InputOnly</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetGeometry</function>
+can generate a
+<function>BadDrawable</function>
+error.
+</para>
+</sect1>
+<sect1 id="Translating_Screen_Coordinates">
+<title>Translating Screen Coordinates</title>
+<!-- .XS -->
+<!-- (SN Translating Screen Coordinates -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications sometimes
+need to perform a coordinate transformation from the coordinate
+space of one window to another window or need to determine which
+window the pointing device is in.
+<function>XTranslateCoordinates</function>
+and
+<function>XQueryPointer</function>
+fulfill these needs (and avoid any race conditions) by
+asking the X server to perform these operations.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To translate a coordinate in one window to the coordinate
+space of another window, use
+<function>XTranslateCoordinates</function>.
+<indexterm significance="preferred"><primary>XTranslateCoordinates</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XTranslateCoordinates</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>
+ <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+ <paramdef>int*dest_x_return,<parameter> *dest_y_return</parameter></paramdef>
+ <paramdef>Window<parameter> *child_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates within the source window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the x and y coordinates within the destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>child_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the child if the coordinates are contained in a mapped child of the
+destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If
+<function>XTranslateCoordinates</function>
+returns
+<function>True</function>,
+it takes the src_x and src_y coordinates relative
+to the source window's origin and returns these coordinates to
+dest_x_return and dest_y_return
+relative to the destination window's origin.
+If
+<function>XTranslateCoordinates</function>
+returns
+<function>False</function>,
+src_w and dest_w are on different screens,
+and dest_x_return and dest_y_return are zero.
+If the coordinates are contained in a mapped child of dest_w,
+that child is returned to child_return.
+Otherwise, child_return is set to
+<function>None</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XTranslateCoordinates</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the screen coordinates of the pointer
+or to determine the pointer coordinates relative to a specified window, use
+<function>XQueryPointer</function>.
+<indexterm significance="preferred"><primary>XQueryPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XQueryPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window*root_return,<parameter> *child_return</parameter></paramdef>
+ <paramdef>int*root_x_return,<parameter> *root_y_return</parameter></paramdef>
+ <paramdef>int*win_x_return,<parameter> *win_y_return</parameter></paramdef>
+ <paramdef>unsignedint<parameter> *mask_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+<!-- .ds Ro that the pointer is in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the root window (Ro.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>child_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the child window that the pointer is located in, if any.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the pointer coordinates relative to the root window's origin.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>win_x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>win_y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the pointer coordinates relative to the specified window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current state of the modifier keys and pointer buttons.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryPointer</function>
+function returns the root window the pointer is logically on and the pointer
+coordinates relative to the root window's origin.
+If
+<function>XQueryPointer</function>
+returns
+<function>False</function>,
+the pointer is not on the same screen as the specified window, and
+<function>XQueryPointer</function>
+returns
+<function>None</function>
+to child_return and zero to win_x_return and win_y_return.
+If
+<function>XQueryPointer</function>
+returns
+<function>True</function>,
+the pointer coordinates returned to win_x_return and win_y_return
+are relative to the origin of the specified window.
+In this case,
+<function>XQueryPointer</function>
+returns the child that contains the pointer, if any,
+or else
+<function>None</function>
+to child_return.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryPointer</function>
+returns the current logical state of the keyboard buttons
+and the modifier keys in mask_return.
+It sets mask_return to the bitwise inclusive OR of one or more
+of the button or modifier key bitmasks to match
+the current state of the mouse buttons and the modifier keys.
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen through Xlib)
+may lag the physical state if device event processing is frozen
+(see section 12.1). <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryPointer</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Properties_and_Atoms">
+<title>Properties and Atoms</title>
+<!-- .XS -->
+<!-- (SN Properties and Atoms -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A property is a collection of named, typed data.
+The window system has a set of predefined properties
+<indexterm><primary>Atom</primary><secondary>predefined</secondary></indexterm>
+(for example, the name of a window, size hints, and so on), and users can
+define any other arbitrary information and associate it with windows.
+Each property has a name,
+which is an ISO Latin-1 string.
+For each named property,
+a unique identifier (atom) is associated with it.
+A property also has a type, for example, string or integer.
+These types are also indicated using atoms, so arbitrary new
+types can be defined.
+Data of only one type may be associated with a single
+property name.
+Clients can store and retrieve properties associated with windows.
+For efficiency reasons,
+an atom is used rather than a character string.
+<function>XInternAtom</function>
+can be used to obtain the atom for property names.
+<indexterm><primary>Atom</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+A property is also stored in one of several possible formats.
+The X server can store the information as 8-bit quantities, 16-bit
+quantities, or 32-bit quantities.
+This permits the X server to present the data in the byte order that the
+client expects.
+<!-- .NT Note -->
+If you define further properties of complex type,
+you must encode and decode them yourself.
+These functions must be carefully written if they are to be portable.
+For further information about how to write a library extension,
+see appendix C. <!-- xref -->
+<!-- .NE -->
+The type of a property is defined by an atom, which allows for
+arbitrary extension in this type scheme.
+<indexterm><primary>Atom</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Certain property names are
+predefined in the server for commonly used functions.
+The atoms for these properties are defined in
+<!-- .hN X11/Xatom.h . -->
+To avoid name clashes with user symbols, the
+<function>#define </function>
+name for each atom has the XA_ prefix.
+For an explanation of the functions that let you get and set
+much of the information stored in these predefined properties,
+see chapter 14. <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+The core protocol imposes no semantics on these property names,
+but semantics are specified in other X Consortium standards,
+such as the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>
+and the <emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+You can use properties to communicate other information between
+applications.
+The functions described in this section let you define new properties
+and get the unique atom IDs in your applications.
+</para>
+<para>
+<!-- .LP -->
+Although any particular atom can have some client interpretation
+within each of the name spaces,
+atoms occur in five distinct name spaces within the protocol:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Selections
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Property names
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Property types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Font properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Type of a
+<function>ClientMessage </function>
+event (none are built into the X server)
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The built-in selection property names are:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i 3i -->
+<!-- .ta .5i 1.5i 3i -->
+<!-- .R -->
+PRIMARY
+SECONDARY
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The built-in property names are:
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry>lw(2i) lw(2i).</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER0</entry>
+ <entry>RESOURCE_MANAGER</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER1</entry>
+ <entry>WM_CLASS</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER2</entry>
+ <entry>WM_CLIENT_MACHINE</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER3</entry>
+ <entry>WM_COLORMAP_WINDOWS</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER4</entry>
+ <entry>WM_COMMAND</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER5</entry>
+ <entry>WM_HINTS</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER6</entry>
+ <entry>WM_ICON_NAME</entry>
+ </row>
+ <row>
+ <entry>CUT_BUFFER7</entry>
+ <entry>WM_ICON_SIZE</entry>
+ </row>
+ <row>
+ <entry>RGB_BEST_MAP</entry>
+ <entry>WM_NAME</entry>
+ </row>
+ <row>
+ <entry>RGB_BLUE_MAP</entry>
+ <entry>WM_NORMAL_HINTS</entry>
+ </row>
+ <row>
+ <entry>RGB_DEFAULT_MAP</entry>
+ <entry>WM_PROTOCOLS</entry>
+ </row>
+ <row>
+ <entry>RGB_GRAY_MAP</entry>
+ <entry>WM_STATE</entry>
+ </row>
+ <row>
+ <entry>RGB_GREEN_MAP</entry>
+ <entry>WM_TRANSIENT_FOR</entry>
+ </row>
+ <row>
+ <entry>RGB_RED_MAP</entry>
+ <entry>WM_ZOOM_HINTS</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+The built-in property types are:
+</para>
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry>lw(2i) lw(2i).</entry>
+ </row>
+ <row>
+ <entry>ARC</entry>
+ <entry>POINT</entry>
+ </row>
+ <row>
+ <entry>ATOM</entry>
+ <entry>RGB_COLOR_MAP</entry>
+ </row>
+ <row>
+ <entry>BITMAP</entry>
+ <entry>RECTANGLE</entry>
+ </row>
+ <row>
+ <entry>CARDINAL</entry>
+ <entry>STRING</entry>
+ </row>
+ <row>
+ <entry>COLORMAP</entry>
+ <entry>VISUALID</entry>
+ </row>
+ <row>
+ <entry>CURSOR</entry>
+ <entry>WINDOW</entry>
+ </row>
+ <row>
+ <entry>DRAWABLE</entry>
+ <entry>WM_HINTS</entry>
+ </row>
+ <row>
+ <entry>FONT</entry>
+ <entry>WM_SIZE_HINTS</entry>
+ </row>
+ <row>
+ <entry>INTEGER</entry>
+ </row>
+ <row>
+ <entry>PIXMAP</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+The built-in font property names are:
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry>lw(2i) lw(2i).</entry>
+ </row>
+ <row>
+ <entry>MIN_SPACE</entry>
+ <entry>STRIKEOUT_DESCENT</entry>
+ </row>
+ <row>
+ <entry>NORM_SPACE</entry>
+ <entry>STRIKEOUT_ASCENT</entry>
+ </row>
+ <row>
+ <entry>MAX_SPACE</entry>
+ <entry>ITALIC_ANGLE</entry>
+ </row>
+ <row>
+ <entry>END_SPACE</entry>
+ <entry>X_HEIGHT</entry>
+ </row>
+ <row>
+ <entry>SUPERSCRIPT_X</entry>
+ <entry>QUAD_WIDTH</entry>
+ </row>
+ <row>
+ <entry>SUPERSCRIPT_Y</entry>
+ <entry>WEIGHT</entry>
+ </row>
+ <row>
+ <entry>SUBSCRIPT_X</entry>
+ <entry>POINT_SIZE</entry>
+ </row>
+ <row>
+ <entry>SUBSCRIPT_Y</entry>
+ <entry>RESOLUTION</entry>
+ </row>
+ <row>
+ <entry>UNDERLINE_POSITION</entry>
+ <entry>COPYRIGHT</entry>
+ </row>
+ <row>
+ <entry>UNDERLINE_THICKNESS</entry>
+ <entry>NOTICE</entry>
+ </row>
+ <row>
+ <entry>FONT_NAME</entry>
+ <entry>FAMILY_NAME</entry>
+ </row>
+ <row>
+ <entry>FULL_NAME</entry>
+ <entry>CAP_HEIGHT</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+For further information about font properties,
+see section 8.5. <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return an atom for a given name, use
+<function>XInternAtom</function>.
+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
+<indexterm significance="preferred"><primary>XInternAtom</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Atom<function> XInternAtom</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *atom_name</parameter></paramdef>
+ <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atom_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name associated with the atom you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>only_if_exists</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the atom must be created.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInternAtom</function>
+function returns the atom identifier associated with the specified atom_name
+string.
+If only_if_exists is
+<function>False</function>,
+the atom is created if it does not exist.
+Therefore,
+<function>XInternAtom</function>
+can return
+<function>None</function>.
+If the atom name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG''
+all designate different atoms.
+The atom will remain defined even after the client's connection closes.
+It will become undefined only when the last connection to
+the X server closes.
+</para>
+<para>
+<!-- .LP -->
+<function>XInternAtom</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return atoms for an array of names, use
+<function>XInternAtoms</function>.
+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
+<indexterm significance="preferred"><primary>XInternAtoms</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XInternAtoms</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> **names</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>
+ <paramdef>Atom<parameter> *atoms_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of atom names.
+<!-- .ds Cn atom names in the array -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>only_if_exists</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the atom must be created.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atoms_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the atoms.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInternAtoms</function>
+function returns the atom identifiers associated with the specified names.
+The atoms are stored in the atoms_return array supplied by the caller.
+Calling this function is equivalent to calling
+<function>XInternAtom</function>
+for each of the names in turn with the specified value of only_if_exists,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if atoms are returned for
+all of the names;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XInternAtoms</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a name for a given atom identifier, use
+<function>XGetAtomName</function>.
+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetAtomName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XGetAtomName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Atom<parameter> atom</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atom</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom for the property name you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetAtomName</function>
+function returns the name associated with the specified atom.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the resulting string,
+call
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetAtomName</function>
+can generate a
+<function>BadAtom </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the names for an array of atom identifiers, use
+<function>XGetAtomNames</function>.
+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetAtomNames</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetAtomNames</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Atom<parameter> *atoms</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>char<parameter> **names_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atoms</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of atoms.
+<!-- .ds Cn atoms in the array -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the atom names.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetAtomNames</function>
+function returns the names associated with the specified atoms.
+The names are stored in the names_return array supplied by the caller.
+Calling this function is equivalent to calling
+<function>XGetAtomName</function>
+for each of the atoms in turn,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if names are returned for
+all of the atoms;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetAtomNames</function>
+can generate a
+<function>BadAtom </function>
+error.
+</para>
+</sect1>
+<sect1 id="Obtaining_and_Changing_Window_Properties">
+<title>Obtaining and Changing Window Properties</title>
+<!-- .XS -->
+<!-- (SN Obtaining and Changing Window Properties -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can attach a property list to every window.
+Each property has a name, a type, and a value (see section 4.3). <!-- xref -->
+The value is an array of 8-bit, 16-bit, or 32-bit quantities,
+whose interpretation is left to the clients. The type
+<function>char</function>
+is used to represent 8-bit quantities, the type
+<function>short</function>
+is used to represent 16-bit quantities, and the type
+<function>long</function>
+is used to represent 32-bit quantities.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to obtain,
+change, update, or interchange window properties.
+In addition, Xlib provides other utility functions for inter-client
+communication (see chapter 14). <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the type, format, and value of a property of a given window, use
+<function>XGetWindowProperty</function>.
+<indexterm><primary>Property</primary><secondary>getting</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGetWindowProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGetWindowProperty</function></funcdef>
+ <paramdef><parameter> \^display</parameter></paramdef>
+ <paramdef><parameter> w</parameter></paramdef>
+ <paramdef><parameter> property</parameter></paramdef>
+ <paramdef><parameter> long_offset</parameter></paramdef>
+ <paramdef><parameter> long_length</parameter></paramdef>
+ <paramdef><parameter> delete</parameter></paramdef>
+ <paramdef><parameter> req_type</parameter></paramdef>
+ <paramdef><parameter> actual_type_return</parameter></paramdef>
+ <paramdef><parameter> actual_format_return</parameter></paramdef>
+ <paramdef><parameter> nitems_return</parameter></paramdef>
+ <paramdef><parameter> bytes_after_return</parameter></paramdef>
+ <paramdef>.br<parameter> prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property you want to obtain -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>long_offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset in the specified property (in 32-bit quantities)
+where the data is to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>long_length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length in 32-bit multiples of the data to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>delete</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that determines whether the property is deleted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>req_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom identifier associated with the property type or
+<function>AnyPropertyType</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actual_type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the atom identifier that defines the actual type of the property.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actual_format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual format of the property.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual number of 8-bit, 16-bit, or 32-bit items
+stored in the prop_return data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes_after_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of bytes remaining to be read in the property if
+a partial read was performed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the data in the specified format.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWindowProperty</function>
+function returns the actual type of the property; the actual format of the property;
+the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
+to be read in the property; and a pointer to the data actually returned.
+<function>XGetWindowProperty</function>
+sets the return arguments as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If the specified property does not exist for the specified window,
+<function>XGetWindowProperty </function>
+returns
+<function>None</function>
+to actual_type_return and the value zero to
+actual_format_return and bytes_after_return.
+The nitems_return argument is empty.
+In this case, the delete argument is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified property exists
+but its type does not match the specified type,
+<function>XGetWindowProperty </function>
+returns the actual property type to actual_type_return,
+the actual property format (never zero) to actual_format_return,
+and the property length in bytes
+(even if the actual_format_return is 16 or 32)
+to bytes_after_return.
+It also ignores the delete argument.
+The nitems_return argument is empty.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified property exists and either you assign
+<function>AnyPropertyType </function>
+to the req_type argument or the specified type matches the actual property type,
+<function>XGetWindowProperty </function>
+returns the actual property type to actual_type_return and the actual
+property format (never zero) to actual_format_return.
+It also returns a value to bytes_after_return and nitems_return, by
+defining the following
+values:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- .nf -->
+ N = actual length of the stored property in bytes
+ (even if the format is 16 or 32)
+ I = 4 * long_offset
+ T = N - I
+ L = MINIMUM(T, 4 * long_length)
+ A = N - (I + L)
+<!-- .fi -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The returned value starts at byte index I in the property (indexing
+from zero), and its length in bytes is L.
+If the value for long_offset causes L to be negative,
+a
+<function>BadValue</function>
+error results.
+The value of bytes_after_return is A,
+giving the number of trailing unread bytes in the stored property.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If the returned format is 8, the returned data is represented as a
+<function>char</function>
+array.
+If the returned format is 16, the returned data is represented as a
+<function>short</function>
+array and should be cast to that type to obtain the elements.
+If the returned format is 32, the returned data is represented as a
+<function>long</function>
+array and should be cast to that type to obtain the elements.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWindowProperty</function>
+always allocates one extra byte in prop_return
+(even if the property is zero length)
+and sets it to zero so that simple properties consisting of characters
+do not have to be copied into yet another string before use.
+</para>
+<para>
+<!-- .LP -->
+If delete is
+<function>True </function>
+and bytes_after_return is zero,
+<function>XGetWindowProperty</function>
+deletes the property
+from the window and generates a
+<function>PropertyNotify </function>
+event on the window.
+</para>
+<para>
+<!-- .LP -->
+The function returns
+<function>Success</function>
+if it executes successfully.
+To free the resulting data,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWindowProperty</function>
+can generate
+<function>BadAtom</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a given window's property list, use
+<function>XListProperties</function>.
+<indexterm><primary>Property</primary><secondary>listing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XListProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Atom<function> *XListProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> *num_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property list you want to obtain -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the length of the properties array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListProperties</function>
+function returns a pointer to an array of atom properties that are defined for
+the specified window or returns NULL if no properties were found.
+To free the memory allocated by this function, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XListProperties</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change a property of a given window, use
+<function>XChangeProperty</function>.
+<indexterm><primary>Property</primary><secondary>changing</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>appending</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>prepending</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>replacing</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>format</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>type</secondary></indexterm>
+<indexterm significance="preferred"><primary>XChangeProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atomproperty,<parameter> type</parameter></paramdef>
+ <paramdef>int<parameter> format</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> *data</parameter></paramdef>
+ <paramdef>int<parameter> nelements</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property you want to change -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the property.
+The X server does not interpret the type but simply
+passes it back to an application that later calls
+<function>XGetWindowProperty</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the data should be viewed as a list
+of 8-bit, 16-bit, or 32-bit quantities.
+Possible values are 8, 16, and 32.
+This information allows the X server to correctly perform
+byte-swap operations as necessary.
+If the format is 16-bit or 32-bit,
+you must explicitly cast your data pointer to an (unsigned char *) in the call
+to
+<function>XChangeProperty</function>.
+<!-- .\" Changed name of this file to prop_mode.a on 1/13/87 -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode of the operation.
+You can pass
+<function>PropModeReplace</function>,
+<function>PropModePrepend</function>,
+or
+<function>PropModeAppend</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nelements</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements of the specified data format.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeProperty</function>
+function alters the property for the specified window and
+causes the X server to generate a
+<function>PropertyNotify</function>
+event on that window.
+<function>XChangeProperty</function>
+performs the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If mode is
+<function>PropModeReplace</function>,
+<function>XChangeProperty</function>
+discards the previous property value and stores the new data.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If mode is
+<function>PropModePrepend</function>
+or
+<function>PropModeAppend</function>,
+<function>XChangeProperty</function>
+inserts the specified data before the beginning of the existing data
+or onto the end of the existing data, respectively.
+The type and format must match the existing property value,
+or a
+<function>BadMatch</function>
+error results.
+If the property is undefined,
+it is treated as defined with the correct type and
+format with zero-length data.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If the specified format is 8, the property data must be a
+<function>char</function>
+array.
+If the specified format is 16, the property data must be a
+<function>short</function>
+array.
+If the specified format is 32, the property data must be a
+<function>long</function>
+array.
+</para>
+<para>
+<!-- .LP -->
+The lifetime of a property is not tied to the storing client.
+Properties remain until explicitly deleted, until the window is destroyed,
+or until the server resets.
+For a discussion of what happens when the connection to the X server is closed,
+see section 2.6. <!-- xref -->
+The maximum size of a property is server dependent and can vary dynamically
+depending on the amount of memory the server has available.
+(If there is insufficient space, a
+<function>BadAlloc</function>
+error results.)
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeProperty</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rotate a window's property list, use
+<function>XRotateWindowProperties</function>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XRotateWindowProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRotateWindowProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atom<parameter> properties[]\^</parameter></paramdef>
+ <paramdef>int<parameter> num_prop</parameter></paramdef>
+ <paramdef>int<parameter> npositions</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>properties</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of properties that are to be rotated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the properties array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npositions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the rotation amount.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRotateWindowProperties</function>
+function allows you to rotate properties on a window and causes
+the X server to generate
+<function>PropertyNotify</function>
+events.
+If the property names in the properties array are viewed as being numbered
+starting from zero and if there are num_prop property names in the list,
+then the value associated with property name I becomes the value associated
+with property name (I + npositions) mod N for all I from zero to N \- 1.
+The effect is to rotate the states by npositions places around the virtual ring
+of property names (right for positive npositions,
+left for negative npositions).
+If npositions mod N is nonzero,
+the X server generates a
+<function>PropertyNotify</function>
+event for each property in the order that they are listed in the array.
+If an atom occurs more than once in the list or no property with that
+name is defined for the window,
+a
+<function>BadMatch </function>
+error results.
+If a
+<function>BadAtom </function>
+or
+<function>BadMatch </function>
+error results,
+no properties are changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XRotateWindowProperties</function>
+can generate
+<function>BadAtom</function>,
+<function>BadMatch</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete a property on a given window, use
+<function>XDeleteProperty</function>.
+<indexterm><primary>Property</primary><secondary>deleting</secondary></indexterm>
+<indexterm significance="preferred"><primary>XDeleteProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDeleteProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property you want to delete -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteProperty</function>
+function deletes the specified property only if the
+property was defined on the specified window
+and causes the X server to generate a
+<function>PropertyNotify</function>
+event on the window unless the property does not exist.
+</para>
+<para>
+<!-- .LP -->
+<function>XDeleteProperty</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Selections">
+<title>Selections</title>
+<!-- .XS -->
+<!-- (SN Selections -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Selection</primary></indexterm>
+Selections are one method used by applications to exchange data.
+By using the property mechanism,
+applications can exchange data of arbitrary types and can negotiate
+the type of the data.
+A selection can be thought of as an indirect property with a dynamic type.
+That is, rather than having the property stored in the X server,
+the property is maintained by some client (the owner).
+A selection is global in nature (considered to belong to the user
+but be maintained by clients) rather than being private to a particular
+window subhierarchy or a particular set of clients.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set, get, or request conversion
+of selections.
+This allows applications to implement the notion of current selection,
+which requires that notification be sent to applications when they no
+longer own the selection.
+Applications that support selection often highlight the current selection
+and so must be informed when another application has
+acquired the selection so that they can unhighlight the selection.
+</para>
+<para>
+<!-- .LP -->
+When a client asks for the contents of
+a selection, it specifies a selection target type.
+This target type
+can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or Z format.
+</para>
+<para>
+<!-- .LP -->
+The target type can also be used to control the class of
+contents transmitted, for example,
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, not the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the selection owner, use
+<function>XSetSelectionOwner</function>.
+<indexterm><primary>Selection</primary><secondary>setting the owner</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetSelectionOwner</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetSelectionOwner</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Atom<parameter> selection</parameter></paramdef>
+ <paramdef>Window<parameter> owner</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the owner of the specified selection atom.
+You can pass a window or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetSelectionOwner</function>
+function changes the owner and last-change time for the specified selection
+and has no effect if the specified time is earlier than the current
+last-change time of the specified selection
+or is later than the current X server time.
+Otherwise, the last-change time is set to the specified time,
+with
+<function>CurrentTime</function>
+replaced by the current server time.
+If the owner window is specified as
+<function>None</function>,
+then the owner of the selection becomes
+<function>None</function>
+(that is, no owner).
+Otherwise, the owner of the selection becomes the client executing
+the request.
+</para>
+<para>
+<!-- .LP -->
+If the new owner (whether a client or
+<function>None</function>)
+is not
+the same as the current owner of the selection and the current
+owner is not
+<function>None</function>,
+the current owner is sent a
+<function>SelectionClear </function>
+event.
+If the client that is the owner of a selection is later
+terminated (that is, its connection is closed)
+or if the owner window it has specified in the request is later
+destroyed,
+the owner of the selection automatically
+reverts to
+<function>None</function>,
+but the last-change time is not affected.
+The selection atom is uninterpreted by the X server.
+<function>XGetSelectionOwner</function>
+returns the owner window, which is reported in
+<function>SelectionRequest</function>
+and
+<function>SelectionClear</function>
+events.
+Selections are global to the X server.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetSelectionOwner</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the selection owner, use
+<function>XGetSelectionOwner</function>.
+<indexterm><primary>Selection</primary><secondary>getting the owner</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetSelectionOwner</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window<function> XGetSelectionOwner</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Atom<parameter> selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Se whose owner you want returned -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection atom (Se.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetSelectionOwner</function>
+function
+returns the window ID associated with the window that currently owns the
+specified selection.
+If no selection was specified, the function returns the constant
+<function>None</function>.
+If
+<function>None</function>
+is returned,
+there is no owner for the selection.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetSelectionOwner</function>
+can generate a
+<function>BadAtom </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To request conversion of a selection, use
+<function>XConvertSelection</function>.
+<indexterm><primary>Selection</primary><secondary>converting</secondary></indexterm>
+<indexterm significance="preferred"><primary>XConvertSelection</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XConvertSelection</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Atomselection,<parameter> target</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+ <paramdef>Window<parameter> requestor</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+You also can pass
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the requestor.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XConvertSelection</function>
+requests that the specified selection be converted to the specified target
+type:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If the specified selection has an owner, the X server sends a
+<function>SelectionRequest</function>
+event to that owner.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no owner for the specified
+selection exists, the X server generates a
+<function>SelectionNotify</function>
+event to the
+requestor with property
+<function>None</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The arguments are passed on unchanged in either of the events.
+There are two predefined selection atoms: PRIMARY and SECONDARY.
+</para>
+<para>
+<!-- .LP -->
+<function>XConvertSelection</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow </function>
+errors.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH05 b/libX11/specs/libX11/CH05 deleted file mode 100644 index 6ea218378..000000000 --- a/libX11/specs/libX11/CH05 +++ /dev/null @@ -1,518 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 5\fP\s-1 - -\s+1\fBPixmap and Cursor Functions\fP\s-1 -.sp 2 -.nr H1 5 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 5: Pixmap and Cursor Functions -.XE -Once you have connected to an X server, -you can use the Xlib functions to: -.IP \(bu 5 -Create and free pixmaps -.IP \(bu 5 -Create, recolor, and free cursors -.NH 2 -Creating and Freeing Pixmaps -.XS -\*(SN Creating and Freeing Pixmaps -.XE -.LP -Pixmaps can only be used on the screen on which they were created. -Pixmaps are off-screen resources that are used for various operations, -such as defining cursors as tiling patterns -or as the source for certain raster operations. -Most graphics requests can operate either on a window or on a pixmap. -A bitmap is a single bit-plane pixmap. -.LP -.sp -To create a pixmap of a given size, use -.PN XCreatePixmap . -.IN "XCreatePixmap" "" "@DEF@" -.sM -.FD 0 -Pixmap XCreatePixmap\^(\^\fIdisplay\fP, \fId\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdepth\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned int \fIdepth\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies which screen the pixmap is created on. -.ds Wh , which define the dimensions of the pixmap -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIdepth\fP 1i -Specifies the depth of the pixmap. -.LP -.eM -The -.PN XCreatePixmap -function creates a pixmap of the width, height, and depth you specified -and returns a pixmap ID that identifies it. -It is valid to pass an -.PN InputOnly -window to the drawable argument. -The width and height arguments must be nonzero, -or a -.PN BadValue -error results. -The depth argument must be one of the depths supported by the screen -of the specified drawable, -or a -.PN BadValue -error results. -.LP -The server uses the specified drawable to determine on which screen -to create the pixmap. -The pixmap can be used only on this screen -and only with other drawables of the same depth (see -.PN XCopyPlane -for an exception to this rule). -The initial contents of the pixmap are undefined. -.LP -.PN XCreatePixmap -can generate -.PN BadAlloc , -.PN BadDrawable , -and -.PN BadValue -errors. -.LP -.sp -To free all storage associated with a specified pixmap, use -.PN XFreePixmap . -.IN "XFreePixmap" "" "@DEF@" -.sM -.FD 0 -XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Pixmap \fIpixmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIpixmap\fP 1i -Specifies the pixmap. -.LP -.eM -The -.PN XFreePixmap -function first deletes the association between the pixmap ID and the pixmap. -Then, the X server frees the pixmap storage when there are no references to it. -The pixmap should never be referenced again. -.LP -.PN XFreePixmap -can generate a -.PN BadPixmap -error. -.NH 2 -Creating, Recoloring, and Freeing Cursors -.XS -\*(SN Creating, Recoloring, and Freeing Cursors -.XE -.LP -Each window can have a different cursor defined for it. -Whenever the pointer is in a visible window, -it is set to the cursor defined for that window. -If no cursor was defined for that window, -the cursor is the one defined for the parent window. -.LP -From X's perspective, -a cursor consists of a cursor source, mask, colors, and a hotspot. -The mask pixmap determines the shape of the cursor and must be a depth -of one. -The source pixmap must have a depth of one, -and the colors determine the colors of the source. -The hotspot defines the point on the cursor that is reported -when a pointer event occurs. -There may be limitations imposed by the hardware on -cursors as to size and whether a mask is implemented. -.IN "XQueryBestCursor" -.PN XQueryBestCursor -can be used to find out what sizes are possible. -There is a standard font for creating cursors, but -Xlib provides functions that you can use to create cursors -from an arbitrary font or from bitmaps. -.LP -.sp -To create a cursor from the standard cursor font, use -.PN XCreateFontCursor . -.IN "XCreateFontCursor" "" "@DEF@" -.sM -.FD 0 -#include <X11/cursorfont.h> -.sp 6p -Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned int \fIshape\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIshape\fP 1i -Specifies the shape of the cursor. -.LP -.eM -X provides a set of standard cursor shapes in a special font named -cursor. -Applications are encouraged to use this interface for their cursors -because the font can be customized for the individual display type. -The shape argument specifies which glyph of the standard fonts -to use. -.LP -The hotspot comes from the information stored in the cursor font. -The initial colors of a cursor are a black foreground and a white -background (see -.PN XRecolorCursor ). -For further information about cursor shapes, -see appendix B. -.LP -.PN XCreateFontCursor -can generate -.PN BadAlloc -and -.PN BadValue -errors. -.LP -.sp -To create a cursor from font glyphs, use -.PN XCreateGlyphCursor . -.IN "XCreateGlyphCursor" "" "@DEF@" -.sM -.FD 0 -Cursor XCreateGlyphCursor\^(\^\fIdisplay\fP, \fIsource_font\fP\^, \fImask_font\fP\^, \fIsource_char\fP\^, \fImask_char\fP\^, -.br - \fIforeground_color\fP\^, \fIbackground_color\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Font \fIsource_font\fP\^, \fImask_font\fP\^; -.br - unsigned int \fIsource_char\fP\^, \fImask_char\fP\^; -.br - XColor *\fIforeground_color\fP\^; -.br - XColor *\fIbackground_color\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsource_font\fP 1i -Specifies the font for the source glyph. -.IP \fImask_font\fP 1i -Specifies the font for the mask glyph or -.PN None . -.IP \fIsource_char\fP 1i -Specifies the character glyph for the source. -.IP \fImask_char\fP 1i -Specifies the glyph character for the mask. -.IP \fIforeground_color\fP 1i -Specifies the RGB values for the foreground of the source. -.IP \fIbackground_color\fP 1i -Specifies the RGB values for the background of the source. -.LP -.eM -The -.PN XCreateGlyphCursor -function is similar to -.PN XCreatePixmapCursor -except that the source and mask bitmaps are obtained from the specified -font glyphs. -The source_char must be a defined glyph in source_font, -or a -.PN BadValue -error results. -If mask_font is given, -mask_char must be a defined glyph in mask_font, -or a -.PN BadValue -error results. -The mask_font and character are optional. -The origins of the source_char and mask_char (if defined) glyphs are -positioned coincidently and define the hotspot. -The source_char and mask_char need not have the same bounding box metrics, -and there is no restriction on the placement of the hotspot relative to the bounding -boxes. -If no mask_char is given, all pixels of the source are displayed. -You can free the fonts immediately by calling -.PN XFreeFont -if no further explicit references to them are to be made. -.LP -For 2-byte matrix fonts, -the 16-bit value should be formed with the byte1 -member in the most significant byte and the byte2 member in the -least significant byte. -.LP -.PN XCreateGlyphCursor -can generate -.PN BadAlloc , -.PN BadFont , -and -.PN BadValue -errors. -.LP -.sp -To create a cursor from two bitmaps, -use -.PN XCreatePixmapCursor . -.IN "XCreatePixmapCursor" "" "@DEF@" -.sM -.FD 0 -Cursor XCreatePixmapCursor\^(\^\fIdisplay\fP, \fIsource\fP\^, \fImask\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Pixmap \fIsource\fP\^; -.br - Pixmap \fImask\fP\^; -.br - XColor *\fIforeground_color\fP\^; -.br - XColor *\fIbackground_color\fP\^; -.br - unsigned int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsource\fP 1i -Specifies the shape of the source cursor. -.\" *** JIM: NEED TO CHECK THIS. *** -.IP \fImask\fP 1i -Specifies the cursor's source bits to be displayed or -.PN None . -.IP \fIforeground_color\fP 1i -Specifies the RGB values for the foreground of the source. -.IP \fIbackground_color\fP 1i -Specifies the RGB values for the background of the source. -.ds Xy , which indicate the hotspot relative to the source's origin -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.LP -.eM -The -.PN XCreatePixmapCursor -function creates a cursor and returns the cursor ID associated with it. -The foreground and background RGB values must be specified using -foreground_color and background_color, -even if the X server only has a -.PN StaticGray -or -.PN GrayScale -screen. -The foreground color is used for the pixels set to 1 in the -source, and the background color is used for the pixels set to 0. -Both source and mask, if specified, must have depth one (or a -.PN BadMatch -error results) but can have any root. -The mask argument defines the shape of the cursor. -The pixels set to 1 in the mask define which source pixels are displayed, -and the pixels set to 0 define which pixels are ignored. -If no mask is given, -all pixels of the source are displayed. -The mask, if present, must be the same size as the pixmap defined by the -source argument, or a -.PN BadMatch -error results. -The hotspot must be a point within the source, -or a -.PN BadMatch -error results. -.LP -The components of the cursor can be transformed arbitrarily to meet -display limitations. -The pixmaps can be freed immediately if no further explicit references -to them are to be made. -Subsequent drawing in the source or mask pixmap has an undefined effect on the -cursor. -The X server might or might not make a copy of the pixmap. -.LP -.PN XCreatePixmapCursor -can generate -.PN BadAlloc -and -.PN BadPixmap -errors. -.LP -.sp -To determine useful cursor sizes, use -.PN XQueryBestCursor . -.IN "XQueryBestCursor" "" "@DEF@" -.sM -.FD 0 -Status XQueryBestCursor\^(\^\fIdisplay\fP, \fId\fP, \fIwidth\fP\^, \fIheight\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Dr , which indicates the screen -.IP \fId\fP 1i -Specifies the drawable\*(Dr. -.ds Wh \ of the cursor that you want the size information for -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the best width and height that is closest to the specified width -and height. -.LP -.eM -Some displays allow larger cursors than other displays. -The -.PN XQueryBestCursor -function provides a way to find out what size cursors are actually -possible on the display. -.IN "Cursor" "limitations" -It returns the largest size that can be displayed. -Applications should be prepared to use smaller cursors on displays that -cannot support large ones. -.LP -.PN XQueryBestCursor -can generate a -.PN BadDrawable -error. -.LP -.sp -To change the color of a given cursor, use -.PN XRecolorCursor . -.IN "XRecolorCursor" "" "@DEF@" -.sM -.FD 0 -XRecolorCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Cursor \fIcursor\fP\^; -.br - XColor *\fIforeground_color\fP\^, *\fIbackground_color\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcursor\fP 1i -Specifies the cursor. -.IP \fIforeground_color\fP 1i -Specifies the RGB values for the foreground of the source. -.IP \fIbackground_color\fP 1i -Specifies the RGB values for the background of the source. -.LP -.eM -The -.PN XRecolorCursor -function changes the color of the specified cursor, and -if the cursor is being displayed on a screen, -the change is visible immediately. -The pixel members of the -.PN XColor -structures are ignored; only the RGB values are used. -.LP -.PN XRecolorCursor -can generate a -.PN BadCursor -error. -.LP -.sp -To free (destroy) a given cursor, use -.PN XFreeCursor . -.IN "XFreeCursor" "" "@DEF@" -.sM -.FD 0 -XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Cursor \fIcursor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcursor\fP 1i -Specifies the cursor. -.LP -.eM -The -.PN XFreeCursor -function deletes the association between the cursor resource ID -and the specified cursor. -The cursor storage is freed when no other resource references it. -The specified cursor ID should not be referred to again. -.LP -.PN XFreeCursor -can generate a -.PN BadCursor -error. -.bp diff --git a/libX11/specs/libX11/CH05.xml b/libX11/specs/libX11/CH05.xml new file mode 100644 index 000000000..449272a19 --- /dev/null +++ b/libX11/specs/libX11/CH05.xml @@ -0,0 +1,815 @@ +<chapter id="pixmap_and_cursor_functions">
+<title>Pixmap and Cursor Functions</title>
+<sect1 id="Creating_and_Freeing_Pixmaps">
+<title>Creating and Freeing Pixmaps</title>
+<!-- .XS -->
+<!-- (SN Creating and Freeing Pixmaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Pixmaps can only be used on the screen on which they were created.
+Pixmaps are off-screen resources that are used for various operations,
+such as defining cursors as tiling patterns
+or as the source for certain raster operations.
+Most graphics requests can operate either on a window or on a pixmap.
+A bitmap is a single bit-plane pixmap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a pixmap of a given size, use
+<function>XCreatePixmap</function>.
+<indexterm significance="preferred"><primary>XCreatePixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Pixmap<function> XCreatePixmap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint<parameter> depth</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which screen the pixmap is created on.
+<!-- .ds Wh , which define the dimensions of the pixmap -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the depth of the pixmap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreatePixmap</function>
+function creates a pixmap of the width, height, and depth you specified
+and returns a pixmap ID that identifies it.
+It is valid to pass an
+<function>InputOnly</function>
+window to the drawable argument.
+The width and height arguments must be nonzero,
+or a
+<function>BadValue</function>
+error results.
+The depth argument must be one of the depths supported by the screen
+of the specified drawable,
+or a
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The server uses the specified drawable to determine on which screen
+to create the pixmap.
+The pixmap can be used only on this screen
+and only with other drawables of the same depth (see
+<function>XCopyPlane</function>
+for an exception to this rule).
+The initial contents of the pixmap are undefined.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreatePixmap</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadDrawable</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free all storage associated with a specified pixmap, use
+<function>XFreePixmap</function>.
+<indexterm significance="preferred"><primary>XFreePixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreePixmap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pixmap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreePixmap</function>
+function first deletes the association between the pixmap ID and the pixmap.
+Then, the X server frees the pixmap storage when there are no references to it.
+The pixmap should never be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreePixmap</function>
+can generate a
+<function>BadPixmap </function>
+error.
+</para>
+</sect1>
+<sect1 id="Creating_Recoloring_and_Freeing_Cursors">
+<title>Creating, Recoloring, and Freeing Cursors</title>
+<!-- .XS -->
+<!-- (SN Creating, Recoloring, and Freeing Cursors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Each window can have a different cursor defined for it.
+Whenever the pointer is in a visible window,
+it is set to the cursor defined for that window.
+If no cursor was defined for that window,
+the cursor is the one defined for the parent window.
+</para>
+<para>
+<!-- .LP -->
+From X's perspective,
+a cursor consists of a cursor source, mask, colors, and a hotspot.
+The mask pixmap determines the shape of the cursor and must be a depth
+of one.
+The source pixmap must have a depth of one,
+and the colors determine the colors of the source.
+The hotspot defines the point on the cursor that is reported
+when a pointer event occurs.
+There may be limitations imposed by the hardware on
+cursors as to size and whether a mask is implemented.
+<indexterm><primary>XQueryBestCursor</primary></indexterm>
+<function>XQueryBestCursor</function>
+can be used to find out what sizes are possible.
+There is a standard font for creating cursors, but
+Xlib provides functions that you can use to create cursors
+from an arbitrary font or from bitmaps.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a cursor from the standard cursor font, use
+<function>XCreateFontCursor</function>.
+</para>
+<para>
+#include <X11/cursorfont.h>
+</para>
+
+<indexterm significance="preferred"><primary>XCreateFontCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Cursor<function> XCreateFontCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> shape</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>shape</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shape of the cursor.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+X provides a set of standard cursor shapes in a special font named
+cursor.
+Applications are encouraged to use this interface for their cursors
+because the font can be customized for the individual display type.
+The shape argument specifies which glyph of the standard fonts
+to use.
+</para>
+<para>
+<!-- .LP -->
+The hotspot comes from the information stored in the cursor font.
+The initial colors of a cursor are a black foreground and a white
+background (see
+<function>XRecolorCursor</function>).
+For further information about cursor shapes,
+see appendix B.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateFontCursor</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a cursor from font glyphs, use
+<function>XCreateGlyphCursor</function>.
+<indexterm significance="preferred"><primary>XCreateGlyphCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Cursor<function> XCreateGlyphCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Fontsource_font,<parameter> mask_font</parameter></paramdef>
+ <paramdef>unsignedintsource_char,<parameter> mask_char</parameter></paramdef>
+ <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>
+ <paramdef>XColor<parameter> *background_color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source_font</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font for the source glyph.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask_font</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font for the mask glyph or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source_char</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character glyph for the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask_char</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the glyph character for the mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>foreground_color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <acronym>RGB</acronym> values for the foreground of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background_color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <acronym>RGB</acronym> values for the background of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateGlyphCursor</function>
+function is similar to
+<function>XCreatePixmapCursor</function>
+except that the source and mask bitmaps are obtained from the specified
+font glyphs.
+The source_char must be a defined glyph in source_font,
+or a
+<function>BadValue</function>
+error results.
+If mask_font is given,
+mask_char must be a defined glyph in mask_font,
+or a
+<function>BadValue</function>
+error results.
+The mask_font and character are optional.
+The origins of the source_char and mask_char (if defined) glyphs are
+positioned coincidently and define the hotspot.
+The source_char and mask_char need not have the same bounding box metrics,
+and there is no restriction on the placement of the hotspot relative to the bounding
+boxes.
+If no mask_char is given, all pixels of the source are displayed.
+You can free the fonts immediately by calling
+<function>XFreeFont</function>
+if no further explicit references to them are to be made.
+</para>
+<para>
+<!-- .LP -->
+For 2-byte matrix fonts,
+the 16-bit value should be formed with the byte1
+member in the most significant byte and the byte2 member in the
+least significant byte.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateGlyphCursor</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadFont</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a cursor from two bitmaps,
+use
+<function>XCreatePixmapCursor</function>.
+<indexterm significance="preferred"><primary>XCreatePixmapCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Cursor<function> XCreatePixmapCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Pixmap<parameter> source</parameter></paramdef>
+ <paramdef>Pixmap<parameter> mask</parameter></paramdef>
+ <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>
+ <paramdef>XColor<parameter> *background_color</parameter></paramdef>
+ <paramdef>unsignedintx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shape of the source cursor.
+<!-- .\" *** JIM: NEED TO CHECK THIS. *** -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor's source bits to be displayed or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>foreground_color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <acronym>RGB</acronym> values for the foreground of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background_color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <acronym>RGB</acronym> values for the background of the source.
+<!-- .ds Xy , which indicate the hotspot relative to the source's origin -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreatePixmapCursor</function>
+function creates a cursor and returns the cursor ID associated with it.
+The foreground and background <acronym>RGB</acronym> values must be specified using
+foreground_color and background_color,
+even if the X server only has a
+<function>StaticGray</function>
+or
+<function>GrayScale</function>
+screen.
+The foreground color is used for the pixels set to 1 in the
+source, and the background color is used for the pixels set to 0.
+Both source and mask, if specified, must have depth one (or a
+<function>BadMatch</function>
+error results) but can have any root.
+The mask argument defines the shape of the cursor.
+The pixels set to 1 in the mask define which source pixels are displayed,
+and the pixels set to 0 define which pixels are ignored.
+If no mask is given,
+all pixels of the source are displayed.
+The mask, if present, must be the same size as the pixmap defined by the
+source argument, or a
+<function>BadMatch</function>
+error results.
+The hotspot must be a point within the source,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The components of the cursor can be transformed arbitrarily to meet
+display limitations.
+The pixmaps can be freed immediately if no further explicit references
+to them are to be made.
+Subsequent drawing in the source or mask pixmap has an undefined effect on the
+cursor.
+The X server might or might not make a copy of the pixmap.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreatePixmapCursor</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadPixmap</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine useful cursor sizes, use
+<function>XQueryBestCursor</function>.
+<indexterm significance="preferred"><primary>XQueryBestCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XQueryBestCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Dr , which indicates the screen -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable(Dr.
+<!-- .ds Wh \ of the cursor that you want the size information for -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the best width and height that is closest to the specified width
+and height.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Some displays allow larger cursors than other displays.
+The
+<function>XQueryBestCursor</function>
+function provides a way to find out what size cursors are actually
+possible on the display.
+<indexterm ><primary>Cursor</primary><secondary>limitations</secondary></indexterm>
+It returns the largest size that can be displayed.
+Applications should be prepared to use smaller cursors on displays that
+cannot support large ones.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestCursor</function>
+can generate a
+<function>BadDrawable </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the color of a given cursor, use
+<function>XRecolorCursor</function>.
+<indexterm significance="preferred"><primary>XRecolorCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRecolorCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+ <paramdef>XColor*foreground_color,<parameter> *background_color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>foreground_color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <acronym>RGB</acronym> values for the foreground of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background_color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <acronym>RGB</acronym> values for the background of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRecolorCursor</function>
+function changes the color of the specified cursor, and
+if the cursor is being displayed on a screen,
+the change is visible immediately.
+The pixel members of the
+<function>XColor</function>
+structures are ignored; only the <acronym>RGB</acronym> values are used.
+</para>
+<para>
+<!-- .LP -->
+<function>XRecolorCursor</function>
+can generate a
+<function>BadCursor </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free (destroy) a given cursor, use
+<function>XFreeCursor</function>.
+<indexterm significance="preferred"><primary>XFreeCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeCursor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeCursor</function>
+function deletes the association between the cursor resource ID
+and the specified cursor.
+The cursor storage is freed when no other resource references it.
+The specified cursor ID should not be referred to again.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeCursor</function>
+can generate a
+<function>BadCursor </function>
+error.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH06 b/libX11/specs/libX11/CH06 deleted file mode 100644 index 44824d324..000000000 --- a/libX11/specs/libX11/CH06 +++ /dev/null @@ -1,4773 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 6\fP\s-1 - -\s+1\fBColor Management Functions\fP\s-1 -.sp 2 -.nr H1 6 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 6: Color Management Functions -.XE -Each X window always has an associated colormap that -provides a level of indirection between pixel values and colors displayed -on the screen. -Xlib provides functions that you can use to manipulate a colormap. -The X protocol defines colors using values in the RGB color space. -The RGB color space is device dependent; -rendering an RGB value on differing output devices typically results -in different colors. -Xlib also provides a means for clients to specify color using -device-independent color spaces for consistent results across devices. -Xlib supports device-independent color spaces derivable from the CIE XYZ -color space. -This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as -the TekHVC color space. -.LP -This chapter discusses how to: -.IP \(bu 5 -Create, copy, and destroy a colormap -.IP \(bu 5 -Specify colors by name or value -.IP \(bu 5 -Allocate, modify, and free color cells -.IP \(bu 5 -Read entries in a colormap -.IP \(bu 5 -Convert between color spaces -.IP \(bu 5 -Control aspects of color conversion -.IP \(bu 5 -Query the color gamut of a screen -.IP \(bu 5 -Add new color spaces -.LP -All functions, types, and symbols in this chapter with the prefix ``Xcms'' -are defined in -.hN X11/Xcms.h . -The remaining functions and types are defined in -.hN X11/Xlib.h . -.LP -Functions in this chapter manipulate the representation of color on the -screen. -For each possible value that a pixel can take in a window, -there is a color cell in the colormap. -For example, -if a window is 4 bits deep, pixel values 0 through 15 are defined. -A colormap is a collection of color cells. -A color cell consists of a triple of red, green, and blue (RGB) values. -The hardware imposes limits on the number of significant -bits in these values. -As each pixel is read out of display memory, the pixel -is looked up in a colormap. -The RGB value of the cell determines what color is displayed on the screen. -On a grayscale display with a black-and-white monitor, -the values are combined to determine the brightness on the screen. -.LP -Typically, an application allocates color cells or sets of color cells -to obtain the desired colors. -The client can allocate read-only cells. -In which case, -the pixel values for these colors can be shared among multiple applications, -and the RGB value of the cell cannot be changed. -If the client allocates read/write cells, -they are exclusively owned by the client, -and the color associated with the pixel value can be changed at will. -Cells must be allocated (and, if read/write, initialized with an RGB value) -by a client to obtain desired colors. -The use of pixel value for an -unallocated cell results in an undefined color. -.LP -Because colormaps are associated with windows, X supports displays -with multiple colormaps and, indeed, different types of colormaps. -If there are insufficient colormap resources in the display, -some windows will display in their true colors, and others -will display with incorrect colors. -A window manager usually controls which windows are displayed -in their true colors if more than one colormap is required for -the color resources the applications are using. -At any time, there is a set of installed colormaps for a screen. -Windows using one of the installed colormaps display with true colors, and -windows using other colormaps generally display with incorrect colors. -You can control the set of installed colormaps by using -.PN XInstallColormap -and -.PN XUninstallColormap . -.LP -Colormaps are local to a particular screen. -Screens always have a default colormap, -and programs typically allocate cells out of this colormap. -Generally, you should not write applications that monopolize -color resources. -Although some hardware supports multiple colormaps installed at one time, -many of the hardware displays -built today support only a single installed colormap, so the primitives -are written to encourage sharing of colormap entries between applications. -.LP -The -.PN DefaultColormap -macro returns the default colormap. -The -.PN DefaultVisual -macro -returns the default visual type for the specified screen. -.IN "Color map" -Possible visual types are -.PN StaticGray , -.PN GrayScale , -.PN StaticColor , -.PN PseudoColor , -.PN TrueColor , -or -.PN DirectColor -(see section 3.1). -.NH 2 -Color Structures -.XS -\*(SN Color Structures -.XE -.LP -Functions that operate only on RGB color space values use an -.PN XColor -structure, which contains: -.LP -.IN "XColor" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - unsigned long pixel; /* pixel value */ - unsigned short red, green, blue; /* rgb values */ - char flags; /* DoRed, DoGreen, DoBlue */ - char pad; -} XColor; -.De -.LP -.eM -The red, green, and blue values are always in the range 0 to 65535 -inclusive, independent of the number of bits actually used in the -display hardware. -The server scales these values down to the range used by the hardware. -Black is represented by (0,0,0), -and white is represented by (65535,65535,65535). -.IN "Color" -In some functions, -the flags member controls which of the red, green, and blue members is used -and can be the inclusive OR of zero or more of -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue . -.LP -.sp -Functions that operate on all color space values use an -.PN XcmsColor -structure. -This structure contains a union of substructures, -each supporting color specification encoding for a particular color space. -Like the -.PN XColor -structure, the -.PN XcmsColor -structure contains pixel -and color specification information (the spec member in the -.PN XcmsColor -structure). -.IN "XcmsColor" "" "@DEF@" -.sM -.LP -.Ds 0 -.TA .5i 1i 2.5i -.ta .5i 1i 2.5i -typedef unsigned long XcmsColorFormat; /* Color Specification Format */ - -typedef struct { - union { - XcmsRGB RGB; - XcmsRGBi RGBi; - XcmsCIEXYZ CIEXYZ; - XcmsCIEuvY CIEuvY; - XcmsCIExyY CIExyY; - XcmsCIELab CIELab; - XcmsCIELuv CIELuv; - XcmsTekHVC TekHVC; - XcmsPad Pad; - } spec; - unsigned long pixel; - XcmsColorFormat format; -} XcmsColor; /* Xcms Color Structure */ -.De -.LP -.eM -Because the color specification can be encoded for the various color spaces, -encoding for the spec member is identified by the format member, -which is of type -.PN XcmsColorFormat . -The following macros define standard formats. -.sM -.TS -lw(.5i) lw(1.6i) lw(1.4i) lw(1.5i). -T{ -#define -T} T{ -.PN XcmsUndefinedFormat -T} T{ -0x00000000 -T} -T{ -#define -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -0x00000001 -T} T{ -/* CIE XYZ */ -T} -T{ -#define -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -0x00000002 -T} T{ -/* CIE u'v'Y */ -T} -T{ -#define -T} T{ -.PN XcmsCIExyYFormat -T} T{ -0x00000003 -T} T{ -/* CIE xyY */ -T} -T{ -#define -T} T{ -.PN XcmsCIELabFormat -T} T{ -0x00000004 -T} T{ -/* CIE L*a*b* */ -T} -T{ -#define -T} T{ -.PN XcmsCIELuvFormat -T} T{ -0x00000005 -T} T{ -/* CIE L*u*v* */ -T} -T{ -#define -T} T{ -.PN XcmsTekHVCFormat -T} T{ -0x00000006 -T} T{ -/* TekHVC */ -T} -T{ -#define -T} T{ -.PN XcmsRGBFormat -T} T{ -0x80000000 -T} T{ -/* RGB Device */ -T} -T{ -#define -T} T{ -.PN XcmsRGBiFormat -T} T{ -0x80000001 -T} T{ -/* RGB Intensity */ -T} -.TE -.LP -.eM -Formats for device-independent color spaces are -distinguishable from those for device-dependent spaces by the 32nd bit. -If this bit is set, -it indicates that the color specification is in a device-dependent form; -otherwise, it is in a device-independent form. -If the 31st bit is set, -this indicates that the color space has been added to Xlib at run time -(see section 6.12.4). -The format value for a color space added at run time may be different each -time the program is executed. -If references to such a color space must be made outside the client -(for example, storing a color specification in a file), -then reference should be made by color space string prefix -(see -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.LP -Data types that describe the color specification encoding for the various -color spaces are defined as follows: -.sM -.IN "XcmsRGB" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef double XcmsFloat; - -typedef struct { - unsigned short red; /* 0x0000 to 0xffff */ - unsigned short green; /* 0x0000 to 0xffff */ - unsigned short blue; /* 0x0000 to 0xffff */ -} XcmsRGB; /* RGB Device */ -.De -.IN "XcmsRGBi" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat red; /* 0.0 to 1.0 */ - XcmsFloat green; /* 0.0 to 1.0 */ - XcmsFloat blue; /* 0.0 to 1.0 */ -} XcmsRGBi; /* RGB Intensity */ -.De -.IN "XcmsCIEXYZ" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat X; - XcmsFloat Y; /* 0.0 to 1.0 */ - XcmsFloat Z; -} XcmsCIEXYZ; /* CIE XYZ */ -.De -.IN "XcmsCIEuvY" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat u_prime; /* 0.0 to ~0.6 */ - XcmsFloat v_prime; /* 0.0 to ~0.6 */ - XcmsFloat Y; /* 0.0 to 1.0 */ -} XcmsCIEuvY; /* CIE u'v'Y */ -.De -.IN "XcmsCIExyY" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat x; /* 0.0 to ~.75 */ - XcmsFloat y; /* 0.0 to ~.85 */ - XcmsFloat Y; /* 0.0 to 1.0 */ -} XcmsCIExyY; /* CIE xyY */ -.De -.IN "XcmsCIELab" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat L_star; /* 0.0 to 100.0 */ - XcmsFloat a_star; - XcmsFloat b_star; -} XcmsCIELab; /* CIE L*a*b* */ -.De -.IN "XcmsCIELuv" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat L_star; /* 0.0 to 100.0 */ - XcmsFloat u_star; - XcmsFloat v_star; -} XcmsCIELuv; /* CIE L*u*v* */ -.De -.IN "XcmsTekHVC" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat H; /* 0.0 to 360.0 */ - XcmsFloat V; /* 0.0 to 100.0 */ - XcmsFloat C; /* 0.0 to 100.0 */ -} XcmsTekHVC; /* TekHVC */ -.De -.IN "XcmsPad" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat pad0; - XcmsFloat pad1; - XcmsFloat pad2; - XcmsFloat pad3; -} XcmsPad; /* four doubles */ -.De -.LP -.eM -The device-dependent formats provided allow color specification in: -.IP \(bu 5 -RGB Intensity -.Pn ( XcmsRGBi ) -.IP -Red, green, and blue linear intensity values, -floating-point values from 0.0 to 1.0, -where 1.0 indicates full intensity, 0.5 half intensity, and so on. -.IP \(bu 5 -RGB Device -.Pn ( XcmsRGB ) -.IP -Red, green, and blue values appropriate for the specified output device. -.PN XcmsRGB -values are of type unsigned short, -scaled from 0 to 65535 inclusive, -and are interchangeable with the red, green, and blue values in an -.PN XColor -structure. -.LP -It is important to note that RGB Intensity values are not gamma corrected -values. -In contrast, -RGB Device values generated as a result of converting color specifications -are always gamma corrected, and -RGB Device values acquired as a result of querying a colormap -or passed in by the client are assumed by Xlib to be gamma corrected. -The term \fIRGB value\fP in this manual always refers to an RGB Device value. -.NH 2 -Color Strings -.XS -\*(SN Color Strings -.XE -.LP -Xlib provides a mechanism for using string names for colors. -A color string may either contain an abstract color name -or a numerical color specification. -Color strings are case-insensitive. -.LP -Color strings are used in the following functions: -.IP \(bu 5 -.PN XAllocNamedColor -.IP \(bu 5 -.PN XcmsAllocNamedColor -.IP \(bu 5 -.PN XLookupColor -.IP \(bu 5 -.PN XcmsLookupColor -.IP \(bu 5 -.PN XParseColor -.IP \(bu 5 -.PN XStoreNamedColor -.LP -Xlib supports the use of abstract color names, for example, red or blue. -A value for this abstract name is obtained by searching one or more color -name databases. -Xlib first searches zero or more client-side databases; -the number, location, and content of these databases is -implementation-dependent and might depend on the current locale. -If the name is not found, Xlib then looks for the color in the -X server's database. -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -.LP -A numerical color specification -consists of a color space name and a set of values in the following syntax: -.LP -.sM -.Ds 0 -\fI<color_space_name>\fP:\fI<value>/.../<value>\fP -.De -.LP -.eM -The following are examples of valid color strings. -.LP -.Ds 0 -"CIEXYZ:0.3227/0.28133/0.2493" -"RGBi:1.0/0.0/0.0" -"rgb:00/ff/00" -"CIELuv:50.0/0.0/0.0" -.De -The syntax and semantics of numerical specifications are given -for each standard color space in the following sections. -.NH 3 -RGB Device String Specification -.XS -\*(SN RGB Device String Specification -.XE -.LP -An RGB Device specification is identified by -the prefix ``rgb:'' and conforms to the following syntax: -.LP -.\" Start marker code here -.Ds 0 -rgb:\fI<red>/<green>/<blue>\fP - - \fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP - \fIh\fP := single hexadecimal digits (case insignificant) -.De -.\" End marker code here -.LP -Note that \fIh\fP indicates the value scaled in 4 bits, -\fIhh\fP the value scaled in 8 bits, -\fIhhh\fP the value scaled in 12 bits, -and \fIhhhh\fP the value scaled in 16 bits, respectively. -.LP -Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'', -but mixed numbers of hexadecimal digit strings -(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'') -are also allowed. -.LP -For backward compatibility, an older syntax for RGB Device is -supported, but its continued use is not encouraged. -The syntax is an initial sharp sign character followed by -a numeric specification, in one of the following formats: -.LP -.\" Start marker code here -.Ds 0 -.TA 2i -.ta 2i -#RGB (4 bits each) -#RRGGBB (8 bits each) -#RRRGGGBBB (12 bits each) -#RRRRGGGGBBBB (16 bits each) -.De -.\" End marker code here -.LP -The R, G, and B represent single hexadecimal digits. -When fewer than 16 bits each are specified, -they represent the most significant bits of the value -(unlike the ``rgb:'' syntax, in which values are scaled). -For example, the string ``#3a7'' is the same as ``#3000a0007000''. -.NH 3 -RGB Intensity String Specification -.XS -\*(SN RGB Intensity String Specification -.XE -.LP -An RGB intensity specification is identified -by the prefix ``rgbi:'' and conforms to the following syntax: -.LP -.\" Start marker code here -.Ds 0 -rgbi:\fI<red>/<green>/<blue>\fP -.De -.\" End marker code here -.LP -Note that red, green, and blue are floating-point values -between 0.0 and 1.0, inclusive. -The input format for these values is an optional sign, -a string of numbers possibly containing a decimal point, -and an optional exponent field containing an E or e -followed by a possibly signed integer string. -.NH 3 -Device-Independent String Specifications -.XS -\*(SN Device-Independent String Specifications -.XE -.LP -The standard device-independent string specifications have -the following syntax: -.LP -.\" Start marker code here -.Ds 0 -CIEXYZ:\fI<X>/<Y>/<Z>\fP -CIEuvY:\fI<u>/<v>/<Y>\fP -CIExyY:\fI<x>/<y>/<Y>\fP -CIELab:\fI<L>/<a>/<b>\fP -CIELuv:\fI<L>/<u>/<v>\fP -TekHVC:\fI<H>/<V>/<C>\fP -.De -.\" End marker code here -.LP -All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are -floating-point values. -The syntax for these values is an optional plus or minus sign, -a string of digits possibly containing a decimal point, -and an optional exponent field consisting of an ``E'' or ``e'' -followed by an optional plus or minus followed by a string of digits. -.NH 2 -Color Conversion Contexts and Gamut Mapping -.XS -\*(SN Color Conversion Contexts and Gamut Mapping -.XE -.LP -When Xlib converts device-independent color specifications -into device-dependent specifications and vice versa, -it uses knowledge about the color limitations of the screen hardware. -This information, typically called the device profile, -.IN "Device profile" -is available in a Color Conversion Context (CCC). -.IN "Color Conversion Context" -.IN "CCC" -.LP -Because a specified color may be outside the color gamut of the target screen -and the white point associated with the color specification may differ -from the white point inherent to the screen, -Xlib applies gamut mapping when it encounters certain conditions: -.IN "White point" -.IP \(bu 5 -Gamut compression occurs when conversion of device-independent -color specifications to device-dependent color specifications -results in a color out of the target screen's gamut. -.IP \(bu 5 -White adjustment occurs when the inherent white point of the screen -differs from the white point assumed by the client. -.LP -Gamut handling methods are stored as callbacks in the CCC, -which in turn are used by the color space conversion routines. -Client data is also stored in the CCC for each callback. -The CCC also contains the white point the client assumes to be -associated with color specifications (that is, the Client White Point). -.IN "Client White Point" -.IN "Gamut compression" -.IN "Gamut handling" -.IN "White point adjustment" -The client can specify the gamut handling callbacks and client data -as well as the Client White Point. -Xlib does not preclude the X client from performing other -forms of gamut handling (for example, gamut expansion); -however, Xlib does not provide direct support for gamut handling -other than white adjustment and gamut compression. -.LP -Associated with each colormap is an initial CCC transparently generated by -Xlib. -.IN "Color Conversion Context" "creation" -Therefore, -when you specify a colormap as an argument to an Xlib function, -you are indirectly specifying a CCC. -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -There is a default CCC associated with each screen. -Newly created CCCs inherit attributes from the default CCC, -so the default CCC attributes can be modified to affect new CCCs. -.IN "CCC" "default" -.IN "Color Conversion Context" "default" -.LP -Xcms functions in which gamut mapping can occur return -.PN Status -and have specific status values defined for them, -as follows: -.IP \(bu 5 -.PN XcmsFailure -indicates that the function failed. -.IP \(bu 5 -.PN XcmsSuccess -indicates that the function succeeded. -In addition, -if the function performed any color conversion, -the colors did not need to be compressed. -.IP \(bu 5 -.PN XcmsSuccessWithCompression -indicates the function performed color conversion -and at least one of the colors needed to be compressed. -The gamut compression method is determined by the gamut compression -procedure in the CCC that is specified directly as a function argument -or in the CCC indirectly specified by means of the colormap argument. -.NH 2 -Creating, Copying, and Destroying Colormaps -.XS -\*(SN Creating, Copying, and Destroying Colormaps -.XE -.LP -To create a colormap for a screen, use -.PN XCreateColormap . -.IN "XCreateColormap" "" "@DEF@" -.sM -.FD 0 -Colormap XCreateColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvisual\fP\^, \fIalloc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Visual *\fIvisual\fP\^; -.br - int \fIalloc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi on whose screen you want to create a colormap -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIvisual\fP 1i -Specifies a visual type supported on the screen. -If the visual type is not one supported by the screen, -a -.PN BadMatch -error results. -.IP \fIalloc\fP 1i -Specifies the colormap entries to be allocated. -You can pass -.PN AllocNone -or -.PN AllocAll . -.LP -.eM -The -.PN XCreateColormap -function creates a colormap of the specified visual type for the screen -on which the specified window resides and returns the colormap ID -associated with it. -Note that the specified window is only used to determine the screen. -.LP -The initial values of the colormap entries are undefined for the -visual classes -.PN GrayScale , -.PN PseudoColor , -and -.PN DirectColor . -For -.PN StaticGray , -.PN StaticColor , -and -.PN TrueColor , -the entries have defined values, -but those values are specific to the visual and are not defined by X. -For -.PN StaticGray , -.PN StaticColor , -and -.PN TrueColor , -alloc must be -.PN AllocNone , -or a -.PN BadMatch -error results. -For the other visual classes, -if alloc is -.PN AllocNone , -the colormap initially has no allocated entries, -and clients can allocate them. -For information about the visual types, -see section 3.1. -.LP -If alloc is -.PN AllocAll , -the entire colormap is allocated writable. -The initial values of all allocated entries are undefined. -For -.PN GrayScale -and -.PN PseudoColor , -the effect is as if an -.PN XAllocColorCells -call returned all pixel values from zero to N \- 1, -where N is the colormap entries value in the specified visual. -For -.PN DirectColor , -the effect is as if an -.PN XAllocColorPlanes -call returned a pixel value of zero and red_mask, green_mask, -and blue_mask values containing the same bits as the corresponding -masks in the specified visual. -However, in all cases, -none of these entries can be freed by using -.PN XFreeColors . -.LP -.PN XCreateColormap -can generate -.PN BadAlloc , -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To create a new colormap when the allocation out of a previously -shared colormap has failed because of resource exhaustion, use -.PN XCopyColormapAndFree . -.IN "XCopyColormapAndFree" "" "@DEF@" -.sM -.FD 0 -Colormap XCopyColormapAndFree\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XCopyColormapAndFree -function creates a colormap of the same visual type and for the same screen -as the specified colormap and returns the new colormap ID. -It also moves all of the client's existing allocation from the specified -colormap to the new colormap with their color values intact -and their read-only or writable characteristics intact and frees those entries -in the specified colormap. -Color values in other entries in the new colormap are undefined. -If the specified colormap was created by the client with alloc set to -.PN AllocAll , -the new colormap is also created with -.PN AllocAll , -all color values for all entries are copied from the specified colormap, -and then all entries in the specified colormap are freed. -If the specified colormap was not created by the client with -.PN AllocAll , -the allocations to be moved are all those pixels and planes -that have been allocated by the client using -.PN XAllocColor , -.PN XAllocNamedColor , -.PN XAllocColorCells , -or -.PN XAllocColorPlanes -and that have not been freed since they were allocated. -.LP -.PN XCopyColormapAndFree -can generate -.PN BadAlloc -and -.PN BadColor -errors. -.LP -.sp -To destroy a colormap, use -.PN XFreeColormap . -.IN "XFreeColormap" "" "@DEF@" -.sM -.FD 0 -XFreeColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Cm that you want to destroy -.IP \fIcolormap\fP 1i -Specifies the colormap \*(Cm. -.LP -.eM -The -.PN XFreeColormap -function deletes the association between the colormap resource ID -and the colormap and frees the colormap storage. -However, this function has no effect on the default colormap for a screen. -If the specified colormap is an installed map for a screen, -it is uninstalled (see -.PN XUninstallColormap ). -If the specified colormap is defined as the colormap for a window (by -.PN XCreateWindow , -.PN XSetWindowColormap , -or -.PN XChangeWindowAttributes ), -.PN XFreeColormap -changes the colormap associated with the window to -.PN None -and generates a -.PN ColormapNotify -event. -X does not define the colors displayed for a window with a colormap of -.PN None . -.LP -.PN XFreeColormap -can generate a -.PN BadColor -error. -.NH 2 -Mapping Color Names to Values -.XS -\*(SN Mapping Color Names to Values -.XE -.LP -.sp -To map a color name to an RGB value, use -.PN XLookupColor . -.IN "Color" "naming" -.IN "XLookupColor" "" "@DEF@" -.sM -.FD 0 -Status XLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP, \fIcolor_name\fP, \ -\fIexact_def_return\fP\^, \fIscreen_def_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_name\fP\^; -.br - XColor *\fIexact_def_return\fP\^, *\fIscreen_def_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_name\fP 1i -Specifies the color name string (for example, red) whose color -definition structure you want returned. -.IP \fIexact_def_return\fP 1i -Returns the exact RGB values. -.IP \fIscreen_def_return\fP 1i -Returns the closest RGB values provided by the hardware. -.LP -.eM -The -.PN XLookupColor -function looks up the string name of a color with respect to the screen -associated with the specified colormap. -It returns both the exact color values and -the closest values provided by the screen -with respect to the visual type of the specified colormap. -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -.PN XLookupColor -returns nonzero if the name is resolved; -otherwise, it returns zero. -.LP -.PN XLookupColor -can generate a -.PN BadColor -error. -.LP -.sp -To map a color name to the exact RGB value, use -.PN XParseColor . -.IN "Color" "naming" -.IN "XParseColor" "" "@DEF@" -.sM -.FD 0 -Status XParseColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \^\fIspec\fP\^, \fIexact_def_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIspec\fP\^; -.br - XColor *\fIexact_def_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIspec\fP 1i -Specifies the color name string; -case is ignored. -.IP \fIexact_def_return\fP 1i -Returns the exact color value for later use and sets the -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue -flags. -.LP -.eM -The -.PN XParseColor -function looks up the string name of a color with respect to the screen -associated with the specified colormap. -It returns the exact color value. -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -.PN XParseColor -returns nonzero if the name is resolved; -otherwise, it returns zero. -.LP -.PN XParseColor -can generate a -.PN BadColor -error. -.LP -.sp -To map a color name to a value in an arbitrary color space, use -.PN XcmsLookupColor . -.IN "Color" "naming" -.IN "XcmsLookupColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_exact_return\fP\^, \fIcolor_screen_return\fP\^, -.br - \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_string\fP\^; -.br - XcmsColor *\fIcolor_exact_return\fP\^, *\fIcolor_screen_return\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.ds St -.IP \fIcolor_string\fP 1i -Specifies the color string\*(St. -.IP \fIcolor_exact_return\fP 1i -Returns the color specification parsed from the color string -or parsed from the corresponding string found in a color-name database. -.IP \fIcolor_screen_return\fP 1i -Returns the color that can be reproduced on the screen. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color -specifications (color_screen_return and color_exact_return arguments). -If the format is -.PN XcmsUndefinedFormat -and the color string contains a -numerical color specification, -the specification is returned in the format used in that numerical -color specification. -If the format is -.PN XcmsUndefinedFormat -and the color string contains a color name, -the specification is returned in the format used -to store the color in the database. -.LP -.eM -The -.PN XcmsLookupColor -function looks up the string name of a color with respect to the screen -associated with the specified colormap. -It returns both the exact color values and -the closest values provided by the screen -with respect to the visual type of the specified colormap. -The values are returned in the format specified by result_format. -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -.PN XcmsLookupColor -returns -.PN XcmsSuccess -or -.PN XcmsSuccessWithCompression -if the name is resolved; otherwise, it returns -.PN XcmsFailure . -If -.PN XcmsSuccessWithCompression -is returned, the color specification returned in -color_screen_return is the result of gamut compression. -.NH 2 -Allocating and Freeing Color Cells -.XS -\*(SN Allocating and Freeing Color Cells -.XE -.LP -There are two ways of allocating color cells: -explicitly as read-only entries, one pixel value at a time, -or read/write, -where you can allocate a number of color cells and planes simultaneously. -.IN "Read-only colormap cells" -A read-only cell has its RGB value set by the server. -.IN "Read/write colormap cells" -Read/write cells do not have defined colors initially; -functions described in the next section must be used to store values into them. -Although it is possible for any client to store values into a read/write -cell allocated by another client, -read/write cells normally should be considered private to the client -that allocated them. -.LP -Read-only colormap cells are shared among clients. -The server counts each allocation and freeing of the cell by clients. -When the last client frees a shared cell, the cell is finally deallocated. -If a single client allocates the same read-only cell multiple -times, the server counts each such allocation, not just the first one. -.LP -.sp -To allocate a read-only color cell with an RGB value, use -.PN XAllocColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "allocation" -.IN "XAllocColor" "" "@DEF@" -.sM -.FD 0 -Status XAllocColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIscreen_in_out\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor *\fIscreen_in_out\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIscreen_in_out\fP 1i -Specifies and returns the values actually used in the colormap. -.LP -.eM -The -.PN XAllocColor -function allocates a read-only colormap entry corresponding to the closest -RGB value supported by the hardware. -.PN XAllocColor -returns the pixel value of the color closest to the specified -RGB elements supported by the hardware -and returns the RGB value actually used. -The corresponding colormap cell is read-only. -In addition, -.PN XAllocColor -returns nonzero if it succeeded or zero if it failed. -.IN "Color map" -.IN "Color" "allocation" -.IN "Allocation" "colormap" -.IN "read-only colormap cells" -Multiple clients that request the same effective RGB value can be assigned -the same read-only entry, thus allowing entries to be shared. -When the last client deallocates a shared cell, it is deallocated. -.PN XAllocColor -does not use or affect the flags in the -.PN XColor -structure. -.LP -.PN XAllocColor -can generate a -.PN BadColor -error. -.EQ -delim %% -.EN -.LP -.sp -To allocate a read-only color cell with a color in arbitrary format, use -.PN XcmsAllocColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "allocation" -.IN "XcmsAllocColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsAllocColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor *\fIcolor_in_out\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_in_out\fP 1i -Specifies the color to allocate and returns the pixel and color -that is actually used in the colormap. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color specification. -.LP -.eM -The -.PN XcmsAllocColor -function is similar to -.PN XAllocColor -except the color can be specified in any format. -The -.PN XcmsAllocColor -function ultimately calls -.PN XAllocColor -to allocate a read-only color cell (colormap entry) with the specified color. -.PN XcmsAllocColor -first converts the color specified -to an RGB value and then passes this to -.PN XAllocColor . -.PN XcmsAllocColor -returns the pixel value of the color cell and the color specification -actually allocated. -This returned color specification is the result of converting the RGB value -returned by -.PN XAllocColor -into the format specified with the result_format argument. -If there is no interest in a returned color specification, -unnecessary computation can be bypassed if result_format is set to -.PN XcmsRGBFormat . -The corresponding colormap cell is read-only. -If this routine returns -.PN XcmsFailure , -the color_in_out color specification is left unchanged. -.LP -.PN XcmsAllocColor -can generate a -.PN BadColor -error. -.LP -.sp -To allocate a read-only color cell using a color name and return the closest -color supported by the hardware in RGB format, use -.PN XAllocNamedColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "naming" -.IN "Color" "allocation" -.IN "XAllocNamedColor" "" "@DEF@" -.sM -.FD 0 -Status XAllocNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \ -\fIcolor_name\fP\^, \fIscreen_def_return\fP\^, \fIexact_def_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_name\fP\^; -.br - XColor *\fIscreen_def_return\fP\^, *\fIexact_def_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_name\fP 1i -Specifies the color name string (for example, red) whose color -definition structure you want returned. -.IP \fIscreen_def_return\fP 1i -Returns the closest RGB values provided by the hardware. -.IP \fIexact_def_return\fP 1i -Returns the exact RGB values. -.LP -.eM -The -.PN XAllocNamedColor -function looks up the named color with respect to the screen that is -associated with the specified colormap. -It returns both the exact database definition and -the closest color supported by the screen. -The allocated color cell is read-only. -The pixel value is returned in screen_def_return. -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -If screen_def_return and exact_def_return -point to the same structure, the pixel field will be set correctly, -but the color values are undefined. -.PN XAllocNamedColor -returns nonzero if a cell is allocated; -otherwise, it returns zero. -.LP -.PN XAllocNamedColor -can generate a -.PN BadColor -error. -.LP -.sp -To allocate a read-only color cell using a color name and return the closest -color supported by the hardware in an arbitrary format, use -.PN XcmsAllocNamedColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "naming" -.IN "Color" "allocation" -.IN "XcmsAllocNamedColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsAllocNamedColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_screen_return\fP\^, \fIcolor_exact_return\fP\^, -.br - \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_string\fP\^; -.br - XcmsColor *\fIcolor_screen_return\fP\^; -.br - XcmsColor *\fIcolor_exact_return\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.ds St \ whose color definition structure is to be returned -.IP \fIcolor_string\fP 1i -Specifies the color string\*(St. -.IP \fIcolor_screen_return\fP 1i -Returns the pixel value of the color cell and color specification -that actually is stored for that cell. -.IP \fIcolor_exact_return\fP 1i -Returns the color specification parsed from the color string -or parsed from the corresponding string found in a color-name database. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color -specifications (color_screen_return and color_exact_return arguments). -If the format is -.PN XcmsUndefinedFormat -and the color string contains a -numerical color specification, -the specification is returned in the format used in that numerical -color specification. -If the format is -.PN XcmsUndefinedFormat -and the color string contains a color name, -the specification is returned in the format used -to store the color in the database. -.LP -.eM -The -.PN XcmsAllocNamedColor -function is similar to -.PN XAllocNamedColor -except that the color returned can be in any format specified. -This function -ultimately calls -.PN XAllocColor -to allocate a read-only color cell with -the color specified by a color string. -The color string is parsed into an -.PN XcmsColor -structure (see -.PN XcmsLookupColor ), -converted -to an RGB value, and finally passed to -.PN XAllocColor . -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -.LP -This function returns both the color specification as a result -of parsing (exact specification) and the actual color specification -stored (screen specification). -This screen specification is the result of converting the RGB value -returned by -.PN XAllocColor -into the format specified in result_format. -If there is no interest in a returned color specification, -unnecessary computation can be bypassed if result_format is set to -.PN XcmsRGBFormat . -If color_screen_return and color_exact_return -point to the same structure, the pixel field will be set correctly, -but the color values are undefined. -.LP -.PN XcmsAllocNamedColor -can generate a -.PN BadColor -error. -.LP -.sp -To allocate read/write color cell and color plane combinations for a -.PN PseudoColor -model, use -.PN XAllocColorCells . -.IN "Read/write colormap cells" "allocating" -.IN "Allocation" "read/write colormap cells" -.IN "Color" "allocation" -.IN "XAllocColorCells" "" "@DEF@" -.sM -.FD 0 -Status XAllocColorCells\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \ -\fIplane_masks_return\fP\^, \fInplanes\fP\^, -.br - \fIpixels_return\fP\^, \fInpixels\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - Bool \fIcontig\fP\^; -.br - unsigned long \fIplane_masks_return\fP[\^]\^; -.br - unsigned int \fInplanes\fP\^; -.br - unsigned long \fIpixels_return\fP[\^]\^; -.br - unsigned int \fInpixels\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcontig\fP 1i -Specifies a Boolean value that indicates whether the planes must be contiguous. -.IP \fIplane_mask_return\fP 1i -Returns an array of plane masks. -.\" *** JIM: NEED MORE INFO FOR THIS. *** -.IP \fInplanes\fP 1i -Specifies the number of plane masks that are to be returned in the plane masks -array. -.IP \fIpixels_return\fP 1i -Returns an array of pixel values. -.IP \fInpixels\fP 1i -Specifies the number of pixel values that are to be returned in the -pixels_return array. -.LP -.eM -.EQ -delim %% -.EN -The -.PN XAllocColorCells -function allocates read/write color cells. -The number of colors must be positive and the number of planes nonnegative, -or a -.PN BadValue -error results. -If ncolors and nplanes are requested, -then ncolors pixels -and nplane plane masks are returned. -No mask will have any bits set to 1 in common with -any other mask or with any of the pixels. -By ORing together each pixel with zero or more masks, -ncolors * %2 sup nplanes% distinct pixels can be produced. -All of these are -allocated writable by the request. -For -.PN GrayScale -or -.PN PseudoColor , -each mask has exactly one bit set to 1. -For -.PN DirectColor , -each has exactly three bits set to 1. -If contig is -.PN True -and if all masks are ORed -together, a single contiguous set of bits set to 1 will be formed for -.PN GrayScale -or -.PN PseudoColor -and three contiguous sets of bits set to 1 (one within each -pixel subfield) for -.PN DirectColor . -The RGB values of the allocated -entries are undefined. -.PN XAllocColorCells -returns nonzero if it succeeded or zero if it failed. -.LP -.PN XAllocColorCells -can generate -.PN BadColor -and -.PN BadValue -errors. -.LP -.sp -To allocate read/write color resources for a -.PN DirectColor -model, use -.PN XAllocColorPlanes . -.IN "Read/write colormap planes" "allocating" -.IN "Allocation" "read/write colormap planes" -.IN "Color" "allocation" -.IN "XAllocColorPlanes" "" "@DEF@" -.sM -.FD 0 -Status XAllocColorPlanes\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \fIpixels_return\fP\^, \fIncolors\fP\^, \fInreds\fP\^, \fIngreens\fP\^, -.br - \fInblues\fP\^, \fIrmask_return\fP\^, \fIgmask_return\fP\^, \fIbmask_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - Bool \fIcontig\fP\^; -.br - unsigned long \fIpixels_return\fP[\^]\^; -.br - int \fIncolors\fP\^; -.br - int \fInreds\fP\^, \fIngreens\fP\^, \fInblues\fP\^; -.br - unsigned long *\fIrmask_return\fP\^, *\fIgmask_return\fP\^, *\fIbmask_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcontig\fP 1i -Specifies a Boolean value that indicates whether the planes must be contiguous. -.IP \fIpixels_return\fP 1i -Returns an array of pixel values. -.PN XAllocColorPlanes -returns the pixel values in this array. -.IP \fIncolors\fP 1i -Specifies the number of pixel values that are to be returned in the -pixels_return array. -.IP \fInreds\fP 1i -.br -.ns -.IP \fIngreens\fP 1i -.br -.ns -.IP \fInblues\fP 1i -.br -.ns -Specify the number of red, green, and blue planes. -The value you pass must be nonnegative. -.IP \fIrmask_return\fP 1i -.br -.ns -.IP \fIgmask_return\fP 1i -.br -.ns -.IP \fIbmask_return\fP 1i -Return bit masks for the red, green, and blue planes. -.LP -.eM -.EQ -delim %% -.EN -The specified ncolors must be positive; -and nreds, ngreens, and nblues must be nonnegative, -or a -.PN BadValue -error results. -If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, -ncolors pixels are returned; and the masks have nreds, ngreens, and -nblues bits set to 1, respectively. -If contig is -.PN True , -each mask will have -a contiguous set of bits set to 1. -No mask will have any bits set to 1 in common with -any other mask or with any of the pixels. -For -.PN DirectColor , -each mask -will lie within the corresponding pixel subfield. -By ORing together -subsets of masks with each pixel value, -ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced. -All of these are allocated by the request. -However, in the -colormap, there are only ncolors * %2 sup nreds% independent red entries, -ncolors * %2 sup ngreens% independent green entries, -and ncolors * %2 sup nblues% independent blue entries. -This is true even for -.PN PseudoColor . -When the colormap entry of a pixel -value is changed (using -.PN XStoreColors , -.PN XStoreColor , -or -.PN XStoreNamedColor ), -the pixel is decomposed according to the masks, -and the corresponding independent entries are updated. -.PN XAllocColorPlanes -returns nonzero if it succeeded or zero if it failed. -.LP -.PN XAllocColorPlanes -can generate -.PN BadColor -and -.PN BadValue -errors. -.LP -.sp -.IN "Freeing" "colors" -To free colormap cells, use -.PN XFreeColors . -.IN "XFreeColors" "" "@DEF@" -.IN "Color" "deallocation" -.sM -.FD 0 -XFreeColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIpixels\fP\^, \fInpixels\fP\^, \fIplanes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - unsigned long \fIpixels\fP\^[\^]; -.br - int \fInpixels\fP\^; -.br - unsigned long \fIplanes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.ds Pi that map to the cells in the specified colormap -.IP \fIpixels\fP 1i -Specifies an array of pixel values \*(Pi. -.IP \fInpixels\fP 1i -Specifies the number of pixels. -.IP \fIplanes\fP 1i -Specifies the planes you want to free. -.LP -.eM -The -.PN XFreeColors -function frees the cells represented by pixels whose values are in the -pixels array. -The planes argument should not have any bits set to 1 in common with any of the -pixels. -The set of all pixels is produced by ORing together subsets of -the planes argument with the pixels. -The request frees all of these pixels that -were allocated by the client (using -.IN XAllocColor -.IN XAllocNamedColor -.IN XAllocColorCells -.IN XAllocColorPlanes -.PN XAllocColor , -.PN XAllocNamedColor , -.PN XAllocColorCells , -and -.PN XAllocColorPlanes ). -Note that freeing an -individual pixel obtained from -.PN XAllocColorPlanes -may not actually allow -it to be reused until all of its related pixels are also freed. -Similarly, -a read-only entry is not actually freed until it has been freed by all clients, -and if a client allocates the same read-only entry multiple times, -it must free the entry that many times before the entry is actually freed. -.LP -All specified pixels that are allocated by the client in the colormap are -freed, even if one or more pixels produce an error. -If a specified pixel is not a valid index into the colormap, a -.PN BadValue -error results. -If a specified pixel is not allocated by the -client (that is, is unallocated or is only allocated by another client) -or if the colormap was created with all entries writable (by passing -.PN AllocAll -to -.PN XCreateColormap ), -a -.PN BadAccess -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.PN XFreeColors -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.NH 2 -Modifying and Querying Colormap Cells -.XS -\*(SN Modifying and Querying Colormap Cells -.XE -.LP -.sp -To store an RGB value in a single colormap cell, use -.PN XStoreColor . -.IN "Color" "storing" -.IN "XStoreColor" "" "@DEF@" -.sM -.FD 0 -XStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor *\fIcolor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies the pixel and RGB values. -.LP -.eM -The -.PN XStoreColor -function changes the colormap entry of the pixel value specified in the -pixel member of the -.PN XColor -structure. -You specified this value in the -pixel member of the -.PN XColor -structure. -This pixel value must be a read/write cell and a valid index into the colormap. -If a specified pixel is not a valid index into the colormap, -a -.PN BadValue -error results. -.PN XStoreColor -also changes the red, green, and/or blue color components. -You specify which color components are to be changed by setting -.PN DoRed , -.PN DoGreen , -and/or -.PN DoBlue -in the flags member of the -.PN XColor -structure. -If the colormap is an installed map for its screen, -the changes are visible immediately. -.LP -.PN XStoreColor -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store multiple RGB values in multiple colormap cells, use -.PN XStoreColors . -.IN "Color" "storing" -.IN "XStoreColors" "" "@DEF@" -.sM -.FD 0 -XStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIncolors\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor \fIcolor\fP\^[\^]\^; -.br - int \fIncolors\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies an array of color definition structures to be stored. -.IP \fIncolors\fP 1i -.\"Specifies the number of color definition structures. -Specifies the number of -.PN XColor -structures in the color definition array. -.LP -.eM -The -.PN XStoreColors -function changes the colormap entries of the pixel values -specified in the pixel members of the -.PN XColor -structures. -You specify which color components are to be changed by setting -.PN DoRed , -.PN DoGreen , -and/or -.PN DoBlue -in the flags member of the -.PN XColor -structures. -If the colormap is an installed map for its screen, the -changes are visible immediately. -.PN XStoreColors -changes the specified pixels if they are allocated writable in the colormap -by any client, even if one or more pixels generates an error. -If a specified pixel is not a valid index into the colormap, a -.PN BadValue -error results. -If a specified pixel either is unallocated or is allocated read-only, a -.PN BadAccess -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.PN XStoreColors -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store a color of arbitrary format in a single colormap cell, use -.PN XcmsStoreColor . -.IN "Color" "storing" -.IN "XcmsStoreColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor *\fIcolor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies the color cell and the color to store. -Values specified in this -.PN XcmsColor -structure remain unchanged on return. -.LP -.eM -The -.PN XcmsStoreColor -function converts the color specified in the -.PN XcmsColor -structure into RGB values. -It then uses this RGB specification in an -.PN XColor -structure, whose three flags -.Pn ( DoRed , -.PN DoGreen , -and -.PN DoBlue ) -are set, in a call to -.PN XStoreColor -to change the color cell specified by the pixel member of the -.PN XcmsColor -structure. -This pixel value must be a valid index for the specified colormap, -and the color cell specified by the pixel value must be a read/write cell. -If the pixel value is not a valid index, a -.PN BadValue -error results. -If the color cell is unallocated or is allocated read-only, a -.PN BadAccess -error results. -If the colormap is an installed map for its screen, -the changes are visible immediately. -.LP -Note that -.PN XStoreColor -has no return value; therefore, an -.PN XcmsSuccess -return value from this function indicates that the conversion -to RGB succeeded and the call to -.PN XStoreColor -was made. -To obtain the actual color stored, use -.PN XcmsQueryColor . -Because of the screen's hardware limitations or gamut compression, -the color stored in the colormap may not be identical -to the color specified. -.LP -.PN XcmsStoreColor -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store multiple colors of arbitrary format in multiple colormap cells, use -.PN XcmsStoreColors . -.IN "Color" "storing" -.IN "XcmsStoreColors" "" "@DEF@" -.sM -.FD 0 -Status XcmsStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor \fIcolors\fP\^[\^]\^; -.br - int \fIncolors\fP\^; -.br - Bool \fIcompression_flags_return\fP\^[\^]\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolors\fP 1i -Specifies the color specification array of -.PN XcmsColor -structures, each specifying a color cell and the color to store in that -cell. -Values specified in the array remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values indicating compression status. -If a non-NULL pointer is supplied, -each element of the array is set to -.PN True -if the corresponding color was compressed and -.PN False -otherwise. -Pass NULL if the compression status is not useful. -.LP -.eM -The -.PN XcmsStoreColors -function converts the colors specified in the array of -.PN XcmsColor -structures into RGB values and then uses these RGB specifications in -.PN XColor -structures, whose three flags -.Pn ( DoRed , -.PN DoGreen , -and -.PN DoBlue ) -are set, in a call to -.PN XStoreColors -to change the color cells specified by the pixel member of the corresponding -.PN XcmsColor -structure. -Each pixel value must be a valid index for the specified colormap, -and the color cell specified by each pixel value must be a read/write cell. -If a pixel value is not a valid index, a -.PN BadValue -error results. -If a color cell is unallocated or is allocated read-only, a -.PN BadAccess -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -If the colormap is an installed map for its screen, -the changes are visible immediately. -.LP -Note that -.PN XStoreColors -has no return value; therefore, an -.PN XcmsSuccess -return value from this function indicates that conversions -to RGB succeeded and the call to -.PN XStoreColors -was made. -To obtain the actual colors stored, use -.PN XcmsQueryColors . -Because of the screen's hardware limitations or gamut compression, -the colors stored in the colormap may not be identical -to the colors specified. -.LP -.PN XcmsStoreColors -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store a color specified by name in a single colormap cell, use -.PN XStoreNamedColor . -.IN "Color" "storing" -.IN "Color" "naming" -.IN "XStoreNamedColor" "" "@DEF@" -.sM -.FD 0 -XStoreNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIpixel\fP\^, \fIflags\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\^\fIcolor\fP\^; -.br - unsigned long \fIpixel\fP\^; -.br - int \fIflags\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies the color name string (for example, red). -.IP \fIpixel\fP 1i -Specifies the entry in the colormap. -.IP \fIflags\fP 1i -Specifies which red, green, and blue components are set. -.LP -.eM -The -.PN XStoreNamedColor -function looks up the named color with respect to the screen associated with -the colormap and stores the result in the specified colormap. -The pixel argument determines the entry in the colormap. -The flags argument determines which of the red, green, and blue components -are set. -You can set this member to the -bitwise inclusive OR of the bits -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue . -If the color name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -If the specified pixel is not a valid index into the colormap, a -.PN BadValue -error results. -If the specified pixel either is unallocated or is allocated read-only, a -.PN BadAccess -error results. -.LP -.PN XStoreNamedColor -can generate -.PN BadAccess , -.PN BadColor , -.PN BadName , -and -.PN BadValue -errors. -.LP -The -.PN XQueryColor -and -.PN XQueryColors -functions take pixel values in the pixel member of -.PN XColor -structures and store in the structures the RGB values for those -pixels from the specified colormap. -The values returned for an unallocated entry are undefined. -These functions also set the flags member in the -.PN XColor -structure to all three colors. -If a pixel is not a valid index into the specified colormap, a -.PN BadValue -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.sp -To query the RGB value of a single colormap cell, use -.PN XQueryColor . -.IN "Color" "querying" -.IN "XQueryColor" "" "@DEF@" -.sM -.FD 0 -XQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdef_in_out\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor *\fIdef_in_out\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIdef_in_out\fP 1i -Specifies and returns the RGB values for the pixel specified in the structure. -.LP -.eM -The -.PN XQueryColor -function returns the current RGB value for the pixel in the -.PN XColor -structure and sets the -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue -flags. -.LP -.PN XQueryColor -can generate -.PN BadColor -and -.PN BadValue -errors. -.LP -.sp -To query the RGB values of multiple colormap cells, use -.PN XQueryColors . -.IN "Color" "querying" -.IN "XQueryColors" "" "@DEF@" -.sM -.FD 0 -XQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdefs_in_out\fP\^, \fIncolors\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor \fIdefs_in_out\fP[\^]\^; -.br - int \fIncolors\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIdefs_in_out\fP 1i -Specifies and returns an array of color definition structures for the pixel -specified in the structure. -.IP \fIncolors\fP 1i -.\"Specifies the number of color definition structures. -Specifies the number of -.PN XColor -structures in the color definition array. -.LP -.eM -The -.PN XQueryColors -function returns the RGB value for each pixel in each -.PN XColor -structure and sets the -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue -flags in each structure. - -.LP -.PN XQueryColors -can generate -.PN BadColor -and -.PN BadValue -errors. -.sp -.LP -To query the color of a single colormap cell in an arbitrary format, use -.PN XcmsQueryColor . -.IN "Color" "querying" -.IN "XcmsQueryColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor *\fIcolor_in_out\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_in_out\fP 1i -Specifies the pixel member that indicates the color cell to query. -The color specification stored for the color cell is returned in this -.PN XcmsColor -structure. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color specification. -.LP -.eM -The -.PN XcmsQueryColor -function obtains the RGB value -for the pixel value in the pixel member of the specified -.PN XcmsColor -structure and then -converts the value to the target format as -specified by the result_format argument. -If the pixel is not a valid index in the specified colormap, a -.PN BadValue -error results. -.LP -.PN XcmsQueryColor -can generate -.PN BadColor -and -.PN BadValue -errors. -.sp -.LP -To query the color of multiple colormap cells in an arbitrary format, use -.PN XcmsQueryColors . -.IN "Color" "querying" -.IN "XcmsQueryColors" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor \fIcolors_in_out\fP\^[\^]\^; -.br - unsigned int \fIncolors\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolors_in_out\fP 1i -Specifies an array of -.PN XcmsColor -structures, each pixel member indicating the color cell to query. -The color specifications for the color cells are returned in these structures. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color specification. -.LP -.eM -The -.PN XcmsQueryColors -function obtains the RGB values -for pixel values in the pixel members of -.PN XcmsColor -structures and then -converts the values to the target format as -specified by the result_format argument. -If a pixel is not a valid index into the specified colormap, a -.PN BadValue -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.PN XcmsQueryColors -can generate -.PN BadColor -and -.PN BadValue -errors. -.NH 2 -Color Conversion Context Functions -.XS -\*(SN Color Conversion Context Functions -.XE -.LP -This section describes functions to create, modify, -and query Color Conversion Contexts (CCCs). -.LP -Associated with each colormap is an initial CCC transparently generated by -Xlib. -.IN "Color Conversion Context" "creation" -Therefore, when you specify a colormap as an argument to a function, -you are indirectly specifying a CCC. -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -The CCC attributes that can be modified by the X client are: -.IP \(bu 5 -Client White Point -.IP \(bu 5 -Gamut compression procedure and client data -.IP \(bu 5 -White point adjustment procedure and client data -.LP -The initial values for these attributes are implementation specific. -The CCC attributes for subsequently created CCCs can be defined -by changing the CCC attributes of the default CCC. -.IN "CCC" "default" -.IN "Color Conversion Context" "default" -There is a default CCC associated with each screen. -.NH 3 -Getting and Setting the Color Conversion Context of a Colormap -.XS -\*(SN Getting and Setting the Color Conversion Context of a Colormap -.XE -.LP -.sp -To obtain the CCC associated with a colormap, use -.PN XcmsCCCOfColormap . -.IN "XcmsCCCOfColormap" "" "@DEF@" -.IN "Colormap" "CCC of" -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -.sM -.FD 0 -XcmsCCC XcmsCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XcmsCCCOfColormap -function returns the CCC associated with the specified colormap. -Once obtained, -the CCC attributes can be queried or modified. -Unless the CCC associated with the specified colormap is changed with -.PN XcmsSetCCCOfColormap , -this CCC is used when the specified colormap is used as an argument -to color functions. -.sp -.LP -To change the CCC associated with a colormap, use -.PN XcmsSetCCCOfColormap . -.IN "XcmsSetCCCOfColormap" "" "@DEF@" -.IN "Colormap" "CCC of" -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -.sM -.FD 0 -XcmsCCC XcmsSetCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIccc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -The -.PN XcmsSetCCCOfColormap -function changes the CCC associated with the specified colormap. -It returns the CCC previously associated with the colormap. -If they are not used again in the application, -CCCs should be freed by calling -.PN XcmsFreeCCC . -Several colormaps may share the same CCC without restriction; this -includes the CCCs generated by Xlib with each colormap. Xlib, however, -creates a new CCC with each new colormap. -.NH 3 -Obtaining the Default Color Conversion Context -.XS -\*(SN Obtaining the Default Color Conversion Context -.XE -.LP -You can change the default CCC attributes for subsequently created CCCs -by changing the CCC attributes of the default CCC. -.IN "CCC" "default" -.IN "Color Conversion Context" "default" -A default CCC is associated with each screen. -.sp -.LP -To obtain the default CCC for a screen, use -.PN XcmsDefaultCCC . -.IN "XcmsDefaultCCC" "" "@DEF@" -.IN "Color Conversion Context" "default" -.IN "CCC" "default" -.sM -.FD 0 -XcmsCCC XcmsDefaultCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -The -.PN XcmsDefaultCCC -function returns the default CCC for the specified screen. -Its visual is the default visual of the screen. -Its initial gamut compression and white point -adjustment procedures as well as the associated client data are implementation -specific. -.NH 3 -Color Conversion Context Macros -.XS -\*(SN Color Conversion Context Macros -.XE -.LP -Applications should not directly modify any part of the -.PN XcmsCCC . -The following lists the C language macros, their corresponding function -equivalents for other language bindings, and what data they both -can return. -.sp -.LP -.IN "DisplayOfCCC" "" "@DEF@" -.IN "XcmsDisplayOfCCC" "" "@DEF@" -.sM -.FD 0 -DisplayOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -Display *XcmsDisplayOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the display associated with the specified CCC. -.LP -.sp -.IN "VisualOfCCC" "" "@DEF@" -.IN "XcmsVisualOfCCC" "" "@DEF@" -.sM -.FD 0 -VisualOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -Visual *XcmsVisualOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the visual associated with the specified CCC. -.sp -.LP -.IN "ScreenNumberOfCCC" "" "@DEF@" -.IN "XcmsScreenNumberOfCCC" "" "@DEF@" -.sM -.FD 0 -ScreenNumberOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -int XcmsScreenNumberOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the number of the screen associated with the specified CCC. -.sp -.LP -.IN "ScreenWhitePointOfCCC" "" "@DEF@" -.IN "XcmsScreenWhitePointOfCCC" "" "@DEF@" -.sM -.FD 0 -ScreenWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -XcmsColor *XcmsScreenWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the white point of the screen associated with the specified CCC. -.sp -.LP -.IN "ClientWhitePointOfCCC" "" "@DEF@" -.IN "XcmsClientWhitePointOfCCC" "" "@DEF@" -.sM -.FD 0 -ClientWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -XcmsColor *XcmsClientWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the Client White Point of the specified CCC. -.NH 3 -Modifying Attributes of a Color Conversion Context -.XS -\*(SN Modifying Attributes of a Color Conversion Context -.XE -.LP -To set the Client White Point in the CCC, use -.PN XcmsSetWhitePoint . -.IN "XcmsSetWhitePoint" "" "@DEF@" -.IN "Client White Point" "of Color Conversion Context" -.sM -.FD 0 -Status XcmsSetWhitePoint\^(\^\fIccc\fP\^, \fIcolor\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIcolor\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.ds Co new Client White Point -.IP \fIcolor\fP 1i -Specifies the \*(Co. -.LP -.eM -The -.PN XcmsSetWhitePoint -function changes the Client White Point in the specified CCC. -Note that the pixel member is ignored -and that the color specification is left unchanged upon return. -The format for the new white point must be -.PN XcmsCIEXYZFormat , -.PN XcmsCIEuvYFormat , -.PN XcmsCIExyYFormat , -or -.PN XcmsUndefinedFormat . -If the color argument is NULL, this function sets the format component of the -Client White Point specification to -.PN XcmsUndefinedFormat , -indicating that the Client White Point is assumed to be the same as the -Screen White Point. -.LP -This function returns nonzero status -if the format for the new white point is valid; -otherwise, it returns zero. - -.sp -.LP -To set the gamut compression procedure and corresponding client data -in a specified CCC, use -.PN XcmsSetCompressionProc . -.IN "XcmsSetCompressionProc" "" "@DEF@" -.IN "Gamut compression" "setting in Color Conversion Context" -.IN "Gamut compression" "procedure" -.IN "Gamut compression" "client data" -.sM -.FD 0 -XcmsCompressionProc XcmsSetCompressionProc\^(\^\fIccc\fP\^, \fIcompression_proc\fP\^, \fIclient_data\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsCompressionProc \fIcompression_proc\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIcompression_proc\fP 1i -Specifies the gamut compression procedure that is to be applied -when a color lies outside the screen's color gamut. -If NULL is specified and a function using this CCC must convert -a color specification to a device-dependent format and encounters a color -that lies outside the screen's color gamut, -that function will return -.PN XcmsFailure . -.ds Cd the gamut compression procedure -.IP \fIclient_data\fP 1i -Specifies client data for \*(Cd or NULL. -.LP -.eM -The -.PN XcmsSetCompressionProc -function first sets the gamut compression procedure and client data -in the specified CCC with the newly specified procedure and client data -and then returns the old procedure. -.sp -.LP -To set the white point adjustment procedure and corresponding client data -in a specified CCC, use -.PN XcmsSetWhiteAdjustProc . -.IN "XcmsSetWhiteAdjustProc" "" "@DEF@" -.IN "White point adjustment" "setting in Color Conversion Context" -.IN "White point adjustment" "procedure" -.IN "White point adjustment" "client data" -.FD 0 -.sM -XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\fIccc\fP\^, \fIwhite_adjust_proc\fP\^, \fIclient_data\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIwhite_adjust_proc\fP 1i -Specifies the white point adjustment procedure. -.ds Cd the white point adjustment procedure -.IP \fIclient_data\fP 1i -Specifies client data for \*(Cd or NULL. -.LP -.eM -The -.PN XcmsSetWhiteAdjustProc -function first sets the white point adjustment procedure and client data -in the specified CCC with the newly specified procedure and client data -and then returns the old procedure. -.NH 3 -Creating and Freeing a Color Conversion Context -.XS -\*(SN Creating and Freeing a Color Conversion Context -.XE -.LP -You can explicitly create a CCC within your application by calling -.PN XcmsCreateCCC . -These created CCCs can then be used by those functions that explicitly -call for a CCC argument. -Old CCCs that will not be used by the application should be freed using -.PN XcmsFreeCCC . -.sp -.LP -To create a CCC, use -.PN XcmsCreateCCC . -.IN "XcmsCreateCCC" "" "@DEF@" -.IN "Color Conversion Context" "creation" -.IN "CCC" "creation" -.sM -.FD 0 -XcmsCCC XcmsCreateCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^, \fIvisual\fP\^, \fIclient_white_point\fP\^, \fIcompression_proc\fP\^, -.br - \fIcompression_client_data\fP\^, \fIwhite_adjust_proc\fP\^, \fIwhite_adjust_client_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.br - Visual *\fIvisual\fP\^; -.br - XcmsColor *\fIclient_white_point\fP\^; -.br - XcmsCompressionProc \fIcompression_proc\fP\^; -.br - XPointer \fIcompression_client_data\fP\^; -.br - XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^; -.br - XPointer \fIwhite_adjust_client_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.IP \fIvisual\fP 1i -Specifies the visual type. -.IP \fIclient_white_point\fP 1i -Specifies the Client White Point. -If NULL is specified, -the Client White Point is to be assumed to be the same as the -Screen White Point. -Note that the pixel member is ignored. -.IP \fIcompression_proc\fP 1i -Specifies the gamut compression procedure that is to be applied -when a color lies outside the screen's color gamut. -If NULL is specified and a function using this CCC must convert -a color specification to a device-dependent format and encounters a color -that lies outside the screen's color gamut, -that function will return -.PN XcmsFailure . -.IP \fIcompression_client_data\fP 1i -Specifies client data for use by the gamut compression procedure or NULL. -.IP \fIwhite_adjust_proc\fP 1i -Specifies the white adjustment procedure that is to be applied -when the Client White Point differs from the Screen White Point. -NULL indicates that no white point adjustment is desired. -.IP \fIwhite_adjust_client_data\fP 1i -Specifies client data for use with the white point adjustment procedure or NULL. -.LP -.eM -The -.PN XcmsCreateCCC -function creates a CCC for the specified display, screen, and visual. -.LP -.sp -To free a CCC, use -.PN XcmsFreeCCC . -.IN "XcmsFreeCCC" "" "@DEF@" -.IN "Color Conversion Context" "freeing" -.IN "CCC" "freeing" -.sM -.FD 0 -void XcmsFreeCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -The -.PN XcmsFreeCCC -function frees the memory used for the specified CCC. -Note that default CCCs and those currently associated with colormaps -are ignored. -.NH 2 -Converting between Color Spaces -.XS -\*(SN Converting between Color Spaces -.XE -.LP -.sp -To convert an array of color specifications in arbitrary color formats -to a single destination format, use -.PN XcmsConvertColors . -.IN "Color conversion" -.IN "Color" "conversion" -.IN "XcmsConvertColors" "" "@DEF@" -.sM -.FD 0 -Status XcmsConvertColors\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fItarget_format\fP\^, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor \fIcolors_in_out\fP\^[\^]\^; -.br - unsigned int \fIncolors\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - Bool \fIcompression_flags_return\fP\^[\^]\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -If conversion is between device-independent color spaces only -(for example, TekHVC to CIELuv), -the CCC is necessary only to specify the Client White Point. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members are ignored and remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values indicating compression status. -If a non-NULL pointer is supplied, -each element of the array is set to -.PN True -if the corresponding color was compressed and -.PN False -otherwise. -Pass NULL if the compression status is not useful. -.LP -.eM -The -.PN XcmsConvertColors -function converts the color specifications in the specified array of -.PN XcmsColor -structures from their current format to a single target format, -using the specified CCC. -When the return value is -.PN XcmsFailure , -the contents of the color specification array are left unchanged. -.LP -The array may contain a mixture of color specification formats -(for example, 3 CIE XYZ, 2 CIE Luv, and so on). -When the array contains both device-independent and -device-dependent color specifications and the target_format argument specifies -a device-dependent format (for example, -.PN XcmsRGBiFormat , -.PN XcmsRGBFormat ), -all specifications are converted to CIE XYZ format and then to the target -device-dependent format. -.NH 2 -Callback Functions -.XS -\*(SN Callback Functions -.XE -.LP -This section describes the gamut compression and white point -adjustment callbacks. -.LP -The gamut compression procedure specified in the CCC -is called when an attempt to convert a color specification from -.PN XcmsCIEXYZ -to a device-dependent format (typically -.PN XcmsRGBi ) -results in a color that lies outside the screen's color gamut. -If the gamut compression procedure requires client data, this data is passed -via the gamut compression client data in the CCC. -.LP -During color specification conversion between device-independent -and device-dependent color spaces, -if a white point adjustment procedure is specified in the CCC, -it is triggered when the Client White Point and Screen White Point differ. -If required, the client data is obtained from the CCC. -.NH 3 -Prototype Gamut Compression Procedure -.XS -\*(SN Prototype Gamut Compression Procedure -.XE -.LP -The gamut compression callback interface must adhere to the -following: -.IN "XcmsCompressionProc" "" "@DEF@" -.sM -.FD 0 -typedef Status (*\^XcmsCompressionProc\^)\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIindex\fP\^, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor \fIcolors_in_out[]\fP\^; -.br - unsigned int \fIncolors\fP\^; -.br - unsigned int \fIindex\fP\^; -.br - Bool \fIcompression_flags_return[]\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIindex\fP 1i -Specifies the index into the array of -.PN XcmsColor -structures for the encountered color specification that lies outside the -screen's color gamut. -Valid values are 0 (for the first element) to ncolors \- 1. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values for indicating compression status. -If a non-NULL pointer is supplied -and a color at a given index is compressed, then -.PN True -should be stored at the corresponding index in this array; -otherwise, the array should not be modified. -.LP -.eM -When implementing a gamut compression procedure, consider the following -rules and assumptions: -.IP \(bu 5 -The gamut compression procedure can attempt to compress one or multiple -specifications at a time. -.IP \(bu 5 -When called, elements 0 to index \- 1 in the color specification -array can be assumed to fall within the screen's color gamut. -In addition, these color specifications are already in some device-dependent -format (typically -.PN XcmsRGBi ). -If any modifications are made to these color specifications, -they must be in their initial device-dependent format upon return. -.IP \(bu 5 -When called, the element in the color specification array specified -by the index argument contains the color specification outside the -screen's color gamut encountered by the calling routine. -In addition, this color specification can be assumed to be in -.PN XcmsCIEXYZ . -Upon return, this color specification must be in -.PN XcmsCIEXYZ . -.IP \(bu 5 -When called, elements from index to ncolors \- 1 -in the color specification array may or may not fall within the -screen's color gamut. -In addition, these color specifications can be assumed to be in -.PN XcmsCIEXYZ . -If any modifications are made to these color specifications, -they must be in -.PN XcmsCIEXYZ -upon return. -.IP \(bu 5 -The color specifications passed to the gamut compression procedure -have already been adjusted to the Screen White Point. -This means that at this point the color specification's white point -is the Screen White Point. -.IP \(bu 5 -If the gamut compression procedure uses a device-independent color space not -initially accessible for use in the color management system, use -.PN XcmsAddColorSpace -to ensure that it is added. -.NH 3 -Supplied Gamut Compression Procedures -.XS -\*(SN Supplied Gamut Compression Procedures -.XE -.LP -The following equations are useful in describing gamut compression -functions: -.EQ -delim %% -.EN -.LP -.Ds 0 -%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% - -%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]% - -%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% - -%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]% -.De -.LP -The gamut compression callback procedures provided by Xlib are as follows: -.IP \(bu 5 -.PN XcmsCIELabClipL -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing or increasing CIE metric lightness (L*) -in the CIE L*a*b* color space until the color is within the gamut. -If the Psychometric Chroma of the color specification -is beyond maximum for the Psychometric Hue Angle, -then while maintaining the same Psychometric Hue Angle, -the color will be clipped to the CIE L*a*b* coordinates of maximum -Psychometric Chroma. -See -.PN XcmsCIELabQueryMaxC . -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELabClipab -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing Psychometric Chroma, -while maintaining Psychometric Hue Angle, -until the color is within the gamut. -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELabClipLab -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by replacing it with CIE L*a*b* coordinates -that fall within the color gamut while maintaining the original -Psychometric Hue -Angle and whose vector to the original coordinates is the shortest attainable. -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELuvClipL -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing or increasing CIE metric lightness (L*) -in the CIE L*u*v* color space until the color is within the gamut. -If the Psychometric Chroma of the color specification -is beyond maximum for the Psychometric Hue Angle, -then, while maintaining the same Psychometric Hue Angle, -the color will be clipped to the CIE L*u*v* coordinates of maximum -Psychometric Chroma. -See -.PN XcmsCIELuvQueryMaxC . -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELuvClipuv -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing -Psychometric Chroma, while maintaining Psychometric Hue Angle, -until the color is within the gamut. -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELuvClipLuv -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by replacing it with CIE L*u*v* coordinates -that fall within the color gamut while maintaining the original -Psychometric Hue -Angle and whose vector to the original coordinates is the shortest attainable. -No client data is necessary. -.IP \(bu 5 -.PN XcmsTekHVCClipV -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing or increasing the Value dimension -in the TekHVC color space until the color is within the gamut. -If Chroma of the color specification is beyond maximum for the particular Hue, -then, while maintaining the same Hue, -the color will be clipped to the Value and Chroma coordinates -that represent maximum Chroma for that particular Hue. -No client data is necessary. -.IP \(bu 5 -.PN XcmsTekHVCClipC -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing the Chroma dimension -in the TekHVC color space until the color is within the gamut. -No client data is necessary. -.IP \(bu 5 -.PN XcmsTekHVCClipVC -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by replacing it with TekHVC coordinates -that fall within the color gamut while maintaining the original Hue -and whose vector to the original coordinates is the shortest attainable. -No client data is necessary. -.NH 3 -Prototype White Point Adjustment Procedure -.XS -\*(SN Prototype White Point Adjustment Procedure -.XE -.LP -The white point adjustment procedure interface must adhere to the following: -.IN "XcmsWhiteAdjustProc" "" "@DEF@" -.sM -.FD 0 -typedef Status (*\^XcmsWhiteAdjustProc\^)\^(\^\fIccc\fP\^, \fIinitial_white_point\fP\^, \fItarget_white_point\fP\^, \fItarget_format\fP\^, -.br - \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIinitial_white_point\fP\^; -.br - XcmsColor *\fItarget_white_point\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor \fIcolors_in_out[]\fP\^; -.br - unsigned int \fIncolors\fP\^; -.br - Bool \fIcompression_flags_return[]\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIinitial_white_point\fP 1i -Specifies the initial white point. -.IP \fItarget_white_point\fP 1i -Specifies the target white point. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values for indicating compression status. -If a non-NULL pointer is supplied -and a color at a given index is compressed, then -.PN True -should be stored at the corresponding index in this array; -otherwise, the array should not be modified. -.LP -.eM -.NH 3 -Supplied White Point Adjustment Procedures -.XS -\*(SN Supplied White Point Adjustment Procedures -.XE -.LP -White point adjustment procedures provided by Xlib are as follows: -.IP \(bu 5 -.PN XcmsCIELabWhiteShiftColors -.IP -This uses the CIE L*a*b* color space for adjusting the chromatic character -of colors to compensate for the chromatic differences between the source -and destination white points. -This procedure simply converts the color specifications to -.PN XcmsCIELab -using the source white point and then converts to the target specification -format using the destination's white point. -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELuvWhiteShiftColors -.IP -This uses the CIE L*u*v* color space for adjusting the chromatic character -of colors to compensate for the chromatic differences between the source -and destination white points. -This procedure simply converts the color specifications to -.PN XcmsCIELuv -using the source white point and then converts to the target specification -format using the destination's white point. -No client data is necessary. -.IP \(bu 5 -.PN XcmsTekHVCWhiteShiftColors -.IP -This uses the TekHVC color space for adjusting the chromatic character -of colors to compensate for the chromatic differences between the source -and destination white points. -This procedure simply converts the color specifications to -.PN XcmsTekHVC -using the source white point and then converts to the target specification -format using the destination's white point. -An advantage of this procedure over those previously described -is an attempt to minimize hue shift. -No client data is necessary. -.LP -From an implementation point of view, -these white point adjustment procedures convert the color specifications -to a device-independent but white-point-dependent color space -(for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point -and then converting those specifications to the target color space -using another white point. -In other words, -the specification goes in the color space with one white point -but comes out with another white point, -resulting in a chromatic shift based on the chromatic displacement -between the initial white point and target white point. -The CIE color spaces that are assumed to be white-point-independent -are CIE u'v'Y, CIE XYZ, and CIE xyY. -When developing a custom white point adjustment procedure that uses a -device-independent color space not initially accessible for use in the -color management system, use -.PN XcmsAddColorSpace -to ensure that it is added. -.LP -As an example, -if the CCC specifies a white point adjustment procedure -and if the Client White Point and Screen White Point differ, the -.PN XcmsAllocColor -function will use the white point adjustment -procedure twice: -.IP \(bu 5 -Once to convert to -.PN XcmsRGB -.IP \(bu 5 -A second time to convert from -.PN XcmsRGB -.LP -For example, assume the specification is in -.PN XcmsCIEuvY -and the adjustment procedure is -.PN XcmsCIELuvWhiteShiftColors . -During conversion to -.PN XcmsRGB , -the call to -.PN XcmsAllocColor -results in the following series of color specification conversions: -.\" Do these need to be font coded? -.IP \(bu 5 -From -.PN XcmsCIEuvY -to -.PN XcmsCIELuv -using the Client White Point -.IP \(bu 5 -From -.PN XcmsCIELuv -to -.PN XcmsCIEuvY -using the Screen White Point -.IP \(bu 5 -From -.PN XcmsCIEuvY -to -.PN XcmsCIEXYZ -(CIE u'v'Y and XYZ are white-point-independent color spaces) -.IP \(bu 5 -From -.PN XcmsCIEXYZ -to -.PN XcmsRGBi -.IP \(bu 5 -From -.PN XcmsRGBi -to -.PN XcmsRGB -.LP -The resulting RGB specification is passed to -.PN XAllocColor , -and the RGB -specification returned by -.PN XAllocColor -is converted back to -.PN XcmsCIEuvY -by reversing the color conversion sequence. -.NH 2 -Gamut Querying Functions -.XS -\*(SN Gamut Querying Functions -.XE -.LP -This section describes the gamut querying functions that Xlib provides. -These functions allow the client to query the boundary -of the screen's color gamut in terms of the CIE L*a*b*, CIE L*u*v*, -and TekHVC color spaces. -.IN "Gamut querying" -Functions are also provided that allow you to query -the color specification of: -.IP \(bu 5 -White (full-intensity red, green, and blue) -.IP \(bu 5 -Red (full-intensity red while green and blue are zero) -.IP \(bu 5 -Green (full-intensity green while red and blue are zero) -.IP \(bu 5 -Blue (full-intensity blue while red and green are zero) -.IP \(bu 5 -Black (zero-intensity red, green, and blue) -.LP -The white point associated with color specifications passed to -and returned from these gamut querying -functions is assumed to be the Screen White Point. -.IN "Screen White Point" -This is a reasonable assumption, -because the client is trying to query the screen's color gamut. -.LP -The following naming convention is used for the Max and Min functions: -.LP -.Ds 0 -Xcms\fI<color_space>\fPQueryMax\fI<dimensions>\fP - -Xcms\fI<color_space>\fPQueryMin\fI<dimensions>\fP -.De -.LP -The <dimensions> consists of a letter or letters -that identify the dimensions of the color space -that are not fixed. -For example, -.PN XcmsTekHVCQueryMaxC -is given a fixed Hue and Value for which maximum Chroma is found. -.NH 3 -Red, Green, and Blue Queries -.XS -\*(SN Red, Green, and Blue Queries -.XE -.LP -To obtain the color specification for black -(zero-intensity red, green, and blue), use -.PN XcmsQueryBlack . -.IN "XcmsQueryBlack" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryBlack\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs zero-intensity red, green, and blue -.IP \fIcolor_return\fP 1i -Returns the color specification in the specified target format -for \*(Cs. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsQueryBlack -function returns the color specification in the specified target format -for zero-intensity red, green, and blue. -.sp -.LP -To obtain the color specification for blue -(full-intensity blue while red and green are zero), use -.PN XcmsQueryBlue . -.IN "XcmsQueryBlue" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryBlue\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity blue while red and green are zero -.IP \fIcolor_return\fP 1i -Returns the color specification in the specified target format -for \*(Cs. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsQueryBlue -function returns the color specification in the specified target format -for full-intensity blue while red and green are zero. -.sp -.LP -To obtain the color specification for green -(full-intensity green while red and blue are zero), use -.PN XcmsQueryGreen . -.IN "XcmsQueryGreen" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryGreen\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity green while red and blue are zero -.IP \fIcolor_return\fP 1i -Returns the color specification in the specified target format -for \*(Cs. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsQueryGreen -function returns the color specification in the specified target format -for full-intensity green while red and blue are zero. -.sp -.LP -To obtain the color specification for red -(full-intensity red while green and blue are zero), use -.PN XcmsQueryRed . -.IN "XcmsQueryRed" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryRed\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity red while green and blue are zero -.IP \fIcolor_return\fP 1i -Returns the color specification in the specified target format -for \*(Cs. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsQueryRed -function returns the color specification in the specified target format -for full-intensity red while green and blue are zero. -.LP -.sp -To obtain the color specification for white -(full-intensity red, green, and blue), use -.PN XcmsQueryWhite . -.IN "XcmsQueryWhite" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryWhite\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity red, green, and blue -.IP \fIcolor_return\fP 1i -Returns the color specification in the specified target format -for \*(Cs. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsQueryWhite -function returns the color specification in the specified target format -for full-intensity red, green, and blue. -.NH 3 -CIELab Queries -.XS -\*(SN CIELab Queries -.XE -.LP -The following equations are useful in describing the CIELab query functions: -.EQ -delim %% -.EN -.LP -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" -.IN "Psychometric Chroma" "maximum" -.Ds 0 -%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% - -%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]% -.De -.sp -To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle and CIE metric lightness (L*), use -.PN XcmsCIELabQueryMaxC . -.IN "XcmsCIELabQueryMaxC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIL_star\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ls maximum chroma -.IP \fIL_star\fP 1i -Specifies the lightness (L*) at which to find \*(Ls. -.ds Lc maximum chroma -.ds lC hue angle and lightness -.IP \fIcolor_return\fP 1i -Returns the CIE L*a*b* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELabQueryMaxC -function, given a hue angle and lightness, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -.LP -.sp -To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELabQueryMaxL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELabQueryMaxL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ch maximum lightness -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc maximum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE L*a*b* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELabQueryMaxL -function, given a hue angle and chroma, -finds the point in CIE L*a*b* color space of maximum -lightness (L*) displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.sp -.LP -To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle, use -.PN XcmsCIELabQueryMaxLC . -.IN "Psychometric Hue Angle" -.IN "Psychometric Chroma" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" "maximum" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELabQueryMaxLC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Lc maximum chroma -.ds lC hue angle -.IP \fIcolor_return\fP 1i -Returns the CIE L*a*b* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELabQueryMaxLC -function, given a hue angle, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -.sp -.LP -To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELabQueryMinL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "minimum" -.IN "XcmsCIELabQueryMinL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha minimum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ch minimum lightness -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc minimum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE L*a*b* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELabQueryMinL -function, given a hue angle and chroma, -finds the point of minimum lightness (L*) displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.NH 3 -CIELuv Queries -.XS -\*(SN CIELuv Queries -.XE -.LP -The following equations are useful in describing the CIELuv query functions: -.EQ -delim %% -.EN -.LP -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" -.IN "Psychometric Chroma" "maximum" -.Ds 0 -%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% - -%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]% -.De -.sp -.LP -To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle and CIE metric lightness (L*), use -.PN XcmsCIELuvQueryMaxC . -.IN "XcmsCIELuvQueryMaxC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIL_star\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ls maximum chroma -.IP \fIL_star\fP 1i -Specifies the lightness (L*) at which to find \*(Ls. -.ds Lc maximum chroma -.ds lC hue angle and lightness -.IP \fIcolor_return\fP 1i -Returns the CIE L*u*v* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELuvQueryMaxC -function, given a hue angle and lightness, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -.sp -.LP -To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELuvQueryMaxL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELuvQueryMaxL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ls maximum lightness -.IP \fIL_star\fP 1i -Specifies the lightness (L*) at which to find \*(Ls. -.ds Lc maximum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE L*u*v* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELuvQueryMaxL -function, given a hue angle and chroma, -finds the point in CIE L*u*v* color space of maximum -lightness (L*) displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.sp -.LP -To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle, use -.PN XcmsCIELuvQueryMaxLC . -.IN "Psychometric Hue Angle" -.IN "Psychometric Chroma" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" "maximum" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELuvQueryMaxLC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Lc maximum chroma -.ds lC hue angle -.IP \fIcolor_return\fP 1i -Returns the CIE L*u*v* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELuvQueryMaxLC -function, given a hue angle, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -.sp -.LP -To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELuvQueryMinL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "minimum" -.IN "XcmsCIELuvQueryMinL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha minimum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ch minimum lightness -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc minimum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE L*u*v* coordinates of \*(Lc -displayable by the screen for the given \*(lC. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsCIELuvQueryMinL -function, given a hue angle and chroma, -finds the point of minimum lightness (L*) displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.NH 3 -TekHVC Queries -.XS -\*(SN TekHVC Queries -.XE -.LP -To obtain the maximum Chroma for a given Hue and Value, use -.PN XcmsTekHVCQueryMaxC . -.IN "Chroma" -.IN "Chroma" "maximum" -.IN "XcmsTekHVCQueryMaxC" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIvalue\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsFloat \fIvalue\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Hu in which to find the maximum Chroma -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Va maximum Chroma -.IP \fIvalue\fP 1i -Specifies the Value in which to find the \*(Va. -.ds Lc maximum Chroma along with the actual Hue and Value -.ds lC maximum Chroma -.IP \fIcolor_return\fP 1i -Returns the \*(Lc at which the \*(lC was found. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxC -function, given a Hue and Value, -determines the maximum Chroma in TekHVC color space -displayable by the screen. -It returns the maximum Chroma along with the actual Hue -and Value at which the maximum Chroma was found. -.sp -.LP -To obtain the maximum Value for a given Hue and Chroma, use -.PN XcmsTekHVCQueryMaxV . -.IN "Value" -.IN "Value" "maximum" -.IN "XcmsTekHVCQueryMaxV" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Hu in which to find the maximum Value -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Ch maximum Value -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc maximum Value along with the Hue and Chroma -.ds lC maximum Value -.IP \fIcolor_return\fP 1i -Returns the \*(Lc at which the \*(lC was found. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxV -function, given a Hue and Chroma, -determines the maximum Value in TekHVC color space -displayable by the screen. -It returns the maximum Value and the actual Hue and Chroma -at which the maximum Value was found. -.sp -.LP -To obtain the maximum Chroma and Value at which it is reached -for a specified Hue, use -.PN XcmsTekHVCQueryMaxVC . -.IN "Chroma" -.IN "Value" -.IN "Chroma" "maximum" -.IN "Value" "maximum" -.IN "XcmsTekHVCQueryMaxVC" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxVC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Hu in which to find the maximum Chroma -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Lc color specification in \ -XcmsTekHVC for the maximum Chroma, the Value at which \ -that maximum Chroma is reached, and the actual Hue -.ds lC maximum Chroma -.IP \fIcolor_return\fP 1i -Returns the \*(Lc at which the \*(lC was found. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxVC -function, given a Hue, -determines the maximum Chroma in TekHVC color space displayable by the screen -and the Value at which that maximum Chroma is reached. -It returns the maximum Chroma, -the Value at which that maximum Chroma is reached, -and the actual Hue for which the maximum Chroma was found. -.sp -.LP -To obtain a specified number of TekHVC specifications such that they -contain maximum Values for a specified Hue and the -Chroma at which the maximum Values are reached, use -.PN XcmsTekHVCQueryMaxVSamples . -.IN "Chroma" -.IN "Value" -.IN "Chroma" "maximum" -.IN "Value" "maximum" -.IN "XcmsTekHVCQueryMaxVSamples" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxVSamples\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolors_return\fP\^, \fInsamples\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsColor \fIcolors_return[]\fP\^; -.br - unsigned int \fInsamples\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Hu for maximum Chroma/Value samples -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.IP \fInsamples\fP 1i -Specifies the number of samples. -.IP \fIcolors_return\fP 1i -Returns nsamples of color specifications in XcmsTekHVC -such that the Chroma is the maximum attainable for the Value and Hue. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxVSamples -returns nsamples of maximum Value, the Chroma at which that maximum Value -is reached, and the actual Hue for which the maximum Chroma was found. -These sample points may then be used to plot the maximum Value/Chroma -boundary of the screen's color gamut for the specified Hue in TekHVC color -space. -.sp -.LP -To obtain the minimum Value for a given Hue and Chroma, use -.PN XcmsTekHVCQueryMinV . -.IN "Value" -.IN "Value" "minimum" -.IN "XcmsTekHVCQueryMinV" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMinV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Hu in which to find the minimum Value -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Va minimum Value -.IP \fIvalue\fP 1i -Specifies the Value in which to find the \*(Va. -.ds Lc minimum Value and the actual Hue and Chroma -.ds lC minimum Value -.IP \fIcolor_return\fP 1i -Returns the \*(Lc at which the \*(lC was found. -The white point associated with the returned -color specification is the Screen White Point. -The value returned in the pixel member is undefined. -.LP -.eM -The -.PN XcmsTekHVCQueryMinV -function, given a Hue and Chroma, -determines the minimum Value in TekHVC color space displayable by the screen. -It returns the minimum Value and the actual Hue and Chroma at which -the minimum Value was found. -.NH 2 -Color Management Extensions -.XS -\*(SN Color Management Extensions -.XE -.LP -The Xlib color management facilities can be extended in two ways: -.IP \(bu 5 -Device-Independent Color Spaces -.IP -Device-independent color spaces that are derivable to CIE XYZ -space can be added using the -.PN XcmsAddColorSpace -function. -.IP \(bu 5 -Color Characterization Function Set -.IP -A Color Characterization Function Set consists of -device-dependent color spaces and their functions that -convert between these color spaces and the CIE XYZ -color space, bundled together for a specific class of output devices. -A function set can be added using the -.PN XcmsAddFunctionSet -function. -.NH 3 -Color Spaces -.XS -\*(SN Color Spaces -.XE -.LP -The CIE XYZ color space serves as the hub for all -conversions between device-independent and device-dependent color spaces. -Therefore, the knowledge to convert an -.PN XcmsColor -structure to and from CIE XYZ format is associated with each color space. -For example, conversion from CIE L*u*v* to RGB requires the knowledge -to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB. -This knowledge is stored as an array of functions that, -when applied in series, will convert the -.PN XcmsColor -structure to or from CIE XYZ format. -This color specification conversion mechanism facilitates -the addition of color spaces. -.LP -Of course, when converting between only device-independent color spaces -or only device-dependent color spaces, -shortcuts are taken whenever possible. -For example, conversion from TekHVC to CIE L*u*v* is performed -by intermediate conversion to CIE u*v*Y and then to CIE L*u*v*, -thus bypassing conversion between CIE u*v*Y and CIE XYZ. -.NH 3 -Adding Device-Independent Color Spaces -.XS -\*(SN Adding Device-Independent Color Spaces -.XE -.LP -To add a device-independent color space, use -.PN XcmsAddColorSpace . -.IN "XcmsAddColorSpace" "" "@DEF@" -.sM -.FD 0 -Status XcmsAddColorSpace\^(\^\fIcolor_space\fP\^) -.br - XcmsColorSpace *\fIcolor_space\fP\^; -.FN -.IP \fIcolor_space\fP 1i -Specifies the device-independent color space to add. -.LP -.eM -The -.PN XcmsAddColorSpace -function makes a device-independent color space (actually an -.PN XcmsColorSpace -structure) accessible by the color management system. -Because format values for unregistered color spaces are assigned at run time, -they should be treated as private to the client. -If references to an unregistered color space must be made -outside the client (for example, storing color specifications -in a file using the unregistered color space), -then reference should be made by color space prefix -(see -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.LP -If the -.PN XcmsColorSpace -structure is already accessible in the color management system, -.PN XcmsAddColorSpace -returns -.PN XcmsSuccess . -.LP -Note that added -.PN XcmsColorSpaces -must be retained for reference by Xlib. -.NH 3 -Querying Color Space Format and Prefix -.XS -\*(SN Querying Color Space Format and Prefix -.XE -.LP -To obtain the format associated with the color space -associated with a specified color string prefix, use -.PN XcmsFormatOfPrefix . -.IN "XcmsFormatOfPrefix" "" "@DEF@" -.sM -.FD 0 -XcmsColorFormat XcmsFormatOfPrefix\^(\^\fIprefix\fP\^) -.br - char *\fIprefix\fP\^; -.FN -.IP \fIprefix\fP 1i -Specifies the string that contains the color space prefix. -.LP -.eM -The -.PN XcmsFormatOfPrefix -function returns the format for the specified color space prefix -(for example, the string ``CIEXYZ''). -The prefix is case-insensitive. -If the color space is not accessible in the color management system, -.PN XcmsFormatOfPrefix -returns -.PN XcmsUndefinedFormat . -.LP -.sp -To obtain the color string prefix associated with the color space -specified by a color format, use -.PN XcmsPrefixOfFormat . -.IN "XcmsPrefixOfFormat" "" "@DEF@" -.sM -.FD 0 -char *XcmsPrefixOfFormat\^(\^\fIformat\fP\^) -.br - XcmsColorFormat \fIformat\fP\^; -.FN -.IP \fIformat\fP 1i -Specifies the color specification format. -.LP -.eM -The -.PN XcmsPrefixOfFormat -function returns the string prefix associated with the color specification -encoding specified by the format argument. -Otherwise, if no encoding is found, it returns NULL. -The returned string must be treated as read-only. -.NH 3 -Creating Additional Color Spaces -.XS -\*(SN Creating Additional Color Spaces -.XE -.LP -Color space specific information necessary -for color space conversion and color string parsing is stored in an -.PN XcmsColorSpace -structure. -Therefore, a new structure containing this information is required -for each additional color space. -In the case of device-independent color spaces, -a handle to this new structure (that is, by means of a global variable) -is usually made accessible to the client program for use with the -.PN XcmsAddColorSpace -function. -.LP -If a new -.PN XcmsColorSpace -structure specifies a color space not registered with the X Consortium, -they should be treated as private to the client -because format values for unregistered color spaces are assigned at run time. -If references to an unregistered color space must be made outside the -client (for example, storing color specifications in a file using the -unregistered color space), then reference should be made by color space prefix -(see -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef (*XcmsConversionProc)(); -typedef XcmsConversionProc *XcmsFuncListPtr; - /* A NULL terminated list of function pointers*/ - -typedef struct _XcmsColorSpace { - char *prefix; - XcmsColorFormat format; - XcmsParseStringProc parseString; - XcmsFuncListPtr to_CIEXYZ; - XcmsFuncListPtr from_CIEXYZ; - int inverse_flag; -} XcmsColorSpace; -.De -.LP -.eM -The prefix member specifies the prefix that indicates a color string -is in this color space's string format. -For example, the strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ, -and ``rgb'' or ``RGB'' for RGB. -The prefix is case insensitive. -The format member specifies the color specification format. -Formats for unregistered color spaces are assigned at run time. -The parseString member contains a pointer to the function -that can parse a color string into an -.PN XcmsColor -structure. -This function returns an integer (int): nonzero if it succeeded -and zero otherwise. -The to_CIEXYZ and from_CIEXYZ members contain pointers, -each to a NULL terminated list of function pointers. -When the list of functions is executed in series, -it will convert the color specified in an -.PN XcmsColor -structure from/to the current color space format to/from the CIE XYZ format. -Each function returns an integer (int): nonzero if it succeeded -and zero otherwise. -The white point to be associated with the colors is specified -explicitly, even though white points can be found in the CCC. -The inverse_flag member, if nonzero, specifies that for each function listed -in to_CIEXYZ, -its inverse function can be found in from_CIEXYZ such that: -.LP -.Ds 0 -Given: n = number of functions in each list - -for each i, such that 0 <= i < n - from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i]. -.De -.LP -This allows Xlib to use the shortest conversion path, -thus bypassing CIE XYZ if possible (for example, TekHVC to CIE L*u*v*). -.NH 3 -Parse String Callback -.XS -\*(SN Parse String Callback -.XE -.LP -The callback in the -.PN XcmsColorSpace -structure for parsing a color string for the particular color space must -adhere to the following software interface specification: -.IN "XcmsParseStringProc" "" "@DEF@" -.sM -.FD 0 -typedef int (*XcmsParseStringProc)\^(\^\fIcolor_string\fP, \fIcolor_return\fP\^) -.br - char *\fIcolor_string\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIcolor_string\fP 1i -Specifies the color string to parse. -.IP \fIcolor_return\fP 1i -Returns the color specification in the color space's format. -.LP -.eM -.NH 3 -Color Specification Conversion Callback -.XS -\*(SN Color Specification Conversion Callback -.XE -.LP -Callback functions in the -.PN XcmsColorSpace -structure for converting a color specification between device-independent -spaces must adhere to the -following software interface specification: -.sM -.FD 0 -Status ConversionProc\^(\^\fIccc\fP, \fIwhite_point\fP, \fIcolors_in_out\fP, \fIncolors\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIwhite_point\fP\^; -.br - XcmsColor *\fIcolors_in_out\fP\^; -.br - unsigned int \fIncolors\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIwhite_point\fP 1i -Specifies the white point associated with color specifications. -The pixel member should be ignored, -and the entire structure remain unchanged upon return. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.LP -.eM -.sp -Callback functions in the -.PN XcmsColorSpace -structure for converting a color specification to or from a device-dependent -space must adhere to the -following software interface specification: -.sM -.FD 0 -Status ConversionProc\^(\^\fIccc\fP, \fIcolors_in_out\fP, \fIncolors\fP, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIcolors_in_out\fP\^; -.br - unsigned int \fIncolors\fP\^; -.br - Bool \fIcompression_flags_return\fP\^[\^]\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values for indicating compression status. -If a non-NULL pointer is supplied -and a color at a given index is compressed, then -.PN True -should be stored at the corresponding index in this array; -otherwise, the array should not be modified. -.LP -.eM -Conversion functions are available globally for use by other color -spaces. -The conversion functions provided by Xlib are: -.TS H -lw(1.8i) lw(1.8i) lw(1.8i). -_ -.sp 6p -.B -Function Converts from Converts to -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN XcmsCIELabToCIEXYZ -T} T{ -.PN XcmsCIELabFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsCIELuvToCIEuvY -T} T{ -.PN XcmsCIELuvFormat -T} T{ -.PN XcmsCIEuvYFormat -T} -T{ -.PN XcmsCIEXYZToCIELab -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsCIELabFormat -T} -T{ -.PN XcmsCIEXYZToCIEuvY -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsCIEuvYFormat -T} -T{ -.PN XcmsCIEXYZToCIExyY -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsCIExyYFormat -T} -T{ -.PN XcmsCIEXYZToRGBi -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsRGBiFormat -T} -T{ -.PN XcmsCIEuvYToCIELuv -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -.PN XcmsCIELabFormat -T} -T{ -.PN XcmsCIEuvYToCIEXYZ -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsCIEuvYToTekHVC -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -.PN XcmsTekHVCFormat -T} -T{ -.PN XcmsCIExyYToCIEXYZ -T} T{ -.PN XcmsCIExyYFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsRGBToRGBi -T} T{ -.PN XcmsRGBFormat -T} T{ -.PN XcmsRGBiFormat -T} -T{ -.PN XcmsRGBiToCIEXYZ -T} T{ -.PN XcmsRGBiFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsRGBiToRGB -T} T{ -.PN XcmsRGBiFormat -T} T{ -.PN XcmsRGBFormat -T} -T{ -.PN XcmsTekHVCToCIEuvY -T} T{ -.PN XcmsTekHVCFormat -T} T{ -.PN XcmsCIEuvYFormat -T} -.sp 6p -_ -.TE -.NH 3 -Function Sets -.XS -\*(SN Function Sets -.XE -.IN "Function set" -.IN "Function set" "LINEAR_RGB" -.LP -Functions to convert between device-dependent color spaces -and CIE XYZ may differ for different classes of output devices -(for example, color versus gray monitors). -Therefore, the notion of a Color Characterization Function Set -has been developed. -A function set consists of device-dependent color spaces -and the functions that convert color specifications -between these device-dependent color spaces and the CIE XYZ color space -appropriate for a particular class of output devices. -The function set also contains a function that reads -color characterization data off root window properties. -It is this characterization data that will differ between devices within -a class of output devices. -.IN "Device Color Characterization" -For details about how color characterization data is -stored in root window properties, -see the section on Device Color Characterization in the -\fIInter-Client Communication Conventions Manual\fP. -The LINEAR_RGB function set is provided by Xlib -and will support most color monitors. -Function sets may require data that differs -from those needed for the LINEAR_RGB function set. -In that case, -its corresponding data may be stored on different root window properties. -.NH 3 -Adding Function Sets -.XS -\*(SN Adding Function Sets -.XE -.LP -To add a function set, use -.PN XcmsAddFunctionSet . -.IN "XcmsAddFunctionSet" "" "@DEF@" -.sM -.FD 0 -Status XcmsAddFunctionSet\^(\^\fIfunction_set\fP\^) -.br - XcmsFunctionSet *\fIfunction_set\fP\^; -.FN -.IP \fIfunction_set\fP 1i -Specifies the function set to add. -.LP -.eM -The -.PN XcmsAddFunctionSet -function adds a function set to the color management system. -If the function set uses device-dependent -.PN XcmsColorSpace -structures not accessible in the color management system, -.PN XcmsAddFunctionSet -adds them. -If an added -.PN XcmsColorSpace -structure is for a device-dependent color space not registered -with the X Consortium, -they should be treated as private to the client -because format values for unregistered color spaces are assigned at run time. -If references to an unregistered color space must be made outside the -client (for example, storing color specifications in a file -using the unregistered color space), -then reference should be made by color space prefix -(see -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.LP -Additional function sets should be added before any calls to other -Xlib routines are made. -If not, the -.PN XcmsPerScrnInfo -member of a previously created -.PN XcmsCCC -does not have the opportunity to initialize -with the added function set. -.NH 3 -Creating Additional Function Sets -.XS -\*(SN Creating Additional Function Sets -.XE -.LP -The creation of additional function sets should be -required only when an output device does not conform to existing -function sets or when additional device-dependent color spaces are necessary. -A function set consists primarily of a collection of device-dependent -.PN XcmsColorSpace -structures and a means to read and store a -screen's color characterization data. -This data is stored in an -.PN XcmsFunctionSet -structure. -A handle to this structure (that is, by means of global variable) -is usually made accessible to the client program for use with -.PN XcmsAddFunctionSet . -.LP -If a function set uses new device-dependent -.PN XcmsColorSpace -structures, -they will be transparently processed into the color management system. -Function sets can share an -.PN XcmsColorSpace -structure for a device-dependent color space. -In addition, multiple -.PN XcmsColorSpace -structures are allowed for a device-dependent color space; -however, a function set can reference only one of them. -These -.PN XcmsColorSpace -structures will differ in the functions to convert to and from CIE XYZ, -thus tailored for the specific function set. -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XcmsFunctionSet { - XcmsColorSpace **DDColorSpaces; - XcmsScreenInitProc screenInitProc; - XcmsScreenFreeProc screenFreeProc; -} XcmsFunctionSet; -.De -.LP -.eM -The DDColorSpaces member is a pointer to a NULL terminated list -of pointers to -.PN XcmsColorSpace -structures for the device-dependent color spaces that are supported -by the function set. -The screenInitProc member is set to the callback procedure (see the following -interface specification) that initializes the -.PN XcmsPerScrnInfo -structure for a particular screen. -.LP -The screen initialization callback must adhere to the following software -interface specification: -.IN "XcmsScreenInitProc" "" "@DEF@" -.sM -.FD 0 -typedef Status (*XcmsScreenInitProc)\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIscreen_info\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.br - XcmsPerScrnInfo *\fIscreen_info\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.IP \fIscreen_info\fP 1i -Specifies the -.PN XcmsPerScrnInfo -structure, which contains the per screen information. -.LP -.eM -The screen initialization callback in the -.PN XcmsFunctionSet -structure fetches the color characterization data (device profile) for -the specified screen, -typically off properties on the -screen's root window. -It then initializes the specified -.PN XcmsPerScrnInfo -structure. -.IN "Device profile" -.IN "Color Characterization Data" -If successful, the procedure fills in the -.PN XcmsPerScrnInfo -structure as follows: -.IP \(bu 5 -It sets the screenData member to the address -of the created device profile data structure -(contents known only by the function set). -.IP \(bu 5 -It next sets the screenWhitePoint member. -.IP \(bu 5 -It next sets the functionSet member to the address of the -.PN XcmsFunctionSet -structure. -.IP \(bu 5 -It then sets the state member to -.PN XcmsInitSuccess -and finally returns -.PN XcmsSuccess . -.LP -If unsuccessful, the procedure sets the state member to -.PN XcmsInitFailure -and returns -.PN XcmsFailure . -.LP -The -.PN XcmsPerScrnInfo -structure contains: -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XcmsPerScrnInfo { - XcmsColor screenWhitePoint; - XPointer functionSet; - XPointer screenData; - unsigned char state; - char pad[3]; -} XcmsPerScrnInfo; -.De -.LP -.eM -The screenWhitePoint member specifies the white point inherent to -the screen. -The functionSet member specifies the appropriate function set. -The screenData member specifies the device profile. -The state member is set to one of the following: -.IP \(bu 5 -.PN XcmsInitNone -indicates initialization has not been previously attempted. -.IP \(bu 5 -.PN XcmsInitFailure -indicates initialization has been previously attempted but failed. -.IP \(bu 5 -.PN XcmsInitSuccess -indicates initialization has been previously attempted and succeeded. -.LP -The screen free callback must adhere to the following software -interface specification: -.IN "XcmsScreenFreeProc" "" "@DEF@" -.sM -.FD 0 -typedef void (*XcmsScreenFreeProc)\^(\^\fIscreenData\fP\^) -.br - XPointer \fIscreenData\fP\^; -.FN -.IP \fIscreenData\fP 1i -Specifies the data to be freed. -.LP -.eM -This function is called to free the screenData stored in an -.PN XcmsPerScrnInfo -structure. -.bp diff --git a/libX11/specs/libX11/CH06.xml b/libX11/specs/libX11/CH06.xml new file mode 100644 index 000000000..9ca12db0c --- /dev/null +++ b/libX11/specs/libX11/CH06.xml @@ -0,0 +1,7439 @@ +<chapter id="color_management_functions">
+<title>Color Management Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 6 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 6: Color Management Functions -->
+<!-- .XE -->
+Each X window always has an associated colormap that
+provides a level of indirection between pixel values and colors displayed
+on the screen.
+Xlib provides functions that you can use to manipulate a colormap.
+The X protocol defines colors using values in the <acronym>RGB</acronym> color space.
+The <acronym>RGB</acronym> color space is device dependent;
+rendering an <acronym>RGB</acronym> value on differing output devices typically results
+in different colors.
+Xlib also provides a means for clients to specify color using
+device-independent color spaces for consistent results across devices.
+Xlib supports device-independent color spaces derivable from the <acronym>CIE</acronym> XYZ
+color space.
+This includes the <acronym>CIE</acronym> XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
+the TekHVC color space.
+</para>
+<para>
+<!-- .LP -->
+This chapter discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Create, copy, and destroy a colormap
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Specify colors by name or value
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Allocate, modify, and free color cells
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Read entries in a colormap
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convert between color spaces
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Control aspects of color conversion
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Query the color gamut of a screen
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Add new color spaces
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+All functions, types, and symbols in this chapter with the prefix ``Xcms''
+are defined in
+<!-- .hN X11/Xcms.h . -->
+The remaining functions and types are defined in
+<!-- .hN X11/Xlib.h . -->
+</para>
+<para>
+<!-- .LP -->
+Functions in this chapter manipulate the representation of color on the
+screen.
+For each possible value that a pixel can take in a window,
+there is a color cell in the colormap.
+For example,
+if a window is 4 bits deep, pixel values 0 through 15 are defined.
+A colormap is a collection of color cells.
+A color cell consists of a triple of red, green, and blue (<acronym>RGB</acronym>) values.
+The hardware imposes limits on the number of significant
+bits in these values.
+As each pixel is read out of display memory, the pixel
+is looked up in a colormap.
+The <acronym>RGB</acronym> value of the cell determines what color is displayed on the screen.
+On a grayscale display with a black-and-white monitor,
+the values are combined to determine the brightness on the screen.
+</para>
+<para>
+<!-- .LP -->
+Typically, an application allocates color cells or sets of color cells
+to obtain the desired colors.
+The client can allocate read-only cells.
+In which case,
+the pixel values for these colors can be shared among multiple applications,
+and the <acronym>RGB</acronym> value of the cell cannot be changed.
+If the client allocates read/write cells,
+they are exclusively owned by the client,
+and the color associated with the pixel value can be changed at will.
+Cells must be allocated (and, if read/write, initialized with an <acronym>RGB</acronym> value)
+by a client to obtain desired colors.
+The use of pixel value for an
+unallocated cell results in an undefined color.
+</para>
+<para>
+<!-- .LP -->
+Because colormaps are associated with windows, X supports displays
+with multiple colormaps and, indeed, different types of colormaps.
+If there are insufficient colormap resources in the display,
+some windows will display in their true colors, and others
+will display with incorrect colors.
+A window manager usually controls which windows are displayed
+in their true colors if more than one colormap is required for
+the color resources the applications are using.
+At any time, there is a set of installed colormaps for a screen.
+Windows using one of the installed colormaps display with true colors, and
+windows using other colormaps generally display with incorrect colors.
+You can control the set of installed colormaps by using
+<function>XInstallColormap</function>
+and
+<function>XUninstallColormap</function>.
+</para>
+<para>
+<!-- .LP -->
+Colormaps are local to a particular screen.
+Screens always have a default colormap,
+and programs typically allocate cells out of this colormap.
+Generally, you should not write applications that monopolize
+color resources.
+Although some hardware supports multiple colormaps installed at one time,
+many of the hardware displays
+built today support only a single installed colormap, so the primitives
+are written to encourage sharing of colormap entries between applications.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>DefaultColormap </function>
+macro returns the default colormap.
+The
+<function>DefaultVisual </function>
+macro
+returns the default visual type for the specified screen.
+<indexterm><primary>Color map</primary></indexterm>
+Possible visual types are
+<function>StaticGray</function>,
+<function>GrayScale</function>,
+<function>StaticColor</function>,
+<function>PseudoColor</function>,
+<function>TrueColor</function>,
+or
+<function>DirectColor </function>
+(see section 3.1).
+</para>
+<sect1 id="Color_Structures">
+<title>Color Structures</title>
+<!-- .XS -->
+<!-- (SN Color Structures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Functions that operate only on <acronym>RGB</acronym> color space values use an
+<function>XColor</function>
+structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XColor</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ unsigned long pixel; /* pixel value */
+ unsigned short red, green, blue; /* rgb values */
+ char flags; /* DoRed, DoGreen, DoBlue */
+ char pad;
+} XColor;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The red, green, and blue values are always in the range 0 to 65535
+inclusive, independent of the number of bits actually used in the
+display hardware.
+The server scales these values down to the range used by the hardware.
+Black is represented by (0,0,0),
+and white is represented by (65535,65535,65535).
+<indexterm><primary>Color</primary></indexterm>
+In some functions,
+the flags member controls which of the red, green, and blue members is used
+and can be the inclusive OR of zero or more of
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Functions that operate on all color space values use an
+<function>XcmsColor</function>
+structure.
+This structure contains a union of substructures,
+each supporting color specification encoding for a particular color space.
+Like the
+<function>XColor</function>
+structure, the
+<function>XcmsColor</function>
+structure contains pixel
+and color specification information (the spec member in the
+<function>XcmsColor</function>
+structure).
+<indexterm significance="preferred"><primary>XcmsColor</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 2.5i -->
+<!-- .ta .5i 1i 2.5i -->
+typedef unsigned long XcmsColorFormat; /* Color Specification Format */
+
+typedef struct {
+ union {
+ XcmsRGB RGB;
+ XcmsRGBi RGBi;
+ XcmsCIEXYZ CIEXYZ;
+ XcmsCIEuvY CIEuvY;
+ XcmsCIExyY CIExyY;
+ XcmsCIELab CIELab;
+ XcmsCIELuv CIELuv;
+ XcmsTekHVC TekHVC;
+ XcmsPad Pad;
+ } spec;
+ unsigned long pixel;
+ XcmsColorFormat format;
+} XcmsColor; /* Xcms Color Structure */
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Because the color specification can be encoded for the various color spaces,
+encoding for the spec member is identified by the format member,
+which is of type
+<function>XcmsColorFormat</function>.
+The following macros define standard formats.
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+#define XcmsUndefinedFormat 0x00000000
+#define XcmsCIEXYZFormat 0x00000001 /* CIE XYZ */
+#define XcmsCIEuvYFormat 0x00000002 /* CIE u'v'Y */
+#define XcmsCIExyYFormat 0x00000003 /* CIE xyY */
+#define XcmsCIELabFormat 0x00000004 /* CIE L*a*b* */
+#define XcmsCIELuvFormat 0x00000005 /* CIE L*u*v* */
+#define XcmsTekHVCFormat 0x00000006 /* TekHVC */
+#define XcmsRGBFormat 0x80000000 /* RGB Device */
+#define XcmsRGBiFormat 0x80000001 /* RGB Intensity */
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Formats for device-independent color spaces are
+distinguishable from those for device-dependent spaces by the 32nd bit.
+If this bit is set,
+it indicates that the color specification is in a device-dependent form;
+otherwise, it is in a device-independent form.
+If the 31st bit is set,
+this indicates that the color space has been added to Xlib at run time
+(see section 6.12.4).
+The format value for a color space added at run time may be different each
+time the program is executed.
+If references to such a color space must be made outside the client
+(for example, storing a color specification in a file),
+then reference should be made by color space string prefix
+(see
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+</para>
+<para>
+<!-- .LP -->
+Data types that describe the color specification encoding for the various
+color spaces are defined as follows:
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XcmsRGB</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef double XcmsFloat;
+
+typedef struct {
+ unsigned short red; /* 0x0000 to 0xffff */
+ unsigned short green; /* 0x0000 to 0xffff */
+ unsigned short blue; /* 0x0000 to 0xffff */
+} XcmsRGB; /* RGB Device */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsRGBi</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat red; /* 0.0 to 1.0 */
+ XcmsFloat green; /* 0.0 to 1.0 */
+ XcmsFloat blue; /* 0.0 to 1.0 */
+} XcmsRGBi; /* RGB Intensity */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIEXYZ</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat X;
+ XcmsFloat Y; /* 0.0 to 1.0 */
+ XcmsFloat Z;
+} XcmsCIEXYZ; /* CIE XYZ */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIEuvY</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat u_prime; /* 0.0 to ~0.6 */
+ XcmsFloat v_prime; /* 0.0 to ~0.6 */
+ XcmsFloat Y; /* 0.0 to 1.0 */
+} XcmsCIEuvY; /* CIE u'v'Y */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIExyY</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat x; /* 0.0 to ~.75 */
+ XcmsFloat y; /* 0.0 to ~.85 */
+ XcmsFloat Y; /* 0.0 to 1.0 */
+} XcmsCIExyY; /* CIE xyY */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIELab</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat L_star; /* 0.0 to 100.0 */
+ XcmsFloat a_star;
+ XcmsFloat b_star;
+} XcmsCIELab; /* CIE L*a*b* */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIELuv</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat L_star; /* 0.0 to 100.0 */
+ XcmsFloat u_star;
+ XcmsFloat v_star;
+} XcmsCIELuv; /* CIE L*u*v* */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsTekHVC</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat H; /* 0.0 to 360.0 */
+ XcmsFloat V; /* 0.0 to 100.0 */
+ XcmsFloat C; /* 0.0 to 100.0 */
+} XcmsTekHVC; /* TekHVC */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsPad</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ XcmsFloat pad0;
+ XcmsFloat pad1;
+ XcmsFloat pad2;
+ XcmsFloat pad3;
+} XcmsPad; /* four doubles */
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The device-dependent formats provided allow color specification in:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<acronym>RGB</acronym> Intensity
+(<function>XcmsRGBi</function>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Red, green, and blue linear intensity values,
+floating-point values from 0.0 to 1.0,
+where 1.0 indicates full intensity, 0.5 half intensity, and so on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<acronym>RGB</acronym> Device
+(<function>XcmsRGB</function>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Red, green, and blue values appropriate for the specified output device.
+<function>XcmsRGB</function>
+values are of type unsigned short,
+scaled from 0 to 65535 inclusive,
+and are interchangeable with the red, green, and blue values in an
+<function>XColor</function>
+structure.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+It is important to note that <acronym>RGB</acronym> Intensity values are not gamma corrected
+values.
+In contrast,
+<acronym>RGB</acronym> Device values generated as a result of converting color specifications
+are always gamma corrected, and
+<acronym>RGB</acronym> Device values acquired as a result of querying a colormap
+or passed in by the client are assumed by Xlib to be gamma corrected.
+The term <emphasis remap='I'><acronym>RGB</acronym> value</emphasis> in this manual always refers to an <acronym>RGB</acronym> Device value.
+</para>
+</sect1>
+<sect1 id="Color_Strings">
+<title>Color Strings</title>
+<!-- .XS -->
+<!-- (SN Color Strings -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides a mechanism for using string names for colors.
+A color string may either contain an abstract color name
+or a numerical color specification.
+Color strings are case-insensitive.
+</para>
+<para>
+<!-- .LP -->
+Color strings are used in the following functions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XAllocNamedColor</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsAllocNamedColor</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XLookupColor</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsLookupColor</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XParseColor</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XStoreNamedColor</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Xlib supports the use of abstract color names, for example, red or blue.
+A value for this abstract name is obtained by searching one or more color
+name databases.
+Xlib first searches zero or more client-side databases;
+the number, location, and content of these databases is
+implementation-dependent and might depend on the current locale.
+If the name is not found, Xlib then looks for the color in the
+X server's database.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+A numerical color specification
+consists of a color space name and a set of values in the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<emphasis remap='I'><color_space_name></emphasis>:<emphasis remap='I'><value>/.../<value></emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The following are examples of valid color strings.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"CIEXYZ:0.3227/0.28133/0.2493"
+"RGBi:1.0/0.0/0.0"
+"rgb:00/ff/00"
+"CIELuv:50.0/0.0/0.0"
+</literallayout>
+The syntax and semantics of numerical specifications are given
+for each standard color space in the following sections.
+</para>
+<sect2 id="RGB_Device_String_Specification">
+<title><acronym>RGB</acronym> Device String Specification</title>
+<!-- .XS -->
+<!-- (SN <acronym>RGB</acronym> Device String Specification -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An <acronym>RGB</acronym> Device specification is identified by
+the prefix ``rgb:'' and conforms to the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+rgb:<emphasis remap='I'><red>/<green>/<blue></emphasis>
+
+ <emphasis remap='I'><red></emphasis>, <emphasis remap='I'><green></emphasis>, <emphasis remap='I'><blue></emphasis> := <emphasis remap='I'>h</emphasis> | <emphasis remap='I'>hh</emphasis> | <emphasis remap='I'>hhh</emphasis> | <emphasis remap='I'>hhhh</emphasis>
+ <emphasis remap='I'>h</emphasis> := single hexadecimal digits (case insignificant)
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Note that <emphasis remap='I'>h</emphasis> indicates the value scaled in 4 bits,
+<emphasis remap='I'>hh</emphasis> the value scaled in 8 bits,
+<emphasis remap='I'>hhh</emphasis> the value scaled in 12 bits,
+and <emphasis remap='I'>hhhh</emphasis> the value scaled in 16 bits, respectively.
+</para>
+<para>
+<!-- .LP -->
+Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',
+but mixed numbers of hexadecimal digit strings
+(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')
+are also allowed.
+</para>
+<para>
+<!-- .LP -->
+For backward compatibility, an older syntax for <acronym>RGB</acronym> Device is
+supported, but its continued use is not encouraged.
+The syntax is an initial sharp sign character followed by
+a numeric specification, in one of the following formats:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA 2i -->
+<!-- .ta 2i -->
+#RGB (4 bits each)
+#RRGGBB (8 bits each)
+#RRRGGGBBB (12 bits each)
+#RRRRGGGGBBBB (16 bits each)
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The R, G, and B represent single hexadecimal digits.
+When fewer than 16 bits each are specified,
+they represent the most significant bits of the value
+(unlike the ``rgb:'' syntax, in which values are scaled).
+For example, the string ``#3a7'' is the same as ``#3000a0007000''.
+</para>
+</sect2>
+<sect2 id="RGB_Intensity_String_Specification">
+<title><acronym>RGB</acronym> Intensity String Specification</title>
+<!-- .XS -->
+<!-- (SN RGB Intensity String Specification -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An <acronym>RGB</acronym> intensity specification is identified
+by the prefix ``rgbi:'' and conforms to the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+rgbi:<emphasis remap='I'><red>/<green>/<blue></emphasis>
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Note that red, green, and blue are floating-point values
+between 0.0 and 1.0, inclusive.
+The input format for these values is an optional sign,
+a string of numbers possibly containing a decimal point,
+and an optional exponent field containing an E or e
+followed by a possibly signed integer string.
+</para>
+</sect2>
+<sect2 id="Device_Independent_String_Specifications">
+<title>Device-Independent String Specifications</title>
+<!-- .XS -->
+<!-- (SN Device-Independent String Specifications -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The standard device-independent string specifications have
+the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+CIEXYZ:<emphasis remap='I'><X>/<Y>/<Z></emphasis>
+CIEuvY:<emphasis remap='I'><u>/<v>/<Y></emphasis>
+CIExyY:<emphasis remap='I'><x>/<y>/<Y></emphasis>
+CIELab:<emphasis remap='I'><L>/<a>/<b></emphasis>
+CIELuv:<emphasis remap='I'><L>/<u>/<v></emphasis>
+TekHVC:<emphasis remap='I'><H>/<V>/<C></emphasis>
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
+floating-point values.
+The syntax for these values is an optional plus or minus sign,
+a string of digits possibly containing a decimal point,
+and an optional exponent field consisting of an ``E'' or ``e''
+followed by an optional plus or minus followed by a string of digits.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Color_Conversion_Contexts_and_Gamut_Mapping">
+<title>Color Conversion Contexts and Gamut Mapping</title>
+<!-- .XS -->
+<!-- (SN Color Conversion Contexts and Gamut Mapping -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When Xlib converts device-independent color specifications
+into device-dependent specifications and vice versa,
+it uses knowledge about the color limitations of the screen hardware.
+This information, typically called the device profile,
+<indexterm><primary>Device profile</primary></indexterm>
+is available in a Color Conversion Context (CCC).
+<indexterm><primary>Color Conversion Context</primary></indexterm>
+<indexterm><primary>CCC</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Because a specified color may be outside the color gamut of the target screen
+and the white point associated with the color specification may differ
+from the white point inherent to the screen,
+Xlib applies gamut mapping when it encounters certain conditions:
+<indexterm><primary>White point</primary></indexterm>
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Gamut compression occurs when conversion of device-independent
+color specifications to device-dependent color specifications
+results in a color out of the target screen's gamut.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+White adjustment occurs when the inherent white point of the screen
+differs from the white point assumed by the client.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Gamut handling methods are stored as callbacks in the CCC,
+which in turn are used by the color space conversion routines.
+Client data is also stored in the CCC for each callback.
+The CCC also contains the white point the client assumes to be
+associated with color specifications (that is, the Client White Point).
+<indexterm><primary>Client White Point</primary></indexterm>
+<indexterm><primary>Gamut compression</primary></indexterm>
+<indexterm><primary>Gamut handling</primary></indexterm>
+<indexterm><primary>White point adjustment</primary></indexterm>
+The client can specify the gamut handling callbacks and client data
+as well as the Client White Point.
+Xlib does not preclude the X client from performing other
+forms of gamut handling (for example, gamut expansion);
+however, Xlib does not provide direct support for gamut handling
+other than white adjustment and gamut compression.
+</para>
+<para>
+<!-- .LP -->
+Associated with each colormap is an initial CCC transparently generated by
+Xlib.
+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
+Therefore,
+when you specify a colormap as an argument to an Xlib function,
+you are indirectly specifying a CCC.
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+There is a default CCC associated with each screen.
+Newly created CCCs inherit attributes from the default CCC,
+so the default CCC attributes can be modified to affect new CCCs.
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Xcms functions in which gamut mapping can occur return
+<function>Status</function>
+and have specific status values defined for them,
+as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XcmsFailure</function>
+indicates that the function failed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsSuccess</function>
+indicates that the function succeeded.
+In addition,
+if the function performed any color conversion,
+the colors did not need to be compressed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsSuccessWithCompression</function>
+indicates the function performed color conversion
+and at least one of the colors needed to be compressed.
+The gamut compression method is determined by the gamut compression
+procedure in the CCC that is specified directly as a function argument
+or in the CCC indirectly specified by means of the colormap argument.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Creating_Copying_and_Destroying_Colormaps">
+<title>Creating, Copying, and Destroying Colormaps</title>
+<!-- .XS -->
+<!-- (SN Creating, Copying, and Destroying Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To create a colormap for a screen, use
+<function>XCreateColormap</function>.</para>
+<indexterm significance="preferred"><primary>XCreateColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap<function> XCreateColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Visual<parameter> *visual</parameter></paramdef>
+ <paramdef>int<parameter> alloc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi on whose screen you want to create a colormap -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a visual type supported on the screen.
+If the visual type is not one supported by the screen,
+a
+<function>BadMatch</function>
+error results.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>alloc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap entries to be allocated.
+You can pass
+<function>AllocNone </function>
+or
+<function>AllocAll</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateColormap</function>
+function creates a colormap of the specified visual type for the screen
+on which the specified window resides and returns the colormap ID
+associated with it.
+Note that the specified window is only used to determine the screen.
+</para>
+<para>
+<!-- .LP -->
+The initial values of the colormap entries are undefined for the
+visual classes
+<function>GrayScale</function>,
+<function>PseudoColor</function>,
+and
+<function>DirectColor</function>.
+For
+<function>StaticGray</function>,
+<function>StaticColor</function>,
+and
+<function>TrueColor</function>,
+the entries have defined values,
+but those values are specific to the visual and are not defined by X.
+For
+<function>StaticGray</function>,
+<function>StaticColor</function>,
+and
+<function>TrueColor</function>,
+alloc must be
+<function>AllocNone</function>,
+or a
+<function>BadMatch</function>
+error results.
+For the other visual classes,
+if alloc is
+<function>AllocNone</function>,
+the colormap initially has no allocated entries,
+and clients can allocate them.
+For information about the visual types,
+see section 3.1.
+</para>
+<para>
+<!-- .LP -->
+If alloc is
+<function>AllocAll</function>,
+the entire colormap is allocated writable.
+The initial values of all allocated entries are undefined.
+For
+<function>GrayScale</function>
+and
+<function>PseudoColor</function>,
+the effect is as if an
+<function>XAllocColorCells</function>
+call returned all pixel values from zero to N - 1,
+where N is the colormap entries value in the specified visual.
+For
+<function>DirectColor</function>,
+the effect is as if an
+<function>XAllocColorPlanes</function>
+call returned a pixel value of zero and red_mask, green_mask,
+and blue_mask values containing the same bits as the corresponding
+masks in the specified visual.
+However, in all cases,
+none of these entries can be freed by using
+<function>XFreeColors</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateColormap</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a new colormap when the allocation out of a previously
+shared colormap has failed because of resource exhaustion, use
+<function>XCopyColormapAndFree</function>.
+<indexterm significance="preferred"><primary>XCopyColormapAndFree</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap<function>XCopyColormapAndFree </function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyColormapAndFree</function>
+function creates a colormap of the same visual type and for the same screen
+as the specified colormap and returns the new colormap ID.
+It also moves all of the client's existing allocation from the specified
+colormap to the new colormap with their color values intact
+and their read-only or writable characteristics intact and frees those entries
+in the specified colormap.
+Color values in other entries in the new colormap are undefined.
+If the specified colormap was created by the client with alloc set to
+<function>AllocAll</function>,
+the new colormap is also created with
+<function>AllocAll</function>,
+all color values for all entries are copied from the specified colormap,
+and then all entries in the specified colormap are freed.
+If the specified colormap was not created by the client with
+<function>AllocAll</function>,
+the allocations to be moved are all those pixels and planes
+that have been allocated by the client using
+<function>XAllocColor</function>,
+<function>XAllocNamedColor</function>,
+<function>XAllocColorCells</function>,
+or
+<function>XAllocColorPlanes</function>
+and that have not been freed since they were allocated.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyColormapAndFree</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadColor </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a colormap, use
+<function>XFreeColormap</function>.
+<indexterm significance="preferred"><primary>XFreeColormap</primary></indexterm>
+</para>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XFreeColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Cm that you want to destroy -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap (Cm.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeColormap</function>
+function deletes the association between the colormap resource ID
+and the colormap and frees the colormap storage.
+However, this function has no effect on the default colormap for a screen.
+If the specified colormap is an installed map for a screen,
+it is uninstalled (see
+<function>XUninstallColormap</function>).
+If the specified colormap is defined as the colormap for a window (by
+<function>XCreateWindow</function>,
+<function>XSetWindowColormap</function>,
+or
+<function>XChangeWindowAttributes</function>),
+<function>XFreeColormap</function>
+changes the colormap associated with the window to
+<function>None </function>
+and generates a
+<function>ColormapNotify</function>
+event.
+X does not define the colors displayed for a window with a colormap of
+<function>None</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeColormap</function>
+can generate a
+<function>BadColor </function>
+error.
+</para>
+</sect1>
+<sect1 id="Mapping_Color_Names_to_Values">
+<title>Mapping Color Names to Values</title>
+<!-- .XS -->
+<!-- (SN Mapping Color Names to Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to an <acronym>RGB</acronym> value, use
+<function>XLookupColor</function>.
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XLookupColor</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XLookupColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>char<parameter> *color_name</parameter></paramdef>
+ <paramdef>XColor*exact_def_return,<parameter> *screen_def_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color name string (for example, red) whose color
+definition structure you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>exact_def_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the exact <acronym>RGB</acronym> values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_def_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the closest <acronym>RGB</acronym> values provided by the hardware.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookupColor</function>
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns both the exact color values and
+the closest values provided by the screen
+with respect to the visual type of the specified colormap.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+<function>XLookupColor</function>
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XLookupColor</function>
+can generate a
+<function>BadColor </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to the exact <acronym>RGB</acronym> value, use
+<function>XParseColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XParseColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XParseColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>char<parameter> *spec</parameter></paramdef>
+ <paramdef>XColor<parameter> *exact_def_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>spec</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color name string;
+case is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>exact_def_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the exact color value for later use and sets the
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>
+flags.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XParseColor</function>
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns the exact color value.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+<function>XParseColor</function>
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XParseColor</function>
+can generate a
+<function>BadColor </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to a value in an arbitrary color space, use
+<function>XcmsLookupColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsLookupColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsLookupColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>char<parameter> *color_string</parameter></paramdef>
+ <paramdef>XcmsColor*color_exact_return,<parameter> *color_screen_return</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+<!-- .ds St -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color string(St.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_exact_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification parsed from the color string
+or parsed from the corresponding string found in a color-name database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_screen_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color that can be reproduced on the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>result_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color format for the returned color
+specifications (color_screen_return and color_exact_return arguments).
+If the format is
+<function>XcmsUndefinedFormat</function>
+and the color string contains a
+numerical color specification,
+the specification is returned in the format used in that numerical
+color specification.
+If the format is
+<function>XcmsUndefinedFormat</function>
+and the color string contains a color name,
+the specification is returned in the format used
+to store the color in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsLookupColor</function>
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns both the exact color values and
+the closest values provided by the screen
+with respect to the visual type of the specified colormap.
+The values are returned in the format specified by result_format.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+<function>XcmsLookupColor</function>
+returns
+<function>XcmsSuccess</function>
+or
+<function>XcmsSuccessWithCompression</function>
+if the name is resolved; otherwise, it returns
+<function>XcmsFailure</function>.
+If
+<function>XcmsSuccessWithCompression</function>
+is returned, the color specification returned in
+color_screen_return is the result of gamut compression.
+</para>
+</sect1>
+
+<sect1 id="Allocating_and_Freeing_Color_Cells">
+<title>Allocating and Freeing Color Cells</title>
+<!-- .XS -->
+<!-- (SN Allocating and Freeing Color Cells -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+There are two ways of allocating color cells:
+explicitly as read-only entries, one pixel value at a time,
+or read/write,
+where you can allocate a number of color cells and planes simultaneously.
+<indexterm><primary>Read-only colormap cells</primary></indexterm>
+A read-only cell has its <acronym>RGB</acronym> value set by the server.
+<indexterm><primary>Read/write colormap cells</primary></indexterm>
+Read/write cells do not have defined colors initially;
+functions described in the next section must be used to store values into them.
+Although it is possible for any client to store values into a read/write
+cell allocated by another client,
+read/write cells normally should be considered private to the client
+that allocated them.
+</para>
+<para>
+<!-- .LP -->
+Read-only colormap cells are shared among clients.
+The server counts each allocation and freeing of the cell by clients.
+When the last client frees a shared cell, the cell is finally deallocated.
+If a single client allocates the same read-only cell multiple
+times, the server counts each such allocation, not just the first one.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell with an <acronym>RGB</acronym> value, use
+<function>XAllocColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XAllocColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XColor<parameter> *screen_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies and returns the values actually used in the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocColor</function>
+function allocates a read-only colormap entry corresponding to the closest
+<acronym>RGB</acronym> value supported by the hardware.
+<function>XAllocColor</function>
+returns the pixel value of the color closest to the specified
+<acronym>RGB</acronym> elements supported by the hardware
+and returns the <acronym>RGB</acronym> value actually used.
+The corresponding colormap cell is read-only.
+In addition,
+<function>XAllocColor</function>
+returns nonzero if it succeeded or zero if it failed.
+<indexterm><primary>Color map</primary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm><primary>Allocation</primary><secondary>colormap</secondary></indexterm>
+<indexterm><primary>read-only colormap cells</primary></indexterm>
+Multiple clients that request the same effective <acronym>RGB</acronym> value can be assigned
+the same read-only entry, thus allowing entries to be shared.
+When the last client deallocates a shared cell, it is deallocated.
+<function>XAllocColor</function>
+does not use or affect the flags in the
+<function>XColor</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocColor</function>
+can generate a
+<function>BadColor </function>
+error.
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell with a color in arbitrary format, use
+<function>XcmsAllocColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsAllocColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsAllocColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color to allocate and returns the pixel and color
+that is actually used in the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>result_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color format for the returned color specification.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAllocColor</function>
+function is similar to
+<function>XAllocColor</function>
+except the color can be specified in any format.
+The
+<function>XcmsAllocColor</function>
+function ultimately calls
+<function>XAllocColor</function>
+to allocate a read-only color cell (colormap entry) with the specified color.
+<function>XcmsAllocColor</function>
+first converts the color specified
+to an <acronym>RGB</acronym> value and then passes this to
+<function>XAllocColor</function>.
+<function>XcmsAllocColor</function>
+returns the pixel value of the color cell and the color specification
+actually allocated.
+This returned color specification is the result of converting the <acronym>RGB</acronym> value
+returned by
+<function>XAllocColor </function>
+into the format specified with the result_format argument.
+If there is no interest in a returned color specification,
+unnecessary computation can be bypassed if result_format is set to
+<function>XcmsRGBFormat</function>.
+The corresponding colormap cell is read-only.
+If this routine returns
+<function>XcmsFailure</function>,
+the color_in_out color specification is left unchanged.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsAllocColor</function>
+can generate a
+<function>BadColor</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell using a color name and return the closest
+color supported by the hardware in <acronym>RGB</acronym> format, use
+<function>XAllocNamedColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocNamedColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XAllocNamedColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>char<parameter> *color_name</parameter></paramdef>
+ <paramdef>XColor*screen_def_return,<parameter> *exact_def_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color name string (for example, red) whose color
+definition structure you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_def_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the closest <acronym>RGB</acronym> values provided by the hardware.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>exact_def_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the exact <acronym>RGB</acronym> values.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocNamedColor</function>
+function looks up the named color with respect to the screen that is
+associated with the specified colormap.
+It returns both the exact database definition and
+the closest color supported by the screen.
+The allocated color cell is read-only.
+The pixel value is returned in screen_def_return.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+If screen_def_return and exact_def_return
+point to the same structure, the pixel field will be set correctly,
+but the color values are undefined.
+<function>XAllocNamedColor</function>
+returns nonzero if a cell is allocated;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocNamedColor</function>
+can generate a
+<function>BadColor</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell using a color name and return the closest
+color supported by the hardware in an arbitrary format, use
+<function>XcmsAllocNamedColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsAllocNamedColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsAllocNamedColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>char<parameter> *color_string</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_screen_return</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_exact_return</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+<!-- .ds St \ whose color definition structure is to be returned -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color string(St.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_screen_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the pixel value of the color cell and color specification
+that actually is stored for that cell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_exact_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification parsed from the color string
+or parsed from the corresponding string found in a color-name database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>result_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color format for the returned color
+specifications (color_screen_return and color_exact_return arguments).
+If the format is
+<function>XcmsUndefinedFormat</function>
+and the color string contains a
+numerical color specification,
+the specification is returned in the format used in that numerical
+color specification.
+If the format is
+<function>XcmsUndefinedFormat</function>
+and the color string contains a color name,
+the specification is returned in the format used
+to store the color in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAllocNamedColor</function>
+function is similar to
+<function>XAllocNamedColor</function>
+except that the color returned can be in any format specified.
+This function
+ultimately calls
+<function>XAllocColor</function>
+to allocate a read-only color cell with
+the color specified by a color string.
+The color string is parsed into an
+<function>XcmsColor</function>
+structure (see
+<function>XcmsLookupColor</function>),
+converted
+to an <acronym>RGB</acronym> value, and finally passed to
+<function>XAllocColor</function>.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+</para>
+<para>
+<!-- .LP -->
+This function returns both the color specification as a result
+of parsing (exact specification) and the actual color specification
+stored (screen specification).
+This screen specification is the result of converting the <acronym>RGB</acronym> value
+returned by
+<function>XAllocColor</function>
+into the format specified in result_format.
+If there is no interest in a returned color specification,
+unnecessary computation can be bypassed if result_format is set to
+<function>XcmsRGBFormat</function>.
+If color_screen_return and color_exact_return
+point to the same structure, the pixel field will be set correctly,
+but the color values are undefined.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsAllocNamedColor</function>
+can generate a
+<function>BadColor</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate read/write color cell and color plane combinations for a
+<function>PseudoColor</function>
+model, use
+<function>XAllocColorCells</function>.
+</para>
+<indexterm><primary>Read/write colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Allocation</primary><secondary>read/write colormap cells</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocColorCells</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XAllocColorCells</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>Bool<parameter> contig</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> plane_masks_return[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> nplanes</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> npixels</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>contig</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the planes must be contiguous.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>plane_mask_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of plane masks.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nplanes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of plane masks that are to be returned in the plane masks
+array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixels_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of pixel values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npixels</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of pixel values that are to be returned in the
+pixels_return array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+The
+<function>XAllocColorCells</function>
+function allocates read/write color cells.
+The number of colors must be positive and the number of planes nonnegative,
+or a
+<function>BadValue</function>
+error results.
+If ncolors and nplanes are requested,
+then ncolors pixels
+and nplane plane masks are returned.
+No mask will have any bits set to 1 in common with
+any other mask or with any of the pixels.
+By ORing together each pixel with zero or more masks,
+ncolors * %2 sup nplanes% distinct pixels can be produced.
+All of these are
+allocated writable by the request.
+For
+<function>GrayScale </function>
+or
+<function>PseudoColor</function>,
+each mask has exactly one bit set to 1.
+For
+<function>DirectColor</function>,
+each has exactly three bits set to 1.
+If contig is
+<function>True </function>
+and if all masks are ORed
+together, a single contiguous set of bits set to 1 will be formed for
+<function>GrayScale</function>
+or
+<function>PseudoColor </function>
+and three contiguous sets of bits set to 1 (one within each
+pixel subfield) for
+<function>DirectColor</function>.
+The <acronym>RGB</acronym> values of the allocated
+entries are undefined.
+<function>XAllocColorCells</function>
+returns nonzero if it succeeded or zero if it failed.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocColorCells</function>
+can generate
+<function>BadColor</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate read/write color resources for a
+<function>DirectColor</function>
+model, use
+<function>XAllocColorPlanes</function>.
+</para>
+<indexterm><primary>Read/write colormap planes</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Allocation</primary><secondary>read/write colormap planes</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocColorPlanes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XAllocColorPlanes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>Bool<parameter> contig</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>
+ <paramdef>int<parameter> ncolors</parameter></paramdef>
+ <paramdef>intnreds,ngreens,<parameter> nblues</parameter></paramdef>
+ <paramdef>unsignedlong*rmask_return,*gmask_return,<parameter> *bmask_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>contig</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the planes must be contiguous.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixels_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of pixel values.
+<function>XAllocColorPlanes</function>
+returns the pixel values in this array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of pixel values that are to be returned in the
+pixels_return array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nreds</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ngreens</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nblues</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+Specify the number of red, green, and blue planes.
+The value you pass must be nonnegative.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rmask_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gmask_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bmask_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return bit masks for the red, green, and blue planes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+The specified ncolors must be positive;
+and nreds, ngreens, and nblues must be nonnegative,
+or a
+<function>BadValue</function>
+error results.
+If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested,
+ncolors pixels are returned; and the masks have nreds, ngreens, and
+nblues bits set to 1, respectively.
+If contig is
+<function>True</function>,
+each mask will have
+a contiguous set of bits set to 1.
+No mask will have any bits set to 1 in common with
+any other mask or with any of the pixels.
+For
+<function>DirectColor</function>,
+each mask
+will lie within the corresponding pixel subfield.
+By ORing together
+subsets of masks with each pixel value,
+ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced.
+All of these are allocated by the request.
+However, in the
+colormap, there are only ncolors * %2 sup nreds% independent red entries,
+ncolors * %2 sup ngreens% independent green entries,
+and ncolors * %2 sup nblues% independent blue entries.
+This is true even for
+<function>PseudoColor</function>.
+When the colormap entry of a pixel
+value is changed (using
+<function>XStoreColors</function>,
+<function>XStoreColor</function>,
+or
+<function>XStoreNamedColor</function>),
+the pixel is decomposed according to the masks,
+and the corresponding independent entries are updated.
+<function>XAllocColorPlanes</function>
+returns nonzero if it succeeded or zero if it failed.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocColorPlanes</function>
+can generate
+<function>BadColor</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm><primary>Freeing</primary><secondary>colors</secondary></indexterm>
+To free colormap cells, use
+<function>XFreeColors</function>.
+<indexterm significance="preferred"><primary>XFreeColors</primary></indexterm>
+<indexterm><primary>Color</primary><secondary>deallocation</secondary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XFreeColors</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> pixels[]</parameter></paramdef>
+ <paramdef>int<parameter> npixels</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> planes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+<!-- .ds Pi that map to the cells in the specified colormap -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixels</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of pixel values (Pi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npixels</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>planes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the planes you want to free.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeColors</function>
+function frees the cells represented by pixels whose values are in the
+pixels array.
+The planes argument should not have any bits set to 1 in common with any of the
+pixels.
+The set of all pixels is produced by ORing together subsets of
+the planes argument with the pixels.
+The request frees all of these pixels that
+were allocated by the client (using
+<indexterm><primary>XAllocColor</primary></indexterm>
+<indexterm><primary>XAllocNamedColor</primary></indexterm>
+<indexterm><primary>XAllocColorCells</primary></indexterm>
+<indexterm><primary>XAllocColorPlanes</primary></indexterm>
+<function>XAllocColor</function>,
+<function>XAllocNamedColor</function>,
+<function>XAllocColorCells</function>,
+and
+<function>XAllocColorPlanes</function>).
+Note that freeing an
+individual pixel obtained from
+<function>XAllocColorPlanes </function>
+may not actually allow
+it to be reused until all of its related pixels are also freed.
+Similarly,
+a read-only entry is not actually freed until it has been freed by all clients,
+and if a client allocates the same read-only entry multiple times,
+it must free the entry that many times before the entry is actually freed.
+</para>
+<para>
+<!-- .LP -->
+All specified pixels that are allocated by the client in the colormap are
+freed, even if one or more pixels produce an error.
+If a specified pixel is not a valid index into the colormap, a
+<function>BadValue </function>
+error results.
+If a specified pixel is not allocated by the
+client (that is, is unallocated or is only allocated by another client)
+or if the colormap was created with all entries writable (by passing
+<function>AllocAll</function>
+to
+<function>XCreateColormap</function>),
+a
+<function>BadAccess</function>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeColors</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Modifying_and_Querying_Colormap_Cells">
+<title>Modifying and Querying Colormap Cells</title>
+<!-- .XS -->
+<!-- (SN Modifying and Querying Colormap Cells -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store an <acronym>RGB</acronym> value in a single colormap cell, use
+<function>XStoreColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XStoreColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XColor<parameter> *color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pixel and <acronym>RGB</acronym> values.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreColor</function>
+function changes the colormap entry of the pixel value specified in the
+pixel member of the
+<function>XColor</function>
+structure.
+You specified this value in the
+pixel member of the
+<function>XColor</function>
+structure.
+This pixel value must be a read/write cell and a valid index into the colormap.
+If a specified pixel is not a valid index into the colormap,
+a
+<function>BadValue</function>
+error results.
+<function>XStoreColor</function>
+also changes the red, green, and/or blue color components.
+You specify which color components are to be changed by setting
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and/or
+<function>DoBlue</function>
+in the flags member of the
+<function>XColor</function>
+structure.
+If the colormap is an installed map for its screen,
+the changes are visible immediately.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreColor</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store multiple <acronym>RGB</acronym> values in multiple colormap cells, use
+<function>XStoreColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XStoreColors</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XColor<parameter> color[]</parameter></paramdef>
+ <paramdef>int<parameter> ncolors</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of color definition structures to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .\"Specifies the number of color definition structures. -->
+Specifies the number of
+<function>XColor</function>
+structures in the color definition array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreColors</function>
+function changes the colormap entries of the pixel values
+specified in the pixel members of the
+<function>XColor</function>
+structures.
+You specify which color components are to be changed by setting
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and/or
+<function>DoBlue</function>
+in the flags member of the
+<function>XColor</function>
+structures.
+If the colormap is an installed map for its screen, the
+changes are visible immediately.
+<function>XStoreColors </function>
+changes the specified pixels if they are allocated writable in the colormap
+by any client, even if one or more pixels generates an error.
+If a specified pixel is not a valid index into the colormap, a
+<function>BadValue</function>
+error results.
+If a specified pixel either is unallocated or is allocated read-only, a
+<function>BadAccess</function>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreColors</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a color of arbitrary format in a single colormap cell, use
+<function>XcmsStoreColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsStoreColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsStoreColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color cell and the color to store.
+Values specified in this
+<function>XcmsColor</function>
+structure remain unchanged on return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsStoreColor</function>
+function converts the color specified in the
+<function>XcmsColor</function>
+structure into <acronym>RGB</acronym> values.
+It then uses this <acronym>RGB</acronym> specification in an
+<function>XColor</function>
+structure, whose three flags
+(<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>)
+are set, in a call to
+<function>XStoreColor</function>
+to change the color cell specified by the pixel member of the
+<function>XcmsColor</function>
+structure.
+This pixel value must be a valid index for the specified colormap,
+and the color cell specified by the pixel value must be a read/write cell.
+If the pixel value is not a valid index, a
+<function>BadValue</function>
+error results.
+If the color cell is unallocated or is allocated read-only, a
+<function>BadAccess</function>
+error results.
+If the colormap is an installed map for its screen,
+the changes are visible immediately.
+</para>
+<para>
+<!-- .LP -->
+Note that
+<function>XStoreColor</function>
+has no return value; therefore, an
+<function>XcmsSuccess</function>
+return value from this function indicates that the conversion
+to <acronym>RGB</acronym> succeeded and the call to
+<function>XStoreColor</function>
+was made.
+To obtain the actual color stored, use
+<function>XcmsQueryColor</function>.
+Because of the screen's hardware limitations or gamut compression,
+the color stored in the colormap may not be identical
+to the color specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsStoreColor</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+and
+<function>BadValue</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store multiple colors of arbitrary format in multiple colormap cells, use
+<function>XcmsStoreColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsStoreColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsStoreColors</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> colors[]</parameter></paramdef>
+ <paramdef>int<parameter> ncolors</parameter></paramdef>
+ <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color specification array of
+<function>XcmsColor</function>
+structures, each specifying a color cell and the color to store in that
+cell.
+Values specified in the array remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_flags_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of Boolean values indicating compression status.
+If a non-NULL pointer is supplied,
+each element of the array is set to
+<function>True</function>
+if the corresponding color was compressed and
+<function>False</function>
+otherwise.
+Pass NULL if the compression status is not useful.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsStoreColors</function>
+function converts the colors specified in the array of
+<function>XcmsColor</function>
+structures into <acronym>RGB</acronym> values and then uses these <acronym>RGB</acronym> specifications in
+<function>XColor</function>
+structures, whose three flags
+(<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>)
+are set, in a call to
+<function>XStoreColors</function>
+to change the color cells specified by the pixel member of the corresponding
+<function>XcmsColor</function>
+structure.
+Each pixel value must be a valid index for the specified colormap,
+and the color cell specified by each pixel value must be a read/write cell.
+If a pixel value is not a valid index, a
+<function>BadValue</function>
+error results.
+If a color cell is unallocated or is allocated read-only, a
+<function>BadAccess</function>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+If the colormap is an installed map for its screen,
+the changes are visible immediately.
+</para>
+<para>
+<!-- .LP -->
+Note that
+<function>XStoreColors</function>
+has no return value; therefore, an
+<function>XcmsSuccess</function>
+return value from this function indicates that conversions
+to <acronym>RGB</acronym> succeeded and the call to
+<function>XStoreColors</function>
+was made.
+To obtain the actual colors stored, use
+<function>XcmsQueryColors</function>.
+Because of the screen's hardware limitations or gamut compression,
+the colors stored in the colormap may not be identical
+to the colors specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsStoreColors</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+and
+<function>BadValue</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a color specified by name in a single colormap cell, use
+<function>XStoreNamedColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreNamedColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XStoreNamedColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>char<parameter> *color</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>
+ <paramdef>int<parameter> flags</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color name string (for example, red).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixel</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the entry in the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>flags</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which red, green, and blue components are set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreNamedColor</function>
+function looks up the named color with respect to the screen associated with
+the colormap and stores the result in the specified colormap.
+The pixel argument determines the entry in the colormap.
+The flags argument determines which of the red, green, and blue components
+are set.
+You can set this member to the
+bitwise inclusive OR of the bits
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+If the specified pixel is not a valid index into the colormap, a
+<function>BadValue</function>
+error results.
+If the specified pixel either is unallocated or is allocated read-only, a
+<function>BadAccess</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreNamedColor</function>
+can generate
+<function>BadAccess</function>,
+<function>BadColor</function>,
+<function>BadName</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XQueryColor</function>
+and
+<function>XQueryColors</function>
+functions take pixel values in the pixel member of
+<function>XColor</function>
+structures and store in the structures the <acronym>RGB</acronym> values for those
+pixels from the specified colormap.
+The values returned for an unallocated entry are undefined.
+These functions also set the flags member in the
+<function>XColor</function>
+structure to all three colors.
+If a pixel is not a valid index into the specified colormap, a
+<function>BadValue</function>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query the <acronym>RGB</acronym> value of a single colormap cell, use
+<function>XQueryColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XQueryColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XQueryColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XColor<parameter> *def_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>def_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies and returns the <acronym>RGB</acronym> values for the pixel specified in the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryColor</function>
+function returns the current <acronym>RGB</acronym> value for the pixel in the
+<function>XColor</function>
+structure and sets the
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>
+flags.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryColor</function>
+can generate
+<function>BadColor</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query the <acronym>RGB</acronym> values of multiple colormap cells, use
+<function>XQueryColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XQueryColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XQueryColors</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XColor<parameter> defs_in_out[]</parameter></paramdef>
+ <paramdef>int<parameter> ncolors</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>defs_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies and returns an array of color definition structures for the pixel
+specified in the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .\"Specifies the number of color definition structures. -->
+Specifies the number of
+<function>XColor</function>
+structures in the color definition array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryColors</function>
+function returns the <acronym>RGB</acronym> value for each pixel in each
+<function>XColor</function>
+structure and sets the
+<function>DoRed</function>,
+<function>DoGreen</function>,
+and
+<function>DoBlue</function>
+flags in each structure.
+
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryColors</function>
+can generate
+<function>BadColor</function>
+and
+<function>BadValue </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To query the color of a single colormap cell in an arbitrary format, use
+<function>XcmsQueryColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsQueryColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryColor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pixel member that indicates the color cell to query.
+The color specification stored for the color cell is returned in this
+<function>XcmsColor</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>result_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color format for the returned color specification.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryColor</function>
+function obtains the <acronym>RGB</acronym> value
+for the pixel value in the pixel member of the specified
+<function>XcmsColor</function>
+structure and then
+converts the value to the target format as
+specified by the result_format argument.
+If the pixel is not a valid index in the specified colormap, a
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsQueryColor</function>
+can generate
+<function>BadColor</function>
+and
+<function>BadValue</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To query the color of multiple colormap cells in an arbitrary format, use
+<function>XcmsQueryColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsQueryColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryColors</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of
+<function>XcmsColor</function>
+structures, each pixel member indicating the color cell to query.
+The color specifications for the color cells are returned in these structures.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>result_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color format for the returned color specification.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryColors</function>
+function obtains the <acronym>RGB</acronym> values
+for pixel values in the pixel members of
+<function>XcmsColor</function>
+structures and then
+converts the values to the target format as
+specified by the result_format argument.
+If a pixel is not a valid index into the specified colormap, a
+<function>BadValue</function>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsQueryColors</function>
+can generate
+<function>BadColor</function>
+and
+<function>BadValue</function>
+errors.
+</para>
+</sect1>
+<sect1 id="Color_Conversion_Context_Functions">
+<title>Color Conversion Context Functions</title>
+<!-- .XS -->
+<!-- (SN Color Conversion Context Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes functions to create, modify,
+and query Color Conversion Contexts (CCCs).
+</para>
+<para>
+<!-- .LP -->
+Associated with each colormap is an initial CCC transparently generated by
+Xlib.
+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
+Therefore, when you specify a colormap as an argument to a function,
+you are indirectly specifying a CCC.
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+The CCC attributes that can be modified by the X client are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Client White Point
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Gamut compression procedure and client data
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+White point adjustment procedure and client data
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The initial values for these attributes are implementation specific.
+The CCC attributes for subsequently created CCCs can be defined
+by changing the CCC attributes of the default CCC.
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+There is a default CCC associated with each screen.
+</para>
+<sect2 id="Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">
+<title>Getting and Setting the Color Conversion Context of a Colormap</title>
+<!-- .XS -->
+<!-- (SN Getting and Setting the Color Conversion Context of a Colormap -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the CCC associated with a colormap, use
+<function>XcmsCCCOfColormap</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCCCOfColormap</primary></indexterm>
+<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsCCC <function>XcmsCCCOfColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCCCOfColormap</function>
+function returns the CCC associated with the specified colormap.
+Once obtained,
+the CCC attributes can be queried or modified.
+Unless the CCC associated with the specified colormap is changed with
+<function>XcmsSetCCCOfColormap</function>,
+this CCC is used when the specified colormap is used as an argument
+to color functions.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To change the CCC associated with a colormap, use
+<function>XcmsSetCCCOfColormap</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetCCCOfColormap</primary></indexterm>
+<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsCCC <function>XcmsSetCCCOfColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetCCCOfColormap</function>
+function changes the CCC associated with the specified colormap.
+It returns the CCC previously associated with the colormap.
+If they are not used again in the application,
+CCCs should be freed by calling
+<function>XcmsFreeCCC</function>.
+Several colormaps may share the same CCC without restriction; this
+includes the CCCs generated by Xlib with each colormap. Xlib, however,
+creates a new CCC with each new colormap.
+</para>
+</sect2>
+<sect2 id="Obtaining_the_Default_Color_Conversion_Context">
+<title>Obtaining the Default Color Conversion Context</title>
+<!-- .XS -->
+<!-- (SN Obtaining the Default Color Conversion Context -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can change the default CCC attributes for subsequently created CCCs
+by changing the CCC attributes of the default CCC.
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+A default CCC is associated with each screen.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the default CCC for a screen, use
+<function>XcmsDefaultCCC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsDefaultCCC</primary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsCCC <function>XcmsDefaultCCC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsDefaultCCC</function>
+function returns the default CCC for the specified screen.
+Its visual is the default visual of the screen.
+Its initial gamut compression and white point
+adjustment procedures as well as the associated client data are implementation
+specific.
+</para>
+</sect2>
+<sect2 id="Color_Conversion_Context_Macros">
+<title>Color Conversion Context Macros</title>
+<!-- .XS -->
+<!-- (SN Color Conversion Context Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications should not directly modify any part of the
+<function>XcmsCCC</function>.
+The following lists the C language macros, their corresponding function
+equivalents for other language bindings, and what data they both
+can return.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>DisplayOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsDisplayOfCCC</primary></indexterm>
+<!-- .sM -->
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>DisplayOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display <function>*XcmsDisplayOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the display associated with the specified CCC.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>VisualOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsVisualOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>VisualOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Visual<function>*XcmsVisualOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the visual associated with the specified CCC.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>ScreenNumberOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsScreenNumberOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>ScreenNumberOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XcmsScreenNumberOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the number of the screen associated with the specified CCC.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>ScreenWhitePointOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsScreenWhitePointOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>ScreenWhitePointOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsColor <function>XcmsScreenWhitePointOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the white point of the screen associated with the specified CCC.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>ClientWhitePointOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsClientWhitePointOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef> <function>ClientWhitePointOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsColor<function> *XcmsClientWhitePointOfCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the Client White Point of the specified CCC.
+</para>
+</sect2>
+
+<sect2 id="Modifying_Attributes_of_a_Color_Conversion_Context">
+<title>Modifying Attributes of a Color Conversion Context</title>
+<!-- .XS -->
+<!-- (SN Modifying Attributes of a Color Conversion Context -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the Client White Point in the CCC, use
+<function>XcmsSetWhitePoint</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetWhitePoint</primary></indexterm>
+<indexterm><primary>Client White Point</primary><secondary>of Color Conversion Context</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function> XcmsSetWhitePoint</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+<!-- .ds Co new Client White Point -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new Client White Point.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetWhitePoint</function>
+function changes the Client White Point in the specified CCC.
+Note that the pixel member is ignored
+and that the color specification is left unchanged upon return.
+The format for the new white point must be
+<function>XcmsCIEXYZFormat</function>,
+<function>XcmsCIEuvYFormat</function>,
+<function>XcmsCIExyYFormat</function>,
+or
+<function>XcmsUndefinedFormat</function>.
+If the color argument is NULL, this function sets the format component of the
+Client White Point specification to
+<function>XcmsUndefinedFormat</function>,
+indicating that the Client White Point is assumed to be the same as the
+Screen White Point.
+</para>
+<para>
+<!-- .LP -->
+This function returns nonzero status
+if the format for the new white point is valid;
+otherwise, it returns zero.
+
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the gamut compression procedure and corresponding client data
+in a specified CCC, use
+<function>XcmsSetCompressionProc</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetCompressionProc</primary></indexterm>
+<indexterm><primary>Gamut compression</primary><secondary>setting in Color Conversion Context</secondary></indexterm>
+<indexterm><primary>Gamut compression</primary><secondary>procedure</secondary></indexterm>
+<indexterm><primary>Gamut compression</primary><secondary>client data</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsCompressionProc <function>XcmsSetCompressionProc</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the gamut compression procedure that is to be applied
+when a color lies outside the screen's color gamut.
+If NULL is specified and a function using this CCC must convert
+a color specification to a device-dependent format and encounters a color
+that lies outside the screen's color gamut,
+that function will return
+<function>XcmsFailure</function>.
+<!-- .ds Cd the gamut compression procedure -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client data for gamut compression procedure or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetCompressionProc</function>
+function first sets the gamut compression procedure and client data
+in the specified CCC with the newly specified procedure and client data
+and then returns the old procedure.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the white point adjustment procedure and corresponding client data
+in a specified CCC, use
+<function>XcmsSetWhiteAdjustProc</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetWhiteAdjustProc</primary></indexterm>
+<indexterm><primary>White point adjustment</primary><secondary>setting in Color Conversion Context</secondary></indexterm>
+<indexterm><primary>White point adjustment</primary><secondary>procedure</secondary></indexterm>
+<indexterm><primary>White point adjustment</primary><secondary>client data</secondary></indexterm>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsWhiteAdjustProc <function>XcmsSetWhiteAdjustProc</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>white_adjust_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the white point adjustment procedure.
+<!-- .ds Cd the white point adjustment procedure -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client data for white point adjustment procedure or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetWhiteAdjustProc</function>
+function first sets the white point adjustment procedure and client data
+in the specified CCC with the newly specified procedure and client data
+and then returns the old procedure.
+</para>
+</sect2>
+<sect2 id="Creating_and_Freeing_a_Color_Conversion_Context">
+<title>Creating and Freeing a Color Conversion Context</title>
+<!-- .XS -->
+<!-- (SN Creating and Freeing a Color Conversion Context -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can explicitly create a CCC within your application by calling
+<function>XcmsCreateCCC</function>.
+These created CCCs can then be used by those functions that explicitly
+call for a CCC argument.
+Old CCCs that will not be used by the application should be freed using
+<function>XcmsFreeCCC</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To create a CCC, use
+<function>XcmsCreateCCC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCreateCCC</primary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>creation</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsCCC <function>XcmsCreateCCC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+ <paramdef>Visual<parameter> *visual</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *client_white_point</parameter></paramdef>
+ <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>
+ <paramdef>XPointer<parameter> compression_client_data</parameter></paramdef>
+ <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>
+ <paramdef>XPointer<parameter> white_adjust_client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_white_point</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Client White Point.
+If NULL is specified,
+the Client White Point is to be assumed to be the same as the
+Screen White Point.
+Note that the pixel member is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the gamut compression procedure that is to be applied
+when a color lies outside the screen's color gamut.
+If NULL is specified and a function using this CCC must convert
+a color specification to a device-dependent format and encounters a color
+that lies outside the screen's color gamut,
+that function will return
+<function>XcmsFailure</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client data for use by the gamut compression procedure or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>white_adjust_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the white adjustment procedure that is to be applied
+when the Client White Point differs from the Screen White Point.
+NULL indicates that no white point adjustment is desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>white_adjust_client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client data for use with the white point adjustment procedure or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCreateCCC</function>
+function creates a CCC for the specified display, screen, and visual.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a CCC, use
+<function>XcmsFreeCCC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsFreeCCC</primary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>freeing</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>XcmsFreeCCC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsFreeCCC</function>
+function frees the memory used for the specified CCC.
+Note that default CCCs and those currently associated with colormaps
+are ignored.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Converting_between_Color_Spaces">
+<title>Converting between Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Converting between Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert an array of color specifications in arbitrary color formats
+to a single destination format, use
+<function>XcmsConvertColors</function>.
+</para>
+<indexterm><primary>Color conversion</primary></indexterm>
+<indexterm><primary>Color</primary><secondary>conversion</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsConvertColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsConvertColors</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+If conversion is between device-independent color spaces only
+(for example, TekHVC to CIELuv),
+the CCC is necessary only to specify the Client White Point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of color specifications.
+Pixel members are ignored and remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_flags_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of Boolean values indicating compression status.
+If a non-NULL pointer is supplied,
+each element of the array is set to
+<function>True</function>
+if the corresponding color was compressed and
+<function>False</function>
+otherwise.
+Pass NULL if the compression status is not useful.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsConvertColors</function>
+function converts the color specifications in the specified array of
+<function>XcmsColor</function>
+structures from their current format to a single target format,
+using the specified CCC.
+When the return value is
+<function>XcmsFailure</function>,
+the contents of the color specification array are left unchanged.
+</para>
+<para>
+<!-- .LP -->
+The array may contain a mixture of color specification formats
+(for example, 3 <acronym>CIE</acronym> XYZ, 2 <acronym>CIE</acronym> Luv, and so on).
+When the array contains both device-independent and
+device-dependent color specifications and the target_format argument specifies
+a device-dependent format (for example,
+<function>XcmsRGBiFormat</function>,
+<function>XcmsRGBFormat</function>),
+all specifications are converted to <acronym>CIE</acronym> XYZ format and then to the target
+device-dependent format.
+</para>
+</sect1>
+<sect1 id="Callback_Functions">
+<title>Callback Functions</title>
+<!-- .XS -->
+<!-- (SN Callback Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes the gamut compression and white point
+adjustment callbacks.
+</para>
+<para>
+<!-- .LP -->
+The gamut compression procedure specified in the CCC
+is called when an attempt to convert a color specification from
+<function>XcmsCIEXYZ</function>
+to a device-dependent format (typically
+<function>XcmsRGBi</function>)
+results in a color that lies outside the screen's color gamut.
+If the gamut compression procedure requires client data, this data is passed
+via the gamut compression client data in the CCC.
+</para>
+<para>
+<!-- .LP -->
+During color specification conversion between device-independent
+and device-dependent color spaces,
+if a white point adjustment procedure is specified in the CCC,
+it is triggered when the Client White Point and Screen White Point differ.
+If required, the client data is obtained from the CCC.
+</para>
+<sect2 id="Prototype_Gamut_Compression_Procedure">
+<title>Prototype Gamut Compression Procedure</title>
+<!-- .XS -->
+<!-- (SN Prototype Gamut Compression Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The gamut compression callback interface must adhere to the
+following:
+</para>
+<indexterm significance="preferred"><primary>XcmsCompressionProc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef Status<function>(*XcmsCompressionProc</function>)</funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+ <paramdef>unsignedint<parameter> index</parameter></paramdef>
+ <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>index</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the index into the array of
+<function>XcmsColor</function>
+structures for the encountered color specification that lies outside the
+screen's color gamut.
+Valid values are 0 (for the first element) to ncolors - 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_flags_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+<function>True</function>
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When implementing a gamut compression procedure, consider the following
+rules and assumptions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The gamut compression procedure can attempt to compress one or multiple
+specifications at a time.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When called, elements 0 to index - 1 in the color specification
+array can be assumed to fall within the screen's color gamut.
+In addition, these color specifications are already in some device-dependent
+format (typically
+<function>XcmsRGBi</function>).
+If any modifications are made to these color specifications,
+they must be in their initial device-dependent format upon return.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When called, the element in the color specification array specified
+by the index argument contains the color specification outside the
+screen's color gamut encountered by the calling routine.
+In addition, this color specification can be assumed to be in
+<function>XcmsCIEXYZ</function>.
+Upon return, this color specification must be in
+<function>XcmsCIEXYZ</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When called, elements from index to ncolors - 1
+in the color specification array may or may not fall within the
+screen's color gamut.
+In addition, these color specifications can be assumed to be in
+<function>XcmsCIEXYZ</function>.
+If any modifications are made to these color specifications,
+they must be in
+<function>XcmsCIEXYZ</function>
+upon return.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The color specifications passed to the gamut compression procedure
+have already been adjusted to the Screen White Point.
+This means that at this point the color specification's white point
+is the Screen White Point.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the gamut compression procedure uses a device-independent color space not
+initially accessible for use in the color management system, use
+<function>XcmsAddColorSpace</function>
+to ensure that it is added.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Supplied_Gamut_Compression_Procedures">
+<title>Supplied Gamut Compression Procedures</title>
+<!-- .XS -->
+<!-- (SN Supplied Gamut Compression Procedures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following equations are useful in describing gamut compression
+functions:
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
+
+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
+
+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
+
+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The gamut compression callback procedures provided by Xlib are as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XcmsCIELabClipL</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)
+in the <acronym>CIE</acronym> L*a*b* color space until the color is within the gamut.
+If the Psychometric Chroma of the color specification
+is beyond maximum for the Psychometric Hue Angle,
+then while maintaining the same Psychometric Hue Angle,
+the color will be clipped to the <acronym>CIE</acronym> L*a*b* coordinates of maximum
+Psychometric Chroma.
+See
+<function>XcmsCIELabQueryMaxC</function>.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsCIELabClipab</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing Psychometric Chroma,
+while maintaining Psychometric Hue Angle,
+until the color is within the gamut.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsCIELabClipLab</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with <acronym>CIE</acronym> L*a*b* coordinates
+that fall within the color gamut while maintaining the original
+Psychometric Hue
+Angle and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsCIELuvClipL</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)
+in the <acronym>CIE</acronym> L*u*v* color space until the color is within the gamut.
+If the Psychometric Chroma of the color specification
+is beyond maximum for the Psychometric Hue Angle,
+then, while maintaining the same Psychometric Hue Angle,
+the color will be clipped to the <acronym>CIE</acronym> L*u*v* coordinates of maximum
+Psychometric Chroma.
+See
+<function>XcmsCIELuvQueryMaxC</function>.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsCIELuvClipuv</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing
+Psychometric Chroma, while maintaining Psychometric Hue Angle,
+until the color is within the gamut.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsCIELuvClipLuv</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with <acronym>CIE</acronym> L*u*v* coordinates
+that fall within the color gamut while maintaining the original
+Psychometric Hue
+Angle and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsTekHVCClipV</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing or increasing the Value dimension
+in the TekHVC color space until the color is within the gamut.
+If Chroma of the color specification is beyond maximum for the particular Hue,
+then, while maintaining the same Hue,
+the color will be clipped to the Value and Chroma coordinates
+that represent maximum Chroma for that particular Hue.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsTekHVCClipC</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing the Chroma dimension
+in the TekHVC color space until the color is within the gamut.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsTekHVCClipVC</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with TekHVC coordinates
+that fall within the color gamut while maintaining the original Hue
+and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Prototype_White_Point_Adjustment_Procedure">
+<title>Prototype White Point Adjustment Procedure</title>
+<!-- .XS -->
+<!-- (SN Prototype White Point Adjustment Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The white point adjustment procedure interface must adhere to the following:
+</para>
+<indexterm significance="preferred"><primary>XcmsWhiteAdjustProc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef Status <function>(*XcmsWhiteAdjustProc</function>)</funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *initial_white_point</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *target_white_point</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+ <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>initial_white_point</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the initial white point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_white_point</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target white point.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_flags_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+<function>True</function>
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Supplied_White_Point_Adjustment_Procedures">
+<title>Supplied White Point Adjustment Procedures</title>
+<!-- .XS -->
+<!-- (SN Supplied White Point Adjustment Procedures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+White point adjustment procedures provided by Xlib are as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XcmsCIELabWhiteShiftColors</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This uses the <acronym>CIE</acronym> L*a*b* color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to
+<function>XcmsCIELab</function>
+using the source white point and then converts to the target specification
+format using the destination's white point.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsCIELuvWhiteShiftColors</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This uses the <acronym>CIE</acronym> L*u*v* color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to
+<function>XcmsCIELuv</function>
+using the source white point and then converts to the target specification
+format using the destination's white point.
+No client data is necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsTekHVCWhiteShiftColors</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This uses the TekHVC color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to
+<function>XcmsTekHVC</function>
+using the source white point and then converts to the target specification
+format using the destination's white point.
+An advantage of this procedure over those previously described
+is an attempt to minimize hue shift.
+No client data is necessary.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+From an implementation point of view,
+these white point adjustment procedures convert the color specifications
+to a device-independent but white-point-dependent color space
+(for example, <acronym>CIE</acronym> L*u*v*, <acronym>CIE</acronym> L*a*b*, TekHVC) using one white point
+and then converting those specifications to the target color space
+using another white point.
+In other words,
+the specification goes in the color space with one white point
+but comes out with another white point,
+resulting in a chromatic shift based on the chromatic displacement
+between the initial white point and target white point.
+The <acronym>CIE</acronym> color spaces that are assumed to be white-point-independent
+are <acronym>CIE</acronym> u'v'Y, <acronym>CIE</acronym> XYZ, and <acronym>CIE</acronym> xyY.
+When developing a custom white point adjustment procedure that uses a
+device-independent color space not initially accessible for use in the
+color management system, use
+<function>XcmsAddColorSpace</function>
+to ensure that it is added.
+</para>
+<para>
+<!-- .LP -->
+As an example,
+if the CCC specifies a white point adjustment procedure
+and if the Client White Point and Screen White Point differ, the
+<function>XcmsAllocColor</function>
+function will use the white point adjustment
+procedure twice:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Once to convert to
+<function>XcmsRGB</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A second time to convert from
+<function>XcmsRGB </function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For example, assume the specification is in
+<function>XcmsCIEuvY</function>
+and the adjustment procedure is
+<function>XcmsCIELuvWhiteShiftColors</function>.
+During conversion to
+<function>XcmsRGB</function>,
+the call to
+<function>XcmsAllocColor </function>
+results in the following series of color specification conversions:
+<!-- .\" Do these need to be font coded? -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+From
+<function>XcmsCIEuvY</function>
+to
+<function>XcmsCIELuv</function>
+using the Client White Point
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+From
+<function>XcmsCIELuv</function>
+to
+<function>XcmsCIEuvY</function>
+using the Screen White Point
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+From
+<function>XcmsCIEuvY</function>
+to
+<function>XcmsCIEXYZ</function>
+(<acronym>CIE</acronym> u'v'Y and XYZ are white-point-independent color spaces)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+From
+<function>XcmsCIEXYZ</function>
+to
+<function>XcmsRGBi</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+From
+<function>XcmsRGBi</function>
+to
+<function>XcmsRGB</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The resulting <acronym>RGB</acronym> specification is passed to
+<function>XAllocColor</function>,
+and the <acronym>RGB</acronym>
+specification returned by
+<function>XAllocColor</function>
+is converted back to
+<function>XcmsCIEuvY</function>
+by reversing the color conversion sequence.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Gamut_Querying_Functions">
+<title>Gamut Querying Functions</title>
+<!-- .XS -->
+<!-- (SN Gamut Querying Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes the gamut querying functions that Xlib provides.
+These functions allow the client to query the boundary
+of the screen's color gamut in terms of the <acronym>CIE</acronym> L*a*b*, <acronym>CIE</acronym> L*u*v*,
+and TekHVC color spaces.
+<indexterm><primary>Gamut querying</primary></indexterm>
+Functions are also provided that allow you to query
+the color specification of:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+White (full-intensity red, green, and blue)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Red (full-intensity red while green and blue are zero)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Green (full-intensity green while red and blue are zero)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Blue (full-intensity blue while red and green are zero)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Black (zero-intensity red, green, and blue)
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The white point associated with color specifications passed to
+and returned from these gamut querying
+functions is assumed to be the Screen White Point.
+<indexterm><primary>Screen White Point</primary></indexterm>
+This is a reasonable assumption,
+because the client is trying to query the screen's color gamut.
+</para>
+<para>
+<!-- .LP -->
+The following naming convention is used for the Max and Min functions:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+Xcms<emphasis remap='I'><color_space></emphasis>QueryMax<emphasis remap='I'><dimensions></emphasis>
+
+Xcms<emphasis remap='I'><color_space></emphasis>QueryMin<emphasis remap='I'><dimensions></emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The <dimensions> consists of a letter or letters
+that identify the dimensions of the color space
+that are not fixed.
+For example,
+<function>XcmsTekHVCQueryMaxC</function>
+is given a fixed Hue and Value for which maximum Chroma is found.
+</para>
+<sect2 id="Red_Green_and_Blue_Queries">
+<title>Red, Green, and Blue Queries</title>
+<!-- .XS -->
+<!-- (SN Red, Green, and Blue Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain the color specification for black
+(zero-intensity red, green, and blue), use
+<function>XcmsQueryBlack</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryBlack</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryBlack</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+<!-- .ds Cs zero-intensity red, green, and blue -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryBlack</function>
+function returns the color specification in the specified target format
+for zero-intensity red, green, and blue.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the color specification for blue
+(full-intensity blue while red and green are zero), use
+<function>XcmsQueryBlue</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryBlue</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryBlue</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity blue while red and green are zero -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryBlue</function>
+function returns the color specification in the specified target format
+for full-intensity blue while red and green are zero.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the color specification for green
+(full-intensity green while red and blue are zero), use
+<function>XcmsQueryGreen</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryGreen</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryGreen</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity green while red and blue are zero -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryGreen</function>
+function returns the color specification in the specified target format
+for full-intensity green while red and blue are zero.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the color specification for red
+(full-intensity red while green and blue are zero), use
+<function>XcmsQueryRed</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryRed</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryRed</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity red while green and blue are zero -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryRed</function>
+function returns the color specification in the specified target format
+for full-intensity red while green and blue are zero.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the color specification for white
+(full-intensity red, green, and blue), use
+<function>XcmsQueryWhite</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryWhite</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsQueryWhite</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity red, green, and blue -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryWhite</function>
+function returns the color specification in the specified target format
+for full-intensity red, green, and blue.
+</para>
+</sect2>
+<sect2 id="CIELab_Queries">
+<title>CIELab Queries</title>
+<!-- .XS -->
+<!-- (SN CIELab Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following equations are useful in describing the CIELab query functions:
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<literallayout class="monospaced">
+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
+
+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
+</literallayout>
+<!-- .sp -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use
+<function>XcmsCIELabQueryMaxC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELabQueryMaxC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ls maximum chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>L_star</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the lightness (L*) at which to find (Ls.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle and lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELabQueryMaxC</function>
+function, given a hue angle and lightness,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELabQueryMaxL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELabQueryMaxL</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ch maximum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc maximum lightness -->
+<!-- .ds lC hue angle and chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELabQueryMaxL</function>
+function, given a hue angle and chroma,
+finds the point in <acronym>CIE</acronym> L*a*b* color space of maximum
+lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+An
+<function>XcmsFailure</function>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle, use
+<function>XcmsCIELabQueryMaxLC</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxLC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELabQueryMaxLC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELabQueryMaxLC</function>
+function, given a hue angle,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELabQueryMinL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMinL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELabQueryMinL</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha minimum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ch minimum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc minimum lightness -->
+<!-- .ds lC hue angle and chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELabQueryMinL</function>
+function, given a hue angle and chroma,
+finds the point of minimum lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+An
+<function>XcmsFailure</function>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+</para>
+</sect2>
+<sect2 id="CIELuv_Queries">
+<title>CIELuv Queries</title>
+<!-- .XS -->
+<!-- (SN CIELuv Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following equations are useful in describing the CIELuv query functions:
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<literallayout class="monospaced">
+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
+
+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use
+<function>XcmsCIELuvQueryMaxC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELuvQueryMaxC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ls maximum chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>L_star</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the lightness (L*) at which to find (Ls.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle and lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELuvQueryMaxC</function>
+function, given a hue angle and lightness,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELuvQueryMaxL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELuvQueryMaxL</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ls maximum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>L_star</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the lightness (L*) at which to find (Ls.
+<!-- .ds Lc maximum lightness -->
+<!-- .ds lC hue angle and chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELuvQueryMaxL</function>
+function, given a hue angle and chroma,
+finds the point in <acronym>CIE</acronym> L*u*v* color space of maximum
+lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+An
+<function>XcmsFailure</function>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle, use
+<function>XcmsCIELuvQueryMaxLC</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxLC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsCIELuvQueryMaxLC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELuvQueryMaxLC</function>
+function, given a hue angle,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELuvQueryMinL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMinL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> </function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha minimum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ch minimum lightness -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc minimum lightness -->
+<!-- .ds lC hue angle and chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELuvQueryMinL</function>
+function, given a hue angle and chroma,
+finds the point of minimum lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+An
+<function>XcmsFailure</function>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+</para>
+</sect2>
+<sect2 id="TekHVC_Queries">
+<title>TekHVC Queries</title>
+<!-- .XS -->
+<!-- (SN TekHVC Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain the maximum Chroma for a given Hue and Value, use
+<function>XcmsTekHVCQueryMaxC</function>.
+</para>
+<indexterm><primary>Chroma</primary></indexterm>
+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsTekHVCQueryMaxC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> value</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the maximum Chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue (Hu.
+<!-- .ds Va maximum Chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Value in which to find the (Va.
+<!-- .ds Lc maximum Chroma along with the actual Hue and Value -->
+<!-- .ds lC maximum Chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsTekHVCQueryMaxC</function>
+function, given a Hue and Value,
+determines the maximum Chroma in TekHVC color space
+displayable by the screen.
+It returns the maximum Chroma along with the actual Hue
+and Value at which the maximum Chroma was found.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the maximum Value for a given Hue and Chroma, use
+<function>XcmsTekHVCQueryMaxV</function>.
+</para>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxV</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsTekHVCQueryMaxV</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the maximum Value -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue (Hu.
+<!-- .ds Ch maximum Value -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc maximum Value along with the Hue and Chroma -->
+<!-- .ds lC maximum Value -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsTekHVCQueryMaxV</function>
+function, given a Hue and Chroma,
+determines the maximum Value in TekHVC color space
+displayable by the screen.
+It returns the maximum Value and the actual Hue and Chroma
+at which the maximum Value was found.
+<!-- .sp -->
+</para>
+
+<para>
+<!-- .LP -->
+To obtain the maximum Chroma and Value at which it is reached
+for a specified Hue, use
+<function>XcmsTekHVCQueryMaxVC</function>.
+</para>
+<indexterm><primary>Chroma</primary></indexterm>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsTekHVCQueryMaxVC</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the maximum Chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue (Hu.
+<!-- .ds Lc color specification in \ -->
+XcmsTekHVC for the maximum Chroma, the Value at which \
+that maximum Chroma is reached, and the actual Hue
+<!-- .ds lC maximum Chroma -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsTekHVCQueryMaxVC</function>
+function, given a Hue,
+determines the maximum Chroma in TekHVC color space displayable by the screen
+and the Value at which that maximum Chroma is reached.
+It returns the maximum Chroma,
+the Value at which that maximum Chroma is reached,
+and the actual Hue for which the maximum Chroma was found.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a specified number of TekHVC specifications such that they
+contain maximum Values for a specified Hue and the
+Chroma at which the maximum Values are reached, use
+<function>XcmsTekHVCQueryMaxVSamples</function>.
+</para>
+<indexterm><primary>Chroma</primary></indexterm>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVSamples</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsTekHVCQueryMaxVSamples</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> colors_return[]</parameter></paramdef>
+ <paramdef>unsignedint<parameter> nsamples</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu for maximum Chroma/Value samples -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue (Hu.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nsamples</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of samples.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns nsamples of color specifications in XcmsTekHVC
+such that the Chroma is the maximum attainable for the Value and Hue.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsTekHVCQueryMaxVSamples</function>
+returns nsamples of maximum Value, the Chroma at which that maximum Value
+is reached, and the actual Hue for which the maximum Chroma was found.
+These sample points may then be used to plot the maximum Value/Chroma
+boundary of the screen's color gamut for the specified Hue in TekHVC color
+space.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the minimum Value for a given Hue and Chroma, use
+<function>XcmsTekHVCQueryMinV</function>.
+</para>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Value</primary><secondary>minimum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMinV</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsTekHVCQueryMinV</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+ <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the minimum Value -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue (Hu.
+<!-- .ds Va minimum Value -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Value in which to find the (Va.
+<!-- .ds Lc minimum Value and the actual Hue and Chroma -->
+<!-- .ds lC minimum Value -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsTekHVCQueryMinV</function>
+function, given a Hue and Chroma,
+determines the minimum Value in TekHVC color space displayable by the screen.
+It returns the minimum Value and the actual Hue and Chroma at which
+the minimum Value was found.
+</para>
+
+</sect2>
+</sect1>
+<sect1 id="Color_Management_Extensions">
+<title>Color Management Extensions</title>
+<!-- .XS -->
+<!-- (SN Color Management Extensions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Xlib color management facilities can be extended in two ways:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Device-Independent Color Spaces
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Device-independent color spaces that are derivable to <acronym>CIE</acronym> XYZ
+space can be added using the
+<function>XcmsAddColorSpace</function>
+function.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Color Characterization Function Set
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A Color Characterization Function Set consists of
+device-dependent color spaces and their functions that
+convert between these color spaces and the <acronym>CIE</acronym> XYZ
+color space, bundled together for a specific class of output devices.
+A function set can be added using the
+<function>XcmsAddFunctionSet</function>
+function.
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Color_Spaces">
+<title>Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The <acronym>CIE</acronym> XYZ color space serves as the hub for all
+conversions between device-independent and device-dependent color spaces.
+Therefore, the knowledge to convert an
+<function>XcmsColor</function>
+structure to and from <acronym>CIE</acronym> XYZ format is associated with each color space.
+For example, conversion from <acronym>CIE</acronym> L*u*v* to <acronym>RGB</acronym> requires the knowledge
+to convert from <acronym>CIE</acronym> L*u*v* to <acronym>CIE</acronym> XYZ and from <acronym>CIE</acronym> XYZ to <acronym>RGB</acronym>.
+This knowledge is stored as an array of functions that,
+when applied in series, will convert the
+<function>XcmsColor</function>
+structure to or from <acronym>CIE</acronym> XYZ format.
+This color specification conversion mechanism facilitates
+the addition of color spaces.
+</para>
+<para>
+<!-- .LP -->
+Of course, when converting between only device-independent color spaces
+or only device-dependent color spaces,
+shortcuts are taken whenever possible.
+For example, conversion from TekHVC to <acronym>CIE</acronym> L*u*v* is performed
+by intermediate conversion to <acronym>CIE</acronym> u*v*Y and then to <acronym>CIE</acronym> L*u*v*,
+thus bypassing conversion between <acronym>CIE</acronym> u*v*Y and <acronym>CIE</acronym> XYZ.
+</para>
+</sect2>
+<sect2 id="Adding_Device_Independent_Color_Spaces">
+<title>Adding Device-Independent Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Adding Device-Independent Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To add a device-independent color space, use
+<function>XcmsAddColorSpace</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsAddColorSpace</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsAddColorSpace</function></funcdef>
+ <paramdef>XcmsColorSpace<parameter> *color_space</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_space</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the device-independent color space to add.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAddColorSpace</function>
+function makes a device-independent color space (actually an
+<function>XcmsColorSpace</function>
+structure) accessible by the color management system.
+Because format values for unregistered color spaces are assigned at run time,
+they should be treated as private to the client.
+If references to an unregistered color space must be made
+outside the client (for example, storing color specifications
+in a file using the unregistered color space),
+then reference should be made by color space prefix
+(see
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+</para>
+<para>
+<!-- .LP -->
+If the
+<function>XcmsColorSpace</function>
+structure is already accessible in the color management system,
+<function>XcmsAddColorSpace</function>
+returns
+<function>XcmsSuccess</function>.
+</para>
+<para>
+<!-- .LP -->
+Note that added
+<function>XcmsColorSpaces</function>
+must be retained for reference by Xlib.
+</para>
+</sect2>
+<sect2 id="Querying_Color_Space_Format_and_Prefix">
+<title>Querying Color Space Format and Prefix</title>
+<!-- .XS -->
+<!-- (SN Querying Color Space Format and Prefix -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain the format associated with the color space
+associated with a specified color string prefix, use
+<function>XcmsFormatOfPrefix</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsFormatOfPrefix</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XcmsColorFormat<function>XcmsFormatOfPrefix</function></funcdef>
+ <paramdef>char<parameter> *prefix</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prefix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string that contains the color space prefix.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsFormatOfPrefix</function>
+function returns the format for the specified color space prefix
+(for example, the string ``CIEXYZ'').
+The prefix is case-insensitive.
+If the color space is not accessible in the color management system,
+<function>XcmsFormatOfPrefix</function>
+returns
+<function>XcmsUndefinedFormat</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the color string prefix associated with the color space
+specified by a color format, use
+<function>XcmsPrefixOfFormat</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsPrefixOfFormat</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char <function>*XcmsPrefixOfFormat</function></funcdef>
+ <paramdef>XcmsColorFormat<parameter> format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color specification format.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsPrefixOfFormat</function>
+function returns the string prefix associated with the color specification
+encoding specified by the format argument.
+Otherwise, if no encoding is found, it returns NULL.
+The returned string must be treated as read-only.
+</para>
+</sect2>
+<sect2 id="Creating_Additional_Color_Spaces">
+<title>Creating Additional Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Creating Additional Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Color space specific information necessary
+for color space conversion and color string parsing is stored in an
+<function>XcmsColorSpace</function>
+structure.
+Therefore, a new structure containing this information is required
+for each additional color space.
+In the case of device-independent color spaces,
+a handle to this new structure (that is, by means of a global variable)
+is usually made accessible to the client program for use with the
+<function>XcmsAddColorSpace</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+If a new
+<function>XcmsColorSpace</function>
+structure specifies a color space not registered with the X Consortium,
+they should be treated as private to the client
+because format values for unregistered color spaces are assigned at run time.
+If references to an unregistered color space must be made outside the
+client (for example, storing color specifications in a file using the
+unregistered color space), then reference should be made by color space prefix
+(see
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef (*XcmsConversionProc)();
+typedef XcmsConversionProc *XcmsFuncListPtr;
+ /* A NULL terminated list of function pointers*/
+
+typedef struct _XcmsColorSpace {
+ char *prefix;
+ XcmsColorFormat format;
+ XcmsParseStringProc parseString;
+ XcmsFuncListPtr to_CIEXYZ;
+ XcmsFuncListPtr from_CIEXYZ;
+ int inverse_flag;
+} XcmsColorSpace;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The prefix member specifies the prefix that indicates a color string
+is in this color space's string format.
+For example, the strings ``ciexyz'' or ``CIEXYZ'' for <acronym>CIE</acronym> XYZ,
+and ``rgb'' or ``<acronym>RGB</acronym>'' for <acronym>RGB</acronym>.
+The prefix is case insensitive.
+The format member specifies the color specification format.
+Formats for unregistered color spaces are assigned at run time.
+The parseString member contains a pointer to the function
+that can parse a color string into an
+<function>XcmsColor</function>
+structure.
+This function returns an integer (int): nonzero if it succeeded
+and zero otherwise.
+The to_CIEXYZ and from_CIEXYZ members contain pointers,
+each to a NULL terminated list of function pointers.
+When the list of functions is executed in series,
+it will convert the color specified in an
+<function>XcmsColor</function>
+structure from/to the current color space format to/from the <acronym>CIE</acronym> XYZ format.
+Each function returns an integer (int): nonzero if it succeeded
+and zero otherwise.
+The white point to be associated with the colors is specified
+explicitly, even though white points can be found in the CCC.
+The inverse_flag member, if nonzero, specifies that for each function listed
+in to_CIEXYZ,
+its inverse function can be found in from_CIEXYZ such that:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+Given: n = number of functions in each list
+
+for each i, such that 0 <= i < n
+ from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+This allows Xlib to use the shortest conversion path,
+thus bypassing <acronym>CIE</acronym> XYZ if possible (for example, TekHVC to <acronym>CIE</acronym> L*u*v*).
+</para>
+</sect2>
+<sect2 id="Parse_String_Callback">
+<title>Parse String Callback</title>
+<!-- .XS -->
+<!-- (SN Parse String Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The callback in the
+<function>XcmsColorSpace</function>
+structure for parsing a color string for the particular color space must
+adhere to the following software interface specification:
+</para>
+<indexterm significance="preferred"><primary>XcmsParseStringProc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsParseStringProc</function></funcdef>
+ <paramdef>char<parameter> *color_string</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color string to parse.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the color space's format.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Color_Specification_Conversion_Callback">
+<title>Color Specification Conversion Callback</title>
+<!-- .XS -->
+<!-- (SN Color Specification Conversion Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Callback functions in the
+<function>XcmsColorSpace</function>
+structure for converting a color specification between device-independent
+spaces must adhere to the
+following software interface specification:
+</para>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>ConversionProc</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *white_point</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>
+ <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>white_point</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the white point associated with color specifications.
+The pixel member should be ignored,
+and the entire structure remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+Callback functions in the
+<function>XcmsColorSpace</function>
+structure for converting a color specification to or from a device-dependent
+space must adhere to the
+following software interface specification:
+</para>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>ConversionProc</function></funcdef>
+ <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+ <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>
+ <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+ <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ccc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the CCC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colors_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ncolors</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of
+<function>XcmsColor</function>
+structures in the color-specification array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>compression_flags_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+<function>True</function>
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Conversion functions are available globally for use by other color
+spaces.
+The conversion functions provided by Xlib are:
+</para>
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Converts from</entry>
+ <entry>Converts to</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XcmsCIELabToCIEXYZ</function></entry>
+ <entry><function>XcmsCIELabFormat</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIELuvToCIEuvY</function></entry>
+ <entry><function>XcmsCIELuvFormat</function></entry>
+ <entry><function>XcmsCIEuvYFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEXYZToCIELab</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ <entry><function>XcmsCIELabFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEXYZToCIEuvY</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ <entry><function>XcmsCIEuvYFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEXYZToCIExyY</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ <entry><function>XcmsCIExyYFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEXYZToRGBi</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ <entry><function>XcmsRGBiFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEuvYToCIELuv</function></entry>
+ <entry><function>XcmsCIEuvYFormat</function></entry>
+ <entry><function>XcmsCIELabFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEuvYToCIEXYZ</function></entry>
+ <entry><function>XcmsCIEuvYFormat</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIEuvYToTekHVC</function></entry>
+ <entry><function>XcmsCIEuvYFormat</function></entry>
+ <entry><function>XcmsTekHVCFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsCIExyYToCIEXYZ</function></entry>
+ <entry><function>XcmsCIExyYFormat</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsRGBToRGBi</function></entry>
+ <entry><function>XcmsRGBFormat</function></entry>
+ <entry><function>XcmsRGBiFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsRGBiToCIEXYZ</function></entry>
+ <entry><function>XcmsRGBiFormat</function></entry>
+ <entry><function>XcmsCIEXYZFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsRGBiToRGB</function></entry>
+ <entry><function>XcmsRGBiFormat</function></entry>
+ <entry><function>XcmsRGBFormat</function></entry>
+ </row>
+ <row>
+ <entry><function>XcmsTekHVCToCIEuvY</function></entry>
+ <entry><function>XcmsTekHVCFormat</function></entry>
+ <entry><function>XcmsCIEuvYFormat</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect2>
+<sect2 id="Function_Sets">
+<title>Function Sets</title>
+<!-- .XS -->
+<!-- (SN Function Sets -->
+<!-- .XE -->
+<indexterm><primary>Function set</primary></indexterm>
+<indexterm><primary>Function set</primary><secondary>LINEAR_RGB</secondary></indexterm>
+<para>
+<!-- .LP -->
+Functions to convert between device-dependent color spaces
+and <acronym>CIE</acronym> XYZ may differ for different classes of output devices
+(for example, color versus gray monitors).
+Therefore, the notion of a Color Characterization Function Set
+has been developed.
+A function set consists of device-dependent color spaces
+and the functions that convert color specifications
+between these device-dependent color spaces and the <acronym>CIE</acronym> XYZ color space
+appropriate for a particular class of output devices.
+The function set also contains a function that reads
+color characterization data off root window properties.
+It is this characterization data that will differ between devices within
+a class of output devices.
+<indexterm><primary>Device Color Characterization</primary></indexterm>
+For details about how color characterization data is
+stored in root window properties,
+see the section on Device Color Characterization in the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+The LINEAR_RGB function set is provided by Xlib
+and will support most color monitors.
+Function sets may require data that differs
+from those needed for the LINEAR_RGB function set.
+In that case,
+its corresponding data may be stored on different root window properties.
+</para>
+</sect2>
+<sect2 id="Adding_Function_Sets">
+<title>Adding Function Sets</title>
+<!-- .XS -->
+<!-- (SN Adding Function Sets -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To add a function set, use
+<function>XcmsAddFunctionSet</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsAddFunctionSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XcmsAddFunctionSet</function></funcdef>
+ <paramdef>XcmsFunctionSet<parameter> *function_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>function_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the function set to add.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAddFunctionSet</function>
+function adds a function set to the color management system.
+If the function set uses device-dependent
+<function>XcmsColorSpace</function>
+structures not accessible in the color management system,
+<function>XcmsAddFunctionSet</function>
+adds them.
+If an added
+<function>XcmsColorSpace</function>
+structure is for a device-dependent color space not registered
+with the X Consortium,
+they should be treated as private to the client
+because format values for unregistered color spaces are assigned at run time.
+If references to an unregistered color space must be made outside the
+client (for example, storing color specifications in a file
+using the unregistered color space),
+then reference should be made by color space prefix
+(see
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+</para>
+<para>
+<!-- .LP -->
+Additional function sets should be added before any calls to other
+Xlib routines are made.
+If not, the
+<function>XcmsPerScrnInfo</function>
+member of a previously created
+<function>XcmsCCC</function>
+does not have the opportunity to initialize
+with the added function set.
+</para>
+</sect2>
+<sect2 id="Creating_Additional_Function_Sets">
+<title>Creating Additional Function Sets</title>
+<!-- .XS -->
+<!-- (SN Creating Additional Function Sets -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The creation of additional function sets should be
+required only when an output device does not conform to existing
+function sets or when additional device-dependent color spaces are necessary.
+A function set consists primarily of a collection of device-dependent
+<function>XcmsColorSpace</function>
+structures and a means to read and store a
+screen's color characterization data.
+This data is stored in an
+<function>XcmsFunctionSet</function>
+structure.
+A handle to this structure (that is, by means of global variable)
+is usually made accessible to the client program for use with
+<function>XcmsAddFunctionSet</function>.
+</para>
+<para>
+<!-- .LP -->
+If a function set uses new device-dependent
+<function>XcmsColorSpace</function>
+structures,
+they will be transparently processed into the color management system.
+Function sets can share an
+<function>XcmsColorSpace</function>
+structure for a device-dependent color space.
+In addition, multiple
+<function>XcmsColorSpace</function>
+structures are allowed for a device-dependent color space;
+however, a function set can reference only one of them.
+These
+<function>XcmsColorSpace</function>
+structures will differ in the functions to convert to and from <acronym>CIE</acronym> XYZ,
+thus tailored for the specific function set.
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XcmsFunctionSet {
+ XcmsColorSpace **DDColorSpaces;
+ XcmsScreenInitProc screenInitProc;
+ XcmsScreenFreeProc screenFreeProc;
+} XcmsFunctionSet;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The DDColorSpaces member is a pointer to a NULL terminated list
+of pointers to
+<function>XcmsColorSpace</function>
+structures for the device-dependent color spaces that are supported
+by the function set.
+The screenInitProc member is set to the callback procedure (see the following
+interface specification) that initializes the
+<function>XcmsPerScrnInfo</function>
+structure for a particular screen.
+</para>
+<para>
+<!-- .LP -->
+The screen initialization callback must adhere to the following software
+interface specification:
+<indexterm significance="preferred"><primary>XcmsScreenInitProc</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef Status <function>(*XcmsScreenInitProc</function>)</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+ <paramdef>ScmsPerScrnInfo<parameter> *screen_info</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_info</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XcmsPerScrnInfo </function>
+structure, which contains the per screen information.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The screen initialization callback in the
+<function>XcmsFunctionSet</function>
+structure fetches the color characterization data (device profile) for
+the specified screen,
+typically off properties on the
+screen's root window.
+It then initializes the specified
+<function>XcmsPerScrnInfo</function>
+structure.
+<indexterm><primary>Device profile</primary></indexterm>
+<indexterm><primary>Color Characterization Data</primary></indexterm>
+If successful, the procedure fills in the
+<function>XcmsPerScrnInfo</function>
+structure as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It sets the screenData member to the address
+of the created device profile data structure
+(contents known only by the function set).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It next sets the screenWhitePoint member.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It next sets the functionSet member to the address of the
+<function>XcmsFunctionSet</function>
+structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It then sets the state member to
+<function>XcmsInitSuccess </function>
+and finally returns
+<function>XcmsSuccess</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If unsuccessful, the procedure sets the state member to
+<function>XcmsInitFailure</function>
+and returns
+<function>XcmsFailure</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XcmsPerScrnInfo</function>
+structure contains:
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XcmsPerScrnInfo {
+ XcmsColor screenWhitePoint;
+ XPointer functionSet;
+ XPointer screenData;
+ unsigned char state;
+ char pad[3];
+} XcmsPerScrnInfo;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The screenWhitePoint member specifies the white point inherent to
+the screen.
+The functionSet member specifies the appropriate function set.
+The screenData member specifies the device profile.
+The state member is set to one of the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XcmsInitNone</function>
+indicates initialization has not been previously attempted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsInitFailure</function>
+indicates initialization has been previously attempted but failed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XcmsInitSuccess</function>
+indicates initialization has been previously attempted and succeeded.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The screen free callback must adhere to the following software
+interface specification:
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef void (*XcmsScreenFreeProc)</funcdef>
+ <paramdef>XPointer<parameter> screenData</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screenData</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This function is called to free the screenData stored in an
+<function>XcmsPerScrnInfo</function>
+structure.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH07 b/libX11/specs/libX11/CH07 deleted file mode 100644 index d6f672289..000000000 --- a/libX11/specs/libX11/CH07 +++ /dev/null @@ -1,2357 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 7\fP\s-1 - -\s+1\fBGraphics Context Functions\fP\s-1 -.sp 2 -.nr H1 7 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 7: Graphics Context Functions -.XE -A number of resources are used when performing graphics operations in X. -Most information about performing graphics (for example, foreground -color, background color, line style, and so on) is stored in -resources called graphics contexts (GCs). -.IN "Graphics context" -Most graphics operations (see chapter 8) take a -GC as an argument. -Although in theory the X protocol permits sharing of GCs between applications, -it is expected that applications will use their own -GCs when performing operations. -Sharing of GCs is highly discouraged because the library may cache GC state. -.LP -Graphics operations can be performed to either windows or pixmaps, -which collectively are called drawables. -.IN "Root" -Each drawable exists on a single screen. -A GC is created for a specific screen and drawable depth -and can only be used with drawables of matching -screen and depth. -.LP -This chapter discusses how to: -.IP \(bu 5 -Manipulate graphics context/state -.IP \(bu 5 -Use graphics context convenience functions -.NH 2 -Manipulating Graphics Context/State -.XS -\*(SN Manipulating Graphics Context/State -.XE -.LP -Most attributes of graphics operations are stored in GCs. -These include line width, line style, plane mask, foreground, background, -tile, stipple, clipping region, end style, join style, and so on. -Graphics operations (for example, drawing lines) use these values -to determine the actual drawing operation. -Extensions to X may add additional components to GCs. -The contents of a GC are private to Xlib. -.LP -Xlib implements a write-back cache for all elements of a GC that are not -resource IDs to allow Xlib to implement the transparent coalescing of changes -to GCs. -For example, -a call to -.PN XSetForeground -of a GC followed by a call to -.PN XSetLineAttributes -results in only a single-change GC protocol request to the server. -GCs are neither expected nor encouraged to be shared between client -applications, so this write-back caching should present no problems. -Applications cannot share GCs without external synchronization. -Therefore, -sharing GCs between applications is highly discouraged. -.LP -To set an attribute of a GC, -set the appropriate member of the -.PN XGCValues -structure and OR in the corresponding value bitmask in your subsequent calls to -.PN XCreateGC . -The symbols for the value mask bits and the -.PN XGCValues -structure are: -.sM -.LP -/* GC attribute value mask bits */ -.TS -lw(.5i) lw(2.5i) lw(.75i). -#define\ - T{ -.PN GCFunction -T} T{ -(1L<<0) -T} -#define\ - T{ -.PN GCPlaneMask -T} T{ -(1L<<1) -T} -#define\ - T{ -.PN GCForeground -T} T{ -(1L<<2) -T} -#define\ - T{ -.PN GCBackground -T} T{ -(1L<<3) -T} -#define\ - T{ -.PN GCLineWidth -T} T{ -(1L<<4) -T} -#define\ - T{ -.PN GCLineStyle -T} T{ -(1L<<5) -T} -#define\ - T{ -.PN GCCapStyle -T} T{ -(1L<<6) -T} -#define\ - T{ -.PN GCJoinStyle -T} T{ -(1L<<7) -T} -#define\ - T{ -.PN GCFillStyle -T} T{ -(1L<<8) -T} -#define\ - T{ -.PN GCFillRule -T} T{ -(1L<<9) -T} -#define\ - T{ -.PN GCTile -T} T{ -(1L<<10) -T} -#define\ - T{ -.PN GCStipple -T} T{ -(1L<<11) -T} -#define\ - T{ -.PN GCTileStipXOrigin -T} T{ -(1L<<12) -T} -#define\ - T{ -.PN GCTileStipYOrigin -T} T{ -(1L<<13) -T} -#define\ - T{ -.PN GCFont -T} T{ -(1L<<14) -T} -#define\ - T{ -.PN GCSubwindowMode -T} T{ -(1L<<15) -T} -#define\ - T{ -.PN GCGraphicsExposures -T} T{ -(1L<<16) -T} -#define\ - T{ -.PN GCClipXOrigin -T} T{ -(1L<<17) -T} -#define\ - T{ -.PN GCClipYOrigin -T} T{ -(1L<<18) -T} -#define\ - T{ -.PN GCClipMask -T} T{ -(1L<<19) -T} -#define\ - T{ -.PN GCDashOffset -T} T{ -(1L<<20) -T} -#define\ - T{ -.PN GCDashList -T} T{ -(1L<<21) -T} -#define\ - T{ -.PN GCArcMode -T} T{ -(1L<<22) -T} -.TE -.IN "XGCValues" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -/* Values */ - -typedef struct { - int function; /* logical operation */ - unsigned long plane_mask; /* plane mask */ - unsigned long foreground; /* foreground pixel */ - unsigned long background; /* background pixel */ - int line_width; /* line width (in pixels) */ - int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ - int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ - int join_style; /* JoinMiter, JoinRound, JoinBevel */ - int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/ - int fill_rule; /* EvenOddRule, WindingRule */ - int arc_mode; /* ArcChord, ArcPieSlice */ - Pixmap tile; /* tile pixmap for tiling operations */ - Pixmap stipple; /* stipple 1 plane pixmap for stippling */ - int ts_x_origin; /* offset for tile or stipple operations */ - int ts_y_origin; - Font font; /* default text font for text operations */ - int subwindow_mode; /* ClipByChildren, IncludeInferiors */ - Bool graphics_exposures; /* boolean, should exposures be generated */ - int clip_x_origin; /* origin for clipping */ - int clip_y_origin; - Pixmap clip_mask; /* bitmap clipping; other calls for rects */ - int dash_offset; /* patterned/dashed line information */ - char dashes; -} XGCValues; -.De -.LP -.eM -The default GC values are: -.TS H -l l. -_ -.sp 6p -.B -Component Default -.sp 6p -_ -.sp 6p -.TH -.R -T{ -function -T} T{ -.PN GXcopy -T} -plane_mask All ones -foreground 0 -background 1 -line_width 0 -T{ -line_style -T} T{ -.PN LineSolid -T} -T{ -cap_style -T} T{ -.PN CapButt -T} -T{ -join_style -T} T{ -.PN JoinMiter -T} -T{ -fill_style -T} T{ -.PN FillSolid -T} -T{ -fill_rule -T} T{ -.PN EvenOddRule -T} -T{ -arc_mode -T} T{ -.PN ArcPieSlice -T} -tile Pixmap of unspecified size filled with foreground pixel - (that is, client specified pixel if any, else 0) - (subsequent changes to foreground do not affect this pixmap) -stipple Pixmap of unspecified size filled with ones -ts_x_origin 0 -ts_y_origin 0 -font <implementation dependent> -T{ -subwindow_mode -T} T{ -.PN ClipByChildren -T} -T{ -graphics_exposures -T} T{ -.PN True -T} -clip_x_origin 0 -clip_y_origin 0 -T{ -clip_mask -T} T{ -.PN None -T} -dash_offset 0 -dashes 4 (that is, the list [4, 4]) -.sp 6p -_ -.TE -.LP -Note that foreground and background are not set to any values likely -to be useful in a window. -.LP -.IN "Display Functions" "" "@DEF@" -.IN "Source" "" "@DEF@" -.IN "Destination" "" "@DEF@" -The function attributes of a GC are used when you update a section of -a drawable (the destination) with bits from somewhere else (the source). -The function in a GC defines how the new destination bits are to be -computed from the source bits and the old destination bits. -.PN GXcopy -is typically the most useful because it will work on a color display, -but special applications may use other functions, -particularly in concert with particular planes of a color display. -The 16 GC functions, defined in -.hN X11/X.h , -are: -.\" are listed in Table 5-1 along with the -.\"the associated hexadecimal code -.\" and operation. -.\".CP T 1 -.\"Display Functions -.TS H -lw(1.5i) cw(.5i) lw(2i). -_ -.sp 6p -.B -Function Name Value Operation -.sp 6p -_ -.sp 6p -.TH -T{ -.PN GXclear -T} T{ -0x0 -T} T{ -0 -T} -T{ -.PN GXand -T} T{ -0x1 -T} T{ -src AND dst -T} -T{ -.PN GXandReverse -T} T{ -0x2 -T} T{ -src AND NOT dst -T} -T{ -.PN GXcopy -T} T{ -0x3 -T} T{ -src -T} -T{ -.PN GXandInverted -T} T{ -0x4 -T} T{ -(NOT src) AND dst -T} -T{ -.PN GXnoop -T} T{ -0x5 -T} T{ -dst -T} -T{ -.PN GXxor -T} T{ -0x6 -T} T{ -src XOR dst -T} -T{ -.PN GXor -T} T{ -0x7 -T} T{ -src OR dst -T} -T{ -.PN GXnor -T} T{ -0x8 -T} T{ -(NOT src) AND (NOT dst) -T} -T{ -.PN GXequiv -T} T{ -0x9 -T} T{ -(NOT src) XOR dst -T} -T{ -.PN GXinvert -T} T{ -0xa -T} T{ -NOT dst -T} -T{ -.PN GXorReverse -T} T{ -0xb -T} T{ -src OR (NOT dst) -T} -T{ -.PN GXcopyInverted -T} T{ -0xc -T} T{ -NOT src -T} -T{ -.PN GXorInverted -T} T{ -0xd -T} T{ -(NOT src) OR dst -T} -T{ -.PN GXnand -T} T{ -0xe -T} T{ -(NOT src) OR (NOT dst) -T} -T{ -.PN GXset -T} T{ -0xf -T} T{ -1 -T} -.sp 6p -_ -.TE -.LP -Many graphics operations depend on either pixel values or planes in a GC. -.IN "Pixel value" -The planes attribute is of type long, and it specifies which planes of the -destination are to be modified, one bit per plane. -.IN "Plane" "mask" -A monochrome display has only one plane and -will be the least significant bit of the word. -As planes are added to the display hardware, they will occupy more -significant bits in the plane mask. -.LP -In graphics operations, given a source and destination pixel, -the result is computed bitwise on corresponding bits of the pixels. -That is, a Boolean operation is performed in each bit plane. -The plane_mask restricts the operation to a subset of planes. -A macro constant -.PN AllPlanes -can be used to refer to all planes of the screen simultaneously. -The result is computed by the following: -.LP -.Ds -((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) -.De -.LP -Range checking is not performed on the values for foreground, -background, or plane_mask. -They are simply truncated to the appropriate -number of bits. -The line-width is measured in pixels and either can be greater than or equal to -one (wide line) or can be the special value zero (thin line). -.LP -Wide lines are drawn centered on the path described by the graphics request. -Unless otherwise specified by the join-style or cap-style, -the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and -width w is a rectangle with vertices at the following real coordinates: -.LP -.Ds -.TA .5i 2.5i -.ta .5i 2.5i -[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], -[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] -.De -.LP -Here sn is the sine of the angle of the line, -and cs is the cosine of the angle of the line. -A pixel is part of the line and so is drawn -if the center of the pixel is fully inside the bounding box -(which is viewed as having infinitely thin edges). -If the center of the pixel is exactly on the bounding box, -it is part of the line if and only if the interior is immediately to its right -(x increasing direction). -Pixels with centers on a horizontal edge are a special case and are part of -the line if and only if the interior or the boundary is immediately below -(y increasing direction) and the interior or the boundary is immediately -to the right (x increasing direction). -.LP -Thin lines (zero line-width) are one-pixel-wide lines drawn using an -unspecified, device-dependent algorithm. -There are only two constraints on this algorithm. -.IP 1. 5 -If a line is drawn unclipped from [x1,y1] to [x2,y2] and -if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], -a point [x,y] is touched by drawing the first line -if and only if the point [x+dx,y+dy] is touched by drawing the second line. -.IP 2. 5 -The effective set of points comprising a line cannot be affected by clipping. -That is, a point is touched in a clipped line if and only if the point -lies inside the clipping region and the point would be touched -by the line when drawn unclipped. -.LP -A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels -as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style -and join-style. -It is recommended that this property be true for thin lines, -but this is not required. -A line-width of zero may differ from a line-width of one in which pixels are -drawn. -This permits the use of many manufacturers' line drawing hardware, -which may run many times faster than the more precisely specified -wide lines. -.LP -In general, -drawing a thin line will be faster than drawing a wide line of width one. -However, because of their different drawing algorithms, -thin lines may not mix well aesthetically with wide lines. -If it is desirable to obtain precise and uniform results across all displays, -a client should always use a line-width of one rather than a line-width of zero. -.LP -The line-style defines which sections of a line are drawn: -.TS -lw(1.3i) lw(4.5i). -T{ -.PN LineSolid -T} T{ -The full path of the line is drawn. -T} -.sp 6p -T{ -.PN LineDoubleDash -T} T{ -The full path of the line is drawn, -but the even dashes are filled differently -from the odd dashes (see fill-style) with -.PN CapButt -style used where even and odd dashes meet. -T} -.sp 6p -T{ -.PN LineOnOffDash -T} T{ -Only the even dashes are drawn, -and cap-style applies to -all internal ends of the individual dashes, -except -.PN CapNotLast -is treated as -.PN CapButt . -T} -.TE -.LP -The cap-style defines how the endpoints of a path are drawn: -.IN "Graphics context" "path" -.TS -lw(1.3i) lw(4.5i). -T{ -.PN CapNotLast -T} T{ -This is equivalent to -.PN CapButt -except that for a line-width of zero the final endpoint is not drawn. -T} -.sp 6p -T{ -.PN CapButt -T} T{ -The line is square at the endpoint (perpendicular to the slope of the line) -with no projection beyond. -T} -.sp 6p -T{ -.PN CapRound -T} T{ -The line has a circular arc with the diameter equal to the line-width, -centered on the endpoint. -(This is equivalent to -.PN CapButt -for line-width of zero). -T} -.sp 6p -T{ -.PN CapProjecting -T} T{ -The line is square at the end, but the path continues beyond the endpoint -for a distance equal to half the line-width. -(This is equivalent to -.PN CapButt -for line-width of zero). -T} -.TE -.LP -The join-style defines how corners are drawn for wide lines: -.TS -lw(1.3i) lw(4.5i). -T{ -.PN JoinMiter -T} T{ -The outer edges of two lines extend to meet at an angle. -However, if the angle is less than 11 degrees, -then a -.PN JoinBevel -join-style is used instead. -T} -.sp 6p -T{ -.PN JoinRound -T} T{ -The corner is a circular arc with the diameter equal to the line-width, -centered on the joinpoint. -T} -.sp 6p -T{ -.PN JoinBevel -T} T{ -The corner has -.PN CapButt -endpoint styles with the triangular notch filled. -T} -.TE -.LP -For a line with coincident endpoints (x1=x2, y1=y2), -when the cap-style is applied to both endpoints, -the semantics depends on the line-width and the cap-style: -.TS -lw(1.3i) lw(.5i) lw(4i). -T{ -.PN CapNotLast -T} T{ -thin -T} T{ -The results are device dependent, -but the desired effect is that nothing is drawn. -T} -.sp 6p -T{ -.PN CapButt -T} T{ -thin -T} T{ -The results are device dependent, -but the desired effect is that a single pixel is drawn. -T} -.sp 6p -T{ -.PN CapRound -T} T{ -thin -T} T{ -The results are the same as for -.PN CapButt /thin. -T} -.sp 6p -T{ -.PN CapProjecting -T} T{ -thin -T} T{ -The results are the same as for -.PN CapButt /thin. -T} -.sp 6p -T{ -.PN CapButt -T} T{ -wide -T} T{ -Nothing is drawn. -T} -.sp 6p -T{ -.PN CapRound -T} T{ -wide -T} T{ -The closed path is a circle, centered at the endpoint, and -with the diameter equal to the line-width. -T} -.sp 6p -T{ -.PN CapProjecting -T} T{ -wide -T} T{ -The closed path is a square, aligned with the coordinate axes, centered at the -endpoint, and with the sides equal to the line-width. -T} -.TE -.LP -For a line with coincident endpoints (x1=x2, y1=y2), -when the join-style is applied at one or both endpoints, -the effect is as if the line was removed from the overall path. -However, if the total path consists of or is reduced to a single point joined -with itself, the effect is the same as when the cap-style is applied at both -endpoints. -.LP -The tile/stipple represents an infinite two-dimensional plane, -with the tile/stipple replicated in all dimensions. -When that plane is superimposed on the drawable -for use in a graphics operation, the upper-left corner -of some instance of the tile/stipple is at the coordinates within -the drawable specified by the tile/stipple origin. -The tile/stipple and clip origins are interpreted relative to the -origin of whatever destination drawable is specified in a graphics -request. -The tile pixmap must have the same root and depth as the GC, -or a -.PN BadMatch -error results. -The stipple pixmap must have depth one and must have the same root as the -GC, or a -.PN BadMatch -error results. -For stipple operations where the fill-style is -.PN FillStippled -but not -.PN FillOpaqueStippled , -the stipple pattern is tiled in a -single plane and acts as an additional clip mask to be ANDed with the clip-mask. -Although some sizes may be faster to use than others, -any size pixmap can be used for tiling or stippling. -.LP -The fill-style defines the contents of the source for line, text, and -fill requests. -For all text and fill requests (for example, -.PN XDrawText , -.PN XDrawText16 , -.PN XFillRectangle , -.PN XFillPolygon , -and -.PN XFillArc ); -for line requests -with line-style -.PN LineSolid -(for example, -.PN XDrawLine , -.PN XDrawSegments , -.PN XDrawRectangle , -.PN XDrawArc ); -and for the even dashes for line requests with line-style -.PN LineOnOffDash -or -.PN LineDoubleDash , -the following apply: -.TS -lw(1.8i) lw(4i). -T{ -.PN FillSolid -T} T{ -Foreground -T} -.sp 6p -T{ -.PN FillTiled -T} T{ -Tile -T} -.sp 6p -T{ -.PN FillOpaqueStippled -T} T{ -A tile with the same width and height as stipple, -but with background everywhere stipple has a zero -and with foreground everywhere stipple has a one -T} -.sp 6p -T{ -.PN FillStippled -T} T{ -Foreground masked by stipple -T} -.TE -.LP -When drawing lines with line-style -.PN LineDoubleDash , -the odd dashes are controlled by the fill-style in the following manner: -.TS -lw(1.8i) lw(4i). -T{ -.PN FillSolid -T} T{ -Background -T} -.sp 6p -T{ -.PN FillTiled -T} T{ -Same as for even dashes -T} -.sp 6p -T{ -.PN FillOpaqueStippled -T} T{ -Same as for even dashes -T} -.sp 6p -T{ -.PN FillStippled -T} T{ -Background masked by stipple -T} -.TE -.LP -Storing a pixmap in a GC might or might not result in a copy -being made. -If the pixmap is later used as the destination for a graphics request, -the change might or might not be reflected in the GC. -If the pixmap is used simultaneously in a graphics request both as -a destination and as a tile or stipple, -the results are undefined. -.LP -For optimum performance, -you should draw as much as possible with the same GC -(without changing its components). -The costs of changing GC components relative to using different GCs -depend on the display hardware and the server implementation. -It is quite likely that some amount of GC information will be -cached in display hardware and that such hardware can only cache a small number -of GCs. -.LP -The dashes value is actually a simplified form of the -more general patterns that can be set with -.PN XSetDashes . -Specifying a -value of N is equivalent to specifying the two-element list [N, N] in -.PN XSetDashes . -The value must be nonzero, -or a -.PN BadValue -error results. -.LP -The clip-mask restricts writes to the destination drawable. -If the clip-mask is set to a pixmap, -it must have depth one and have the same root as the GC, -or a -.PN BadMatch -error results. -If clip-mask is set to -.PN None , -the pixels are always drawn regardless of the clip origin. -The clip-mask also can be set by calling the -.PN XSetClipRectangles -or -.PN XSetRegion -functions. -Only pixels where the clip-mask has a bit set to 1 are drawn. -Pixels are not drawn outside the area covered by the clip-mask -or where the clip-mask has a bit set to 0. -The clip-mask affects all graphics requests. -The clip-mask does not clip sources. -The clip-mask origin is interpreted relative to the origin of whatever -destination drawable is specified in a graphics request. -.LP -You can set the subwindow-mode to -.PN ClipByChildren -or -.PN IncludeInferiors . -For -.PN ClipByChildren , -both source and destination windows are -additionally clipped by all viewable -.PN InputOutput -children. -For -.PN IncludeInferiors , -neither source nor destination window is clipped by inferiors. -This will result in including subwindow contents in the source -and drawing through subwindow boundaries of the destination. -The use of -.PN IncludeInferiors -on a window of one depth with mapped -inferiors of differing depth is not illegal, but the semantics are -undefined by the core protocol. -.LP -The fill-rule defines what pixels are inside (drawn) for -paths given in -.PN XFillPolygon -requests and can be set to -.PN EvenOddRule -or -.PN WindingRule . -For -.PN EvenOddRule , -a point is inside if -an infinite ray with the point as origin crosses the path an odd number -of times. -For -.PN WindingRule , -a point is inside if an infinite ray with the -point as origin crosses an unequal number of clockwise and -counterclockwise directed path segments. -A clockwise directed path segment is one that crosses the ray from left to -right as observed from the point. -A counterclockwise segment is one that crosses the ray from right to left -as observed from the point. -The case where a directed line segment is coincident with the ray is -uninteresting because you can simply choose a different ray that is not -coincident with a segment. -.LP -For both -.PN EvenOddRule -and -.PN WindingRule , -a point is infinitely small, -and the path is an infinitely thin line. -A pixel is inside if the center point of the pixel is inside -and the center point is not on the boundary. -If the center point is on the boundary, -the pixel is inside if and only if the polygon interior is immediately to -its right (x increasing direction). -Pixels with centers on a horizontal edge are a special case -and are inside if and only if the polygon interior is immediately below -(y increasing direction). -.LP -The arc-mode controls filling in the -.PN XFillArcs -function and can be set to -.PN ArcPieSlice -or -.PN ArcChord . -For -.PN ArcPieSlice , -the arcs are pie-slice filled. -For -.PN ArcChord , -the arcs are chord filled. -.LP -The graphics-exposure flag controls -.PN GraphicsExpose -event generation -for -.PN XCopyArea -and -.PN XCopyPlane -requests (and any similar requests defined by extensions). -.LP -.sp -To create a new GC that is usable on a given screen with a -depth of drawable, use -.PN XCreateGC . -.IN "Graphics context" "initializing" -.IN "XCreateGC" "" "@DEF@" -.sM -.FD 0 -GC XCreateGC\^(\^\fIdisplay\fP, \fId\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - unsigned long \fIvaluemask\fP\^; -.br - XGCValues *\^\fIvalues\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.ds Vm set using the information in the specified values structure -.IP \fIvaluemask\fP 1i -Specifies which components in the GC are to be \*(Vm. -This argument is the bitwise inclusive OR of zero or more of the valid -GC component mask bits. -.IP \fIvalues\fP 1i -Specifies any values as specified by the valuemask. -.LP -.eM -The -.PN XCreateGC -function creates a graphics context and returns a GC. -The GC can be used with any destination drawable having the same root -and depth as the specified drawable. -Use with other drawables results in a -.PN BadMatch -error. -.LP -.PN XCreateGC -can generate -.PN BadAlloc , -.PN BadDrawable , -.PN BadFont , -.PN BadMatch , -.PN BadPixmap , -and -.PN BadValue -errors. -.LP -.sp -To copy components from a source GC to a destination GC, use -.PN XCopyGC . -.IN "XCopyGC" "" "@DEF@" -.sM -.FD 0 -XCopyGC\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIvaluemask\fP\^, \fIdest\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIsrc\fP\^, \fIdest\fP\^; -.br - unsigned long \fIvaluemask\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsrc\fP 1i -Specifies the components of the source GC. -.ds Vm copied to the destination GC -.IP \fIvaluemask\fP 1i -Specifies which components in the GC are to be \*(Vm. -This argument is the bitwise inclusive OR of zero or more of the valid -GC component mask bits. -.IP \fIdest\fP 1i -Specifies the destination GC. -.LP -.eM -The -.PN XCopyGC -function copies the specified components from the source GC -to the destination GC. -The source and destination GCs must have the same root and depth, -or a -.PN BadMatch -error results. -The valuemask specifies which component to copy, as for -.PN XCreateGC . -.LP -.PN XCopyGC -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadMatch -errors. -.LP -.sp -To change the components in a given GC, use -.PN XChangeGC . -.IN "XChangeGC" "" "@DEF@" -.sM -.FD 0 -XChangeGC\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned long \fIvaluemask\fP\^; -.br - XGCValues *\^\fIvalues\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Vm changed using information in the specified values structure -.IP \fIvaluemask\fP 1i -Specifies which components in the GC are to be \*(Vm. -This argument is the bitwise inclusive OR of zero or more of the valid -GC component mask bits. -.IP \fIvalues\fP 1i -Specifies any values as specified by the valuemask. -.LP -.eM -The -.PN XChangeGC -function changes the components specified by valuemask for -the specified GC. -The values argument contains the values to be set. -The values and restrictions are the same as for -.PN XCreateGC . -Changing the clip-mask overrides any previous -.PN XSetClipRectangles -request on the context. -Changing the dash-offset or dash-list -overrides any previous -.PN XSetDashes -request on the context. -The order in which components are verified and altered is server dependent. -If an error is generated, a subset of the components may have been altered. -.LP -.PN XChangeGC -can generate -.PN BadAlloc , -.PN BadFont , -.PN BadGC , -.PN BadMatch , -.PN BadPixmap , -and -.PN BadValue -errors. -.LP -.sp -To obtain components of a given GC, use -.PN XGetGCValues . -.IN "XGetGCValues" "" "@DEF@" -.sM -.FD 0 -Status XGetGCValues\^(\^\fIdisplay\fP, \fIgc\fP, \fIvaluemask\fP, \ -\fIvalues_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned long \fIvaluemask\fP\^; -.br - XGCValues *\fIvalues_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Vm returned in the values_return argument -.IP \fIvaluemask\fP 1i -Specifies which components in the GC are to be \*(Vm. -This argument is the bitwise inclusive OR of zero or more of the valid -GC component mask bits. -.IP \fIvalues_return\fP 1i -Returns the GC values in the specified -.PN XGCValues -structure. -.LP -.eM -The -.PN XGetGCValues -function returns the components specified by valuemask for the specified GC. -If the valuemask contains a valid set of GC mask bits -.Pn ( GCFunction , -.PN GCPlaneMask , -.PN GCForeground , -.PN GCBackground , -.PN GCLineWidth , -.PN GCLineStyle , -.PN GCCapStyle , -.PN GCJoinStyle , -.PN GCFillStyle , -.PN GCFillRule , -.PN GCTile , -.PN GCStipple , -.PN GCTileStipXOrigin , -.PN GCTileStipYOrigin , -.PN GCFont , -.PN GCSubwindowMode , -.PN GCGraphicsExposures , -.PN GCClipXOrigin , -.PN GCCLipYOrigin , -.PN GCDashOffset , -or -.PN GCArcMode ) -and no error occurs, -.PN XGetGCValues -sets the requested components in values_return and returns a nonzero status. -Otherwise, it returns a zero status. -Note that the clip-mask and dash-list (represented by the -.PN GCClipMask -and -.PN GCDashList -bits, respectively, in the valuemask) -cannot be requested. -Also note that an invalid resource ID (with one or more of the three -most significant bits set to 1) will be returned for -.PN GCFont , -.PN GCTile , -and -.PN GCStipple -if the component has never been explicitly set by the client. -.LP -.sp -To free a given GC, use -.PN XFreeGC . -.IN "XFreeGC" "" "@DEF@" -.sM -.FD 0 -XFreeGC\^(\^\fIdisplay\fP, \fIgc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.LP -.eM -The -.PN XFreeGC -function destroys the specified GC as well as all the associated storage. -.LP -.PN XFreeGC -can generate a -.PN BadGC -error. -.LP -.sp -To obtain the -.PN GContext -resource ID for a given GC, use -.PN XGContextFromGC . -.IN "XGContextFromGC" "" "@DEF@" -.sM -.FD 0 -GContext XGContextFromGC\^(\^\fIgc\fP\^) -.br - GC \fIgc\fP\^; -.FN -.ds Gc for which you want the resource ID -.IP \fIgc\fP 1i -Specifies the GC \*(Gc. -.LP -.eM -.sp -Xlib usually defers sending changes to the components of a GC to the server -until a graphics function is actually called with that GC. -This permits batching of component changes into a single server request. -In some circumstances, however, it may be necessary for the client -to explicitly force sending the changes to the server. -An example might be when a protocol extension uses the GC indirectly, -in such a way that the extension interface cannot know what GC will be used. -To force sending GC component changes, use -.PN XFlushGC . -.IN "XFlushGC" "" "@DEF@" -.sM -.FD 0 -void XFlushGC\^(\^\fIdisplay\fP, \fIgc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.LP -.eM -.NH 2 -Using Graphics Context Convenience Routines -.XS -\*(SN Using Graphics Context Convenience Routines -.XE -.LP -This section discusses how to set the: -.IP \(bu 5 -Foreground, background, plane mask, or function components -.IP \(bu 5 -Line attributes and dashes components -.IP \(bu 5 -Fill style and fill rule components -.IP \(bu 5 -Fill tile and stipple components -.IP \(bu 5 -Font component -.IP \(bu 5 -Clip region component -.IP \(bu 5 -Arc mode, subwindow mode, and graphics exposure components -.NH 3 -Setting the Foreground, Background, Function, or Plane Mask -.XS -\*(SN Setting the Foreground, Background, Function, or Plane Mask -.XE -.LP -To set the foreground, background, plane mask, and function components -for a given GC, use -.PN XSetState . -.IN "XSetState" "" "@DEF@" -.sM -.FD 0 -XSetState\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^, \fIbackground\fP\^, \fIfunction\fP\^, \fIplane_mask\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned long \fIforeground\fP\^, \fIbackground\fP\^; -.br - int \fIfunction\fP\^; -.br - unsigned long \fIplane_mask\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIforeground\fP 1i -Specifies the foreground you want to set for the specified GC. -.IP \fIbackground\fP 1i -Specifies the background you want to set for the specified GC. -.IP \fIfunction\fP 1i -Specifies the function you want to set for the specified GC. -.IP \fIplane_mask\fP 1i -Specifies the plane mask. -.\" *** JIM: NEED MORE INFO FOR THIS. *** -.LP -.eM -.PN XSetState -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To set the foreground of a given GC, use -.PN XSetForeground . -.IN "XSetForeground" "" "@DEF@" -.sM -.FD 0 -XSetForeground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned long \fIforeground\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIforeground\fP 1i -Specifies the foreground you want to set for the specified GC. -.LP -.eM -.PN XSetForeground -can generate -.PN BadAlloc -and -.PN BadGC -errors. -.LP -.sp -To set the background of a given GC, use -.PN XSetBackground . -.IN "XSetBackground" "" "@DEF@" -.sM -.FD 0 -XSetBackground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIbackground\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned long \fIbackground\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIbackground\fP 1i -Specifies the background you want to set for the specified GC. -.LP -.eM -.PN XSetBackground -can generate -.PN BadAlloc -and -.PN BadGC -errors. -.LP -.sp -To set the display function in a given GC, use -.PN XSetFunction . -.IN "XSetFunction" "" "@DEF@" -.sM -.FD 0 -XSetFunction\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfunction\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIfunction\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIfunction\fP 1i -Specifies the function you want to set for the specified GC. -.LP -.eM -.PN XSetFunction -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To set the plane mask of a given GC, use -.PN XSetPlaneMask . -.IN "XSetPlaneMask" "" "@DEF@" -.sM -.FD 0 -XSetPlaneMask\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIplane_mask\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned long \fIplane_mask\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIplane_mask\fP 1i -Specifies the plane mask. -.\" *** JIM: NEED MORE INFO FOR THIS. *** -.LP -.eM -.PN XSetPlaneMask -can generate -.PN BadAlloc -and -.PN BadGC -errors. -.NH 3 -Setting the Line Attributes and Dashes -.XS -\*(SN Setting the Line Attributes and Dashes -.XE -.LP -To set the line drawing components of a given GC, use -.PN XSetLineAttributes . -.IN "XSetLineAttributes" "" "@DEF@" -.sM -.FD 0 -XSetLineAttributes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIline_width\fP\^, \fIline_style\fP\^, \fIcap_style\fP\^, \fIjoin_style\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - unsigned int \fIline_width\fP\^; -.br - int \fIline_style\fP\^; -.br - int \fIcap_style\fP\^; -.br - int \fIjoin_style\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIline_width\fP 1i -Specifies the line-width you want to set for the specified GC. -.IP \fIline_style\fP 1i -Specifies the line-style you want to set for the specified GC. -You can pass -.PN LineSolid , -.PN LineOnOffDash , -or -.PN LineDoubleDash . -.IP \fIcap_style\fP 1i -Specifies the line-style and cap-style you want to set for the specified GC. -You can pass -.PN CapNotLast , -.PN CapButt , -.PN CapRound , -or -.PN CapProjecting . -.IP \fIjoin_style\fP 1i -Specifies the line join-style you want to set for the specified GC. -You can pass -.PN JoinMiter , -.PN JoinRound , -or -.PN JoinBevel . -.LP -.eM -.PN XSetLineAttributes -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To set the dash-offset and dash-list for dashed line styles of a given GC, use -.PN XSetDashes . -.IN "XSetDashes" "" "@DEF@" -.sM -.FD 0 -XSetDashes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIdash_offset\fP\^, \fIdash_list\fP\^, \fIn\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIdash_offset\fP\^; -.br - char \fIdash_list\fP[]\^; -.br - int \fIn\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIdash_offset\fP 1i -Specifies the phase of the pattern for the dashed line-style you want to set -for the specified GC. -.IP \fIdash_list\fP 1i -Specifies the dash-list for the dashed line-style -you want to set for the specified GC. -.IP \fIn\fP 1i -Specifies the number of elements in dash_list. -.LP -.eM -The -.PN XSetDashes -function sets the dash-offset and dash-list attributes for dashed line styles -in the specified GC. -There must be at least one element in the specified dash_list, -or a -.PN BadValue -error results. -The initial and alternating elements (second, fourth, and so on) -of the dash_list are the even dashes, and -the others are the odd dashes. -Each element specifies a dash length in pixels. -All of the elements must be nonzero, -or a -.PN BadValue -error results. -Specifying an odd-length list is equivalent to specifying the same list -concatenated with itself to produce an even-length list. -.LP -The dash-offset defines the phase of the pattern, -specifying how many pixels into the dash-list the pattern -should actually begin in any single graphics request. -Dashing is continuous through path elements combined with a join-style -but is reset to the dash-offset between each sequence of joined lines. -.LP -The unit of measure for dashes is the same for the ordinary coordinate system. -Ideally, a dash length is measured along the slope of the line, but implementations -are only required to match this ideal for horizontal and vertical lines. -Failing the ideal semantics, it is suggested that the length be measured along the -major axis of the line. -The major axis is defined as the x axis for lines drawn at an angle of between -\-45 and +45 degrees or between 135 and 225 degrees from the x axis. -For all other lines, the major axis is the y axis. -.LP -.PN XSetDashes -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.NH 3 -Setting the Fill Style and Fill Rule -.XS -\*(SN Setting the Fill Style and Fill Rule -.XE -.LP -To set the fill-style of a given GC, use -.PN XSetFillStyle . -.IN "XSetFillStyle" "" "@DEF@" -.sM -.FD 0 -XSetFillStyle\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_style\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIfill_style\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIfill_style\fP 1i -Specifies the fill-style you want to set for the specified GC. -You can pass -.PN FillSolid , -.PN FillTiled , -.PN FillStippled , -or -.PN FillOpaqueStippled . -.LP -.eM -.PN XSetFillStyle -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To set the fill-rule of a given GC, use -.PN XSetFillRule . -.IN "XSetFillRule" "" "@DEF@" -.sM -.FD 0 -XSetFillRule\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_rule\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIfill_rule\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIfill_rule\fP 1i -Specifies the fill-rule you want to set for the specified GC. -You can pass -.PN EvenOddRule -or -.PN WindingRule . -.LP -.eM -.PN XSetFillRule -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.NH 3 -Setting the Fill Tile and Stipple -.XS -\*(SN Setting the Fill Tile and Stipple -.XE -.LP -Some displays have hardware support for tiling or -stippling with patterns of specific sizes. -Tiling and stippling operations that restrict themselves to those specific -sizes run much faster than such operations with arbitrary size patterns. -Xlib provides functions that you can use to determine the best size, -tile, or stipple for the display -as well as to set the tile or stipple shape and the tile or stipple origin. -.LP -.sp -To obtain the best size of a tile, stipple, or cursor, use -.PN XQueryBestSize . -.IN "XQueryBestSize" "" "@DEF@" -.sM -.FD 0 -Status XQueryBestSize\^(\^\fIdisplay\fP, \fIclass\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIclass\fP\^; -.br - Drawable \fIwhich_screen\fP\^; -.br - unsigned int \fIwidth\fP, \fIheight\fP\^; -.br - unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIclass\fP 1i -Specifies the class that you are interested in. -You can pass -.PN TileShape , -.PN CursorShape , -or -.PN StippleShape . -.IP \fIwhich_screen\fP 1i -Specifies any drawable on the screen. -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height of the object best supported -by the display hardware. -.LP -.eM -The -.PN XQueryBestSize -function returns the best or closest size to the specified size. -For -.PN CursorShape , -this is the largest size that can be fully displayed on the screen specified by -which_screen. -For -.PN TileShape , -this is the size that can be tiled fastest. -For -.PN StippleShape , -this is the size that can be stippled fastest. -For -.PN CursorShape , -the drawable indicates the desired screen. -For -.PN TileShape -and -.PN StippleShape , -the drawable indicates the screen and possibly the window class and depth. -An -.PN InputOnly -window cannot be used as the drawable for -.PN TileShape -or -.PN StippleShape , -or a -.PN BadMatch -error results. -.LP -.PN XQueryBestSize -can generate -.PN BadDrawable , -.PN BadMatch , -and -.PN BadValue -errors. -.LP -.sp -To obtain the best fill tile shape, use -.PN XQueryBestTile . -.IN "XQueryBestTile" "" "@DEF@" -.sM -.FD 0 -Status XQueryBestTile\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fIwhich_screen\fP\^; -.br - unsigned int \fIwidth\fP, \fIheight\fP\^; -.br - unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIwhich_screen\fP 1i -Specifies any drawable on the screen. -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height of the object best supported -by the display hardware. -.LP -.eM -The -.PN XQueryBestTile -function returns the best or closest size, that is, the size that can be -tiled fastest on the screen specified by which_screen. -The drawable indicates the screen and possibly the window class and depth. -If an -.PN InputOnly -window is used as the drawable, a -.PN BadMatch -error results. -.LP -.PN XQueryBestTile -can generate -.PN BadDrawable -and -.PN BadMatch -errors. -.LP -.sp -To obtain the best stipple shape, use -.PN XQueryBestStipple . -.IN "XQueryBestStipple" "" "@DEF@" -.sM -.FD 0 -Status XQueryBestStipple\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fIwhich_screen\fP\^; -.br - unsigned int \fIwidth\fP, \fIheight\fP\^; -.br - unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIwhich_screen\fP 1i -Specifies any drawable on the screen. -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height of the object best supported -by the display hardware. -.LP -.eM -The -.PN XQueryBestStipple -function returns the best or closest size, that is, the size that can be -stippled fastest on the screen specified by which_screen. -The drawable indicates the screen and possibly the window class and depth. -If an -.PN InputOnly -window is used as the drawable, a -.PN BadMatch -error results. -.LP -.PN XQueryBestStipple -can generate -.PN BadDrawable -and -.PN BadMatch -errors. -.LP -.sp -To set the fill tile of a given GC, use -.PN XSetTile . -.IN "XSetTile" "" "@DEF@" -.sM -.FD 0 -XSetTile\^(\^\fIdisplay\fP, \fIgc\fP\^, \fItile\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - Pixmap \fItile\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fItile\fP 1i -Specifies the fill tile you want to set for the specified GC. -.LP -.eM -The tile and GC must have the same depth, -or a -.PN BadMatch -error results. -.LP -.PN XSetTile -can generate -.PN BadAlloc , -.PN BadGC , -.PN BadMatch , -and -.PN BadPixmap -errors. -.LP -.sp -To set the stipple of a given GC, use -.PN XSetStipple . -.IN "XSetStipple" "" "@DEF@" -.sM -.FD 0 -XSetStipple\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIstipple\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - Pixmap \fIstipple\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIstipple\fP 1i -Specifies the stipple you want to set for the specified GC. -.LP -.eM -The stipple must have a depth of one, -or a -.PN BadMatch -error results. -.LP -.PN XSetStipple -can generate -.PN BadAlloc , -.PN BadGC , -.PN BadMatch , -and -.PN BadPixmap -errors. -.LP -.sp -To set the tile or stipple origin of a given GC, use -.PN XSetTSOrigin . -.IN "XSetTSOrigin" "" "@DEF@" -.sM -.FD 0 -XSetTSOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIts_x_origin\fP\^, \fIts_y_origin\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIts_x_origin\fP\^, \fIts_y_origin\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIts_x_origin\fP 1i -.br -.ns -.IP \fIts_y_origin\fP 1i -Specify the x and y coordinates of the tile and stipple origin. -.LP -.eM -When graphics requests call for tiling or stippling, -the parent's origin will be interpreted relative to whatever destination -drawable is specified in the graphics request. -.LP -.PN XSetTSOrigin -can generate -.PN BadAlloc -and -.PN BadGC -errors. -.NH 3 -Setting the Current Font -.XS -\*(SN Setting the Current Font -.XE -.LP -To set the current font of a given GC, use -.PN XSetFont . -.IN "XSetFont" "" "@DEF@" -.sM -.FD 0 -XSetFont\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfont\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - Font \fIfont\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIfont\fP 1i -Specifies the font. -.LP -.eM -.PN XSetFont -can generate -.PN BadAlloc , -.PN BadFont , -and -.PN BadGC -errors. -.NH 3 -Setting the Clip Region -.XS -\*(SN Setting the Clip Region -.XE -.LP -Xlib provides functions that you can use to set the clip-origin -and the clip-mask or set the clip-mask to a list of rectangles. -.LP -.sp -To set the clip-origin of a given GC, use -.PN XSetClipOrigin . -.IN "XSetClipOrigin" "" "@DEF@" -.sM -.FD 0 -XSetClipOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIclip_x_origin\fP 1i -.br -.ns -.IP \fIclip_y_origin\fP 1i -Specify the x and y coordinates of the clip-mask origin. -.LP -.eM -The clip-mask origin is interpreted relative to the origin of whatever -destination drawable is specified in the graphics request. -.LP -.PN XSetClipOrigin -can generate -.PN BadAlloc -and -.PN BadGC -errors. -.LP -.sp -To set the clip-mask of a given GC to the specified pixmap, use -.PN XSetClipMask . -.IN "XSetClipMask" "" "@DEF@" -.sM -.FD 0 -XSetClipMask\^(\^\fIdisplay\fP, \fIgc\fP, \fIpixmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - Pixmap \fIpixmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIpixmap\fP 1i -Specifies the pixmap or -.PN None . -.LP -.eM -If the clip-mask is set to -.PN None , -the pixels are always drawn (regardless of the clip-origin). -.LP -.PN XSetClipMask -can generate -.PN BadAlloc , -.PN BadGC , -.PN BadMatch , -and -.PN BadPixmap -errors. -.LP -.sp -To set the clip-mask of a given GC to the specified list of rectangles, use -.PN XSetClipRectangles . -.IN "XSetClipRectangles" "" "@DEF@" -.sM -.FD 0 -XSetClipRectangles\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^, \fIrectangles\fP\^, \fIn\fP\^, \fIordering\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^; -.br - XRectangle \fIrectangles\fP[]\^; -.br - int \fIn\fP\^; -.br - int \fIordering\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIclip_x_origin\fP 1i -.br -.ns -.IP \fIclip_y_origin\fP 1i -Specify the x and y coordinates of the clip-mask origin. -.IP \fIrectangles\fP 1i -Specifies an array of rectangles that define the clip-mask. -.IP \fIn\fP 1i -Specifies the number of rectangles. -.IP \fIordering\fP 1i -Specifies the ordering relations on the rectangles. -You can pass -.PN Unsorted , -.PN YSorted , -.PN YXSorted , -or -.PN YXBanded . -.LP -.eM -The -.PN XSetClipRectangles -function changes the clip-mask in the specified GC -to the specified list of rectangles and sets the clip origin. -The output is clipped to remain contained within the -rectangles. -The clip-origin is interpreted relative to the origin of -whatever destination drawable is specified in a graphics request. -The rectangle coordinates are interpreted relative to the clip-origin. -The rectangles should be nonintersecting, or the graphics results will be -undefined. -Note that the list of rectangles can be empty, -which effectively disables output. -This is the opposite of passing -.PN None -as the clip-mask in -.PN XCreateGC , -.PN XChangeGC , -and -.PN XSetClipMask . -.LP -If known by the client, ordering relations on the rectangles can be -specified with the ordering argument. -This may provide faster operation -by the server. -If an incorrect ordering is specified, the X server may generate a -.PN BadMatch -error, but it is not required to do so. -If no error is generated, the graphics -results are undefined. -.PN Unsorted -means the rectangles are in arbitrary order. -.PN YSorted -means that the rectangles are nondecreasing in their Y origin. -.PN YXSorted -additionally constrains -.PN YSorted -order in that all -rectangles with an equal Y origin are nondecreasing in their X -origin. -.PN YXBanded -additionally constrains -.PN YXSorted -by requiring that, -for every possible Y scanline, all rectangles that include that -scanline have an identical Y origins and Y extents. -.LP -.PN XSetClipRectangles -can generate -.PN BadAlloc , -.PN BadGC , -.PN BadMatch , -and -.PN BadValue -errors. -.LP -Xlib provides a set of basic functions for performing -region arithmetic. -For information about these functions, -see section 16.5. -.NH 3 -Setting the Arc Mode, Subwindow Mode, and Graphics Exposure -.XS -\*(SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure -.XE -.LP -To set the arc mode of a given GC, use -.PN XSetArcMode . -.IN "XSetArcMode" "" "@DEF@" -.sM -.FD 0 -XSetArcMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIarc_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIarc_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIarc_mode\fP 1i -Specifies the arc mode. -You can pass -.PN ArcChord -or -.PN ArcPieSlice . -.LP -.eM -.PN XSetArcMode -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To set the subwindow mode of a given GC, use -.PN XSetSubwindowMode . -.IN "XSetSubwindowMode" "" "@DEF@" -.sM -.FD 0 -XSetSubwindowMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIsubwindow_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIsubwindow_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIsubwindow_mode\fP 1i -Specifies the subwindow mode. -You can pass -.PN ClipByChildren -or -.PN IncludeInferiors . -.LP -.eM -.PN XSetSubwindowMode -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To set the graphics-exposures flag of a given GC, use -.PN XSetGraphicsExposures . -.IN "XSetGraphicsExposures" "" "@DEF@" -.sM -.FD 0 -XSetGraphicsExposures\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIgraphics_exposures\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - Bool \fIgraphics_exposures\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIgraphics_exposures\fP 1i -Specifies a Boolean value that indicates whether you want -.PN GraphicsExpose -and -.PN NoExpose -events to be reported when calling -.PN XCopyArea -and -.PN XCopyPlane -with this GC. -.LP -.eM -.PN XSetGraphicsExposures -can generate -.PN BadAlloc , -.PN BadGC , -and -.PN BadValue -errors. -.bp diff --git a/libX11/specs/libX11/CH07.xml b/libX11/specs/libX11/CH07.xml new file mode 100644 index 000000000..6e8894080 --- /dev/null +++ b/libX11/specs/libX11/CH07.xml @@ -0,0 +1,3401 @@ +<chapter id="graphics_context_functions">
+<title>Graphics Context Functions</title>
+
+<para>
+A number of resources are used when performing graphics operations in X. Most information
+about performing graphics (for example, foreground color, background color, line style, and so
+on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter
+8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between
+applications, it is expected that applications will use their own GCs when performing operations.
+Sharing of GCs is highly discouraged because the library may cache GC state.
+</para>
+<para>
+Graphics operations can be performed to either windows or pixmaps, which collectively are
+called drawables. Each drawable exists on a single screen. A GC is created for a specific screen
+and drawable depth and can only be used with drawables of matching screen and depth.
+</para>
+<para>
+This chapter discusses how to:
+</para>
+<itemizedlist>
+ <listitem><para>Manipulate graphics context/state</para></listitem>
+ <listitem><para>Use graphics context convenience functions</para></listitem>
+</itemizedlist>
+
+<sect1 id="Manipulating_Graphics_Context_State">
+<title>Manipulating Graphics Context/State</title>
+<!-- .XS -->
+<!-- (SN Manipulating Graphics Context/State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Most attributes of graphics operations are stored in GCs.
+These include line width, line style, plane mask, foreground, background,
+tile, stipple, clipping region, end style, join style, and so on.
+Graphics operations (for example, drawing lines) use these values
+to determine the actual drawing operation.
+Extensions to X may add additional components to GCs.
+The contents of a GC are private to Xlib.
+</para>
+<para>
+<!-- .LP -->
+Xlib implements a write-back cache for all elements of a GC that are not
+resource IDs to allow Xlib to implement the transparent coalescing of changes
+to GCs.
+For example,
+a call to
+<function>XSetForeground</function>
+of a GC followed by a call to
+<function>XSetLineAttributes</function>
+results in only a single-change GC protocol request to the server.
+GCs are neither expected nor encouraged to be shared between client
+applications, so this write-back caching should present no problems.
+Applications cannot share GCs without external synchronization.
+Therefore,
+sharing GCs between applications is highly discouraged.
+</para>
+<para>
+<!-- .LP -->
+To set an attribute of a GC,
+set the appropriate member of the
+<function>XGCValues</function>
+structure and OR in the corresponding value bitmask in your subsequent calls to
+<function>XCreateGC</function>.
+The symbols for the value mask bits and the
+<function>XGCValues</function>
+structure are:
+<!-- .sM -->
+</para>
+
+
+<literallayout class="monospaced">
+/* GC attribute value mask bits */
+
+#define GCFunction (1L<<0)
+#define GCPlaneMask (1L<<1)
+#define GCForeground (1L<<2)
+#define GCBackground (1L<<3)
+#define GCLineWidth (1L<<4)
+#define GCLineStyle (1L<<5)
+#define GCCapStyle (1L<<6)
+#define GCJoinStyle (1L<<7)
+#define GCFillStyle (1L<<8)
+#define GCFillRule (1L<<9)
+#define GCTile (1L<<10)
+#define GCStipple (1L<<11)
+#define GCTileStipXOrigin (1L<<12)
+#define GCTileStipYOrigin (1L<<13)
+#define GCFont (1L<<14)
+#define GCSubwindowMode (1L<<15)
+#define GCGraphicsExposures (1L<<16)
+#define GCClipXOrigin (1L<<17)
+#define GCClipYOrigin (1L<<18)
+#define GCClipMask (1L<<19)
+#define GCDashOffset (1L<<20)
+#define GCDashList (1L<<21)
+#define GCArcMode (1L<<22)
+</literallayout>
+
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* Values */
+
+typedef struct {
+ int function; /* logical operation */
+ unsigned long plane_mask; /* plane mask */
+ unsigned long foreground; /* foreground pixel */
+ unsigned long background; /* background pixel */
+ int line_width; /* line width (in pixels) */
+ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */
+ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */
+ int join_style; /* JoinMiter, JoinRound, JoinBevel */
+ int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
+ int fill_rule; /* EvenOddRule, WindingRule */
+ int arc_mode; /* ArcChord, ArcPieSlice */
+ Pixmap tile; /* tile pixmap for tiling operations */
+ Pixmap stipple; /* stipple 1 plane pixmap for stippling */
+ int ts_x_origin; /* offset for tile or stipple operations */
+ int ts_y_origin
+ Font font; /* default text font for text operations */
+ int subwindow_mode; /* ClipByChildren, IncludeInferiors */
+ Bool graphics_exposures; /* boolean, should exposures be generated */
+ int clip_x_origin; /* origin for clipping */
+ int clip_y_origin;
+ Pixmap clip_mask; /* bitmap clipping; other calls for rects */
+ int dash_offset; /* patterned/dashed line information */
+ char dashes;
+} XGCValues;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The default GC values are:
+</para>
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Component</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>function</entry>
+ <entry><function>GXcopy</function></entry>
+ </row>
+ <row>
+ <entry>plane_mask</entry>
+ <entry>All ones</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>line_width</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>line_style</entry>
+ <entry><function>LineSolid</function></entry>
+ </row>
+ <row>
+ <entry>cap_style</entry>
+ <entry><function>CapButt</function></entry>
+ </row>
+ <row>
+ <entry>join_style</entry>
+ <entry><function>JoinMiter</function></entry>
+ </row>
+ <row>
+ <entry>fill_style</entry>
+ <entry><function>FillSolid</function></entry>
+ </row>
+ <row>
+ <entry>fill_rule</entry>
+ <entry><function>EvenOddRule</function></entry>
+ </row>
+ <row>
+ <entry>arc_mode</entry>
+ <entry><function>ArcPieSlice</function></entry>
+ </row>
+ <row>
+ <entry>tile</entry>
+ <entry>Pixmap of unspecified size filled with foreground pixel</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>(that is, client specified pixel if any, else 0)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>(subsequent changes to foreground do not affect this pixmap)</entry>
+ </row>
+ <row>
+ <entry>stipple</entry>
+ <entry>Pixmap of unspecified size filled with ones</entry>
+ </row>
+ <row>
+ <entry>ts_x_origin</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>ts_y_origin</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry><implementation dependent></entry>
+ </row>
+ <row>
+ <entry>subwindow_mode</entry>
+ <entry><function>ClipByChildren</function></entry>
+ </row>
+ <row>
+ <entry>graphics_exposures</entry>
+ <entry><function>True</function></entry>
+ </row>
+ <row>
+ <entry>clip_x_origin</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>clip_y_origin</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>clip_mask</entry>
+ <entry><function>None</function></entry>
+ </row>
+ <row>
+ <entry>dash_offset</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>dashes</entry>
+ <entry>4 (that is, the list [4, 4])</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Note that foreground and background are not set to any values likely
+to be useful in a window.
+</para>
+
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Display Functions</primary></indexterm>
+<indexterm significance="preferred"><primary>Source</primary></indexterm>
+<indexterm significance="preferred"><primary>Destination</primary></indexterm>
+The function attributes of a GC are used when you update a section of
+a drawable (the destination) with bits from somewhere else (the source).
+The function in a GC defines how the new destination bits are to be
+computed from the source bits and the old destination bits.
+<function>GXcopy</function>
+is typically the most useful because it will work on a color display,
+but special applications may use other functions,
+particularly in concert with particular planes of a color display.
+The 16 GC functions, defined in
+<!-- .hN X11/X.h , -->
+are:
+</para>
+<!-- .\" are listed in Table 5-1 along with the -->
+<!-- .\"the associated hexadecimal code -->
+<!-- .\" and operation. -->
+<!-- .\".CP T 1 -->
+<!-- .\"Display Functions -->
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Function Name</entry>
+ <entry>Value</entry>
+ <entry>Operation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>GXclear</function></entry>
+ <entry>0x0</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry><function>GXand</function></entry>
+ <entry>0x1</entry>
+ <entry>src AND dst</entry>
+ </row>
+ <row>
+ <entry><function>GXandReverse</function></entry>
+ <entry>0x2</entry>
+ <entry>src AND NOT dst</entry>
+ </row>
+ <row>
+ <entry><function>GXcopy</function></entry>
+ <entry>0x3</entry>
+ <entry>src</entry>
+ </row>
+ <row>
+ <entry><function>GXandInverted</function></entry>
+ <entry>0x4</entry>
+ <entry>(NOT src) AND dst</entry>
+ </row>
+ <row>
+ <entry><function>GXnoop</function></entry>
+ <entry>0x5</entry>
+ <entry>dst</entry>
+ </row>
+ <row>
+ <entry><function>GXxor</function></entry>
+ <entry>0x6</entry>
+ <entry>src XOR dst</entry>
+ </row>
+ <row>
+ <entry><function>GXor</function></entry>
+ <entry>0x7</entry>
+ <entry>src OR dst</entry>
+ </row>
+ <row>
+ <entry><function>GXnor</function></entry>
+ <entry>0x8</entry>
+ <entry>(NOT src) AND (NOT dst)</entry>
+ </row>
+ <row>
+ <entry><function>GXequiv</function></entry>
+ <entry>0x9</entry>
+ <entry>(NOT src) XOR dst</entry>
+ </row>
+ <row>
+ <entry><function>GXinvert</function></entry>
+ <entry>0xa</entry>
+ <entry>NOT dst</entry>
+ </row>
+ <row>
+ <entry><function>GXorReverse</function></entry>
+ <entry>0xb</entry>
+ <entry>src OR (NOT dst)</entry>
+ </row>
+ <row>
+ <entry><function>GXcopyInverted</function></entry>
+ <entry>0xc</entry>
+ <entry>NOT src</entry>
+ </row>
+ <row>
+ <entry><function>GXorInverted</function></entry>
+ <entry>0xd</entry>
+ <entry>(NOT src) OR dst</entry>
+ </row>
+ <row>
+ <entry><function>GXnand</function></entry>
+ <entry>0xe</entry>
+ <entry>(NOT src) OR (NOT dst)</entry>
+ </row>
+ <row>
+ <entry><function>GXset</function></entry>
+ <entry>0xf</entry>
+ <entry>1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Many graphics operations depend on either pixel values or planes in a GC.
+<indexterm><primary>Pixel value</primary></indexterm>
+The planes attribute is of type long, and it specifies which planes of the
+destination are to be modified, one bit per plane.
+<indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm>
+A monochrome display has only one plane and
+will be the least significant bit of the word.
+As planes are added to the display hardware, they will occupy more
+significant bits in the plane mask.
+</para>
+<para>
+<!-- .LP -->
+In graphics operations, given a source and destination pixel,
+the result is computed bitwise on corresponding bits of the pixels.
+That is, a Boolean operation is performed in each bit plane.
+The plane_mask restricts the operation to a subset of planes.
+A macro constant
+<function>AllPlanes</function>
+can be used to refer to all planes of the screen simultaneously.
+The result is computed by the following:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Range checking is not performed on the values for foreground,
+background, or plane_mask.
+They are simply truncated to the appropriate
+number of bits.
+The line-width is measured in pixels and either can be greater than or equal to
+one (wide line) or can be the special value zero (thin line).
+</para>
+<para>
+<!-- .LP -->
+Wide lines are drawn centered on the path described by the graphics request.
+Unless otherwise specified by the join-style or cap-style,
+the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
+width w is a rectangle with vertices at the following real coordinates:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
+[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Here sn is the sine of the angle of the line,
+and cs is the cosine of the angle of the line.
+A pixel is part of the line and so is drawn
+if the center of the pixel is fully inside the bounding box
+(which is viewed as having infinitely thin edges).
+If the center of the pixel is exactly on the bounding box,
+it is part of the line if and only if the interior is immediately to its right
+(x increasing direction).
+Pixels with centers on a horizontal edge are a special case and are part of
+the line if and only if the interior or the boundary is immediately below
+(y increasing direction) and the interior or the boundary is immediately
+to the right (x increasing direction).
+</para>
+<para>
+<!-- .LP -->
+Thin lines (zero line-width) are one-pixel-wide lines drawn using an
+unspecified, device-dependent algorithm.
+There are only two constraints on this algorithm.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If a line is drawn unclipped from [x1,y1] to [x2,y2] and
+if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
+a point [x,y] is touched by drawing the first line
+if and only if the point [x+dx,y+dy] is touched by drawing the second line.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The effective set of points comprising a line cannot be affected by clipping.
+That is, a point is touched in a clipped line if and only if the point
+lies inside the clipping region and the point would be touched
+by the line when drawn unclipped.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
+as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
+and join-style.
+It is recommended that this property be true for thin lines,
+but this is not required.
+A line-width of zero may differ from a line-width of one in which pixels are
+drawn.
+This permits the use of many manufacturers' line drawing hardware,
+which may run many times faster than the more precisely specified
+wide lines.
+</para>
+<para>
+<!-- .LP -->
+In general,
+drawing a thin line will be faster than drawing a wide line of width one.
+However, because of their different drawing algorithms,
+thin lines may not mix well aesthetically with wide lines.
+If it is desirable to obtain precise and uniform results across all displays,
+a client should always use a line-width of one rather than a line-width of zero.
+</para>
+<para>
+<!-- .LP -->
+The line-style defines which sections of a line are drawn:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><function>LineSolid</function></term>
+ <listitem>
+ <para>The full path of the line is drawn.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>LineDoubleDash</function></term>
+ <listitem>
+ <para>
+The full path of the line is drawn,
+but the even dashes are filled differently
+from the odd dashes (see fill-style) with <!-- xref -->
+<function>CapButt </function>
+style used where even and odd dashes meet.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>LineOnOffDash</function></term>
+ <listitem>
+ <para>
+Only the even dashes are drawn,
+and cap-style applies to
+all internal ends of the individual dashes,
+except
+<function>CapNotLast</function>
+is treated as
+<function>CapButt</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+The cap-style defines how the endpoints of a path are drawn:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><function>CapNotLast</function></term>
+ <listitem>
+ <para>
+This is equivalent to
+<function>CapButt</function>
+except that for a line-width of zero the final endpoint is not drawn.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>CapButt</function></term>
+ <listitem>
+ <para>
+The line is square at the endpoint (perpendicular to the slope of the line)
+with no projection beyond.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>CapRound</function></term>
+ <listitem>
+ <para>
+The line has a circular arc with the diameter equal to the line-width,
+centered on the endpoint.
+(This is equivalent to
+<function>CapButt </function>
+for line-width of zero).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>CapProjecting</function></term>
+ <listitem>
+ <para>
+The line is square at the end, but the path continues beyond the endpoint
+for a distance equal to half the line-width.
+(This is equivalent to
+<function>CapButt </function>
+for line-width of zero).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The join-style defines how corners are drawn for wide lines:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><function>JoinMiter</function></term>
+ <listitem>
+ <para>
+The outer edges of two lines extend to meet at an angle.
+However, if the angle is less than 11 degrees,
+then a
+<function>JoinBevel</function>
+join-style is used instead.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>JoinRound</function></term>
+ <listitem>
+ <para>
+The corner is a circular arc with the diameter equal to the line-width,
+centered on the joinpoint.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>JoinBevel</function></term>
+ <listitem>
+ <para>
+The corner has
+<function>CapButt </function>
+endpoint styles with the triangular notch filled.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+<!-- .LP -->
+For a line with coincident endpoints (x1=x2, y1=y2),
+when the cap-style is applied to both endpoints,
+the semantics depends on the line-width and the cap-style:
+</para>
+
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <tbody>
+ <row>
+ <entry><function>CapNotLast</function></entry>
+ <entry>thin</entry>
+ <entry>The results are device dependent,
+ but the desired effect is that nothing is drawn.</entry>
+ </row>
+ <row>
+ <entry><function>CapButt</function></entry>
+ <entry>thin</entry>
+ <entry>The results are device dependent,
+ but the desired effect is that a single pixel is drawn.</entry>
+ </row>
+ <row>
+ <entry><function>CapRound</function></entry>
+ <entry>thin</entry>
+ <entry>The results are the same as for
+ <function>CapButt /thin</function>.</entry>
+ </row>
+ <row>
+ <entry><function>CapProjecting</function></entry>
+ <entry>thin</entry>
+ <entry>The results are the same as for
+ <function>CapButt /thin</function>.</entry>
+ </row>
+ <row>
+ <entry><function>CapButt</function></entry>
+ <entry>wide</entry>
+ <entry>Nothing is drawn.</entry>
+ </row>
+ <row>
+ <entry><function>CapRound</function></entry>
+ <entry>wide</entry>
+ <entry>The closed path is a circle, centered at the endpoint, and
+ with the diameter equal to the line-width.</entry>
+ </row>
+ <row>
+ <entry><function>CapProjecting</function></entry>
+ <entry>wide</entry>
+ <entry>The closed path is a square, aligned with the coordinate axes, centered at the
+ endpoint, and with the sides equal to the line-width.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+For a line with coincident endpoints (x1=x2, y1=y2),
+when the join-style is applied at one or both endpoints,
+the effect is as if the line was removed from the overall path.
+However, if the total path consists of or is reduced to a single point joined
+with itself, the effect is the same as when the cap-style is applied at both
+endpoints.
+</para>
+<para>
+<!-- .LP -->
+The tile/stipple represents an infinite two-dimensional plane,
+with the tile/stipple replicated in all dimensions.
+When that plane is superimposed on the drawable
+for use in a graphics operation, the upper-left corner
+of some instance of the tile/stipple is at the coordinates within
+the drawable specified by the tile/stipple origin.
+The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics
+request.
+The tile pixmap must have the same root and depth as the GC,
+or a
+<function>BadMatch </function>
+error results.
+The stipple pixmap must have depth one and must have the same root as the
+GC, or a
+<function>BadMatch </function>
+error results.
+For stipple operations where the fill-style is
+<function>FillStippled</function>
+but not
+<function>FillOpaqueStippled</function>,
+the stipple pattern is tiled in a
+single plane and acts as an additional clip mask to be ANDed with the clip-mask.
+Although some sizes may be faster to use than others,
+any size pixmap can be used for tiling or stippling.
+</para>
+
+<para>
+<!-- .LP -->
+The fill-style defines the contents of the source for line, text, and
+fill requests.
+For all text and fill requests (for example,
+<function>XDrawText</function>,
+<function>XDrawText16</function>,
+<function>XFillRectangle</function>,
+<function>XFillPolygon</function>,
+and
+<function>XFillArc</function>);
+for line requests
+with line-style
+<function>LineSolid </function>
+(for example,
+<function>XDrawLine</function>,
+<function>XDrawSegments</function>,
+<function>XDrawRectangle</function>,
+<function>XDrawArc</function>);
+and for the even dashes for line requests with line-style
+<function>LineOnOffDash </function>
+or
+<function>LineDoubleDash</function>,
+the following apply:
+</para>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>FillSolid</function></entry>
+ <entry>Foreground</entry>
+ </row>
+ <row>
+ <entry><function>FillTiled</function></entry>
+ <entry>Tile</entry>
+ </row>
+ <row>
+ <entry><function>FillOpaqueStippled</function></entry>
+ <entry>A tile with the same width and height as stipple,
+ but with background everywhere stipple has a zero
+ and with foreground everywhere stipple has a one</entry>
+ </row>
+ <row>
+ <entry><function>FillStippled</function></entry>
+ <entry>Foreground masked by stipple</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+When drawing lines with line-style
+<function>LineDoubleDash</function>,
+the odd dashes are controlled by the fill-style in the following manner:
+</para>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>FillSolid</function></entry>
+ <entry>Background</entry>
+ </row>
+ <row>
+ <entry><function>FillTiled</function></entry>
+ <entry>Same as for even dashes</entry>
+ </row>
+ <row>
+ <entry><function>FillOpaqueStippled</function></entry>
+ <entry>Same as for even dashes</entry>
+ </row>
+ <row>
+ <entry><function>FillStippled</function></entry>
+ <entry>Background masked by stipple</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Storing a pixmap in a GC might or might not result in a copy
+being made.
+If the pixmap is later used as the destination for a graphics request,
+the change might or might not be reflected in the GC.
+If the pixmap is used simultaneously in a graphics request both as
+a destination and as a tile or stipple,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+For optimum performance,
+you should draw as much as possible with the same GC
+(without changing its components).
+The costs of changing GC components relative to using different GCs
+depend on the display hardware and the server implementation.
+It is quite likely that some amount of GC information will be
+cached in display hardware and that such hardware can only cache a small number
+of GCs.
+</para>
+<para>
+<!-- .LP -->
+The dashes value is actually a simplified form of the
+more general patterns that can be set with
+<function>XSetDashes</function>.
+Specifying a
+value of N is equivalent to specifying the two-element list [N, N] in
+<function>XSetDashes</function>.
+The value must be nonzero,
+or a
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The clip-mask restricts writes to the destination drawable.
+If the clip-mask is set to a pixmap,
+it must have depth one and have the same root as the GC,
+or a
+<function>BadMatch </function>
+error results.
+If clip-mask is set to
+<function>None</function>,
+the pixels are always drawn regardless of the clip origin.
+The clip-mask also can be set by calling the
+<function>XSetClipRectangles</function>
+or
+<function>XSetRegion</function>
+functions.
+Only pixels where the clip-mask has a bit set to 1 are drawn.
+Pixels are not drawn outside the area covered by the clip-mask
+or where the clip-mask has a bit set to 0.
+The clip-mask affects all graphics requests.
+The clip-mask does not clip sources.
+The clip-mask origin is interpreted relative to the origin of whatever
+destination drawable is specified in a graphics request.
+</para>
+<para>
+<!-- .LP -->
+You can set the subwindow-mode to
+<function>ClipByChildren</function>
+or
+<function>IncludeInferiors</function>.
+For
+<function>ClipByChildren</function>,
+both source and destination windows are
+additionally clipped by all viewable
+<function>InputOutput</function>
+children.
+For
+<function>IncludeInferiors</function>,
+neither source nor destination window is clipped by inferiors.
+This will result in including subwindow contents in the source
+and drawing through subwindow boundaries of the destination.
+The use of
+<function>IncludeInferiors </function>
+on a window of one depth with mapped
+inferiors of differing depth is not illegal, but the semantics are
+undefined by the core protocol.
+</para>
+<para>
+<!-- .LP -->
+The fill-rule defines what pixels are inside (drawn) for
+paths given in
+<function>XFillPolygon </function>
+requests and can be set to
+<function>EvenOddRule </function>
+or
+<function>WindingRule</function>.
+For
+<function>EvenOddRule</function>,
+a point is inside if
+an infinite ray with the point as origin crosses the path an odd number
+of times.
+For
+<function>WindingRule</function>,
+a point is inside if an infinite ray with the
+point as origin crosses an unequal number of clockwise and
+counterclockwise directed path segments.
+A clockwise directed path segment is one that crosses the ray from left to
+right as observed from the point.
+A counterclockwise segment is one that crosses the ray from right to left
+as observed from the point.
+The case where a directed line segment is coincident with the ray is
+uninteresting because you can simply choose a different ray that is not
+coincident with a segment.
+</para>
+<para>
+<!-- .LP -->
+For both
+<function>EvenOddRule</function>
+and
+<function>WindingRule</function>,
+a point is infinitely small,
+and the path is an infinitely thin line.
+A pixel is inside if the center point of the pixel is inside
+and the center point is not on the boundary.
+If the center point is on the boundary,
+the pixel is inside if and only if the polygon interior is immediately to
+its right (x increasing direction).
+Pixels with centers on a horizontal edge are a special case
+and are inside if and only if the polygon interior is immediately below
+(y increasing direction).
+</para>
+<para>
+<!-- .LP -->
+The arc-mode controls filling in the
+<function>XFillArcs</function>
+function and can be set to
+<function>ArcPieSlice</function>
+or
+<function>ArcChord</function>.
+For
+<function>ArcPieSlice</function>,
+the arcs are pie-slice filled.
+For
+<function>ArcChord</function>,
+the arcs are chord filled.
+</para>
+<para>
+<!-- .LP -->
+The graphics-exposure flag controls
+<function>GraphicsExpose </function>
+event generation
+for
+<function>XCopyArea </function>
+and
+<function>XCopyPlane</function>
+requests (and any similar requests defined by extensions).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a new GC that is usable on a given screen with a
+depth of drawable, use
+<function>XCreateGC</function>.
+<indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XCreateGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC<function> XCreateGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+ <paramdef>XGCValues<parameter> *\^values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+<!-- .ds Vm set using the information in the specified values structure -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>valuemask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which components in the GC are to be (Vm.
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any values as specified by the valuemask.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateGC</function>
+function creates a graphics context and returns a GC.
+The GC can be used with any destination drawable having the same root
+and depth as the specified drawable.
+Use with other drawables results in a
+<function>BadMatch</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateGC</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadDrawable</function>,
+<function>BadFont</function>,
+<function>BadMatch</function>,
+<function>BadPixmap</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To copy components from a source GC to a destination GC, use
+<function>XCopyGC</function>.
+<indexterm significance="preferred"><primary>XCopyGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XCopyGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GCsrc,<parameter> dest</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the components of the source GC.
+<!-- .ds Vm copied to the destination GC -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>valuemask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which components in the GC are to be (Vm.
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyGC</function>
+function copies the specified components from the source GC
+to the destination GC.
+The source and destination GCs must have the same root and depth,
+or a
+<function>BadMatch</function>
+error results.
+The valuemask specifies which component to copy, as for
+<function>XCreateGC</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyGC</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the components in a given GC, use
+<function>XChangeGC</function>.
+<indexterm significance="preferred"><primary>XChangeGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+ <paramdef>XGCValues<parameter> *\^values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Vm changed using information in the specified values structure -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>valuemask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which components in the GC are to be (Vm.
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any values as specified by the valuemask.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeGC</function>
+function changes the components specified by valuemask for
+the specified GC.
+The values argument contains the values to be set.
+The values and restrictions are the same as for
+<function>XCreateGC</function>.
+Changing the clip-mask overrides any previous
+<function>XSetClipRectangles</function>
+request on the context.
+Changing the dash-offset or dash-list
+overrides any previous
+<function>XSetDashes</function>
+request on the context.
+The order in which components are verified and altered is server dependent.
+If an error is generated, a subset of the components may have been altered.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeGC</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadFont</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+<function>BadPixmap</function>,
+and
+<function>BadValue</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain components of a given GC, use
+<function>XGetGCValues</function>.
+<indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetGCValues</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+ <paramdef>XGCValues<parameter> *values_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Vm returned in the values_return argument -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>valuemask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which components in the GC are to be (Vm.
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the GC values in the specified
+<function>XGCValues </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetGCValues</function>
+function returns the components specified by valuemask for the specified GC.
+If the valuemask contains a valid set of GC mask bits
+(<function>GCFunction</function>,
+<function>GCPlaneMask</function>,
+<function>GCForeground</function>,
+<function>GCBackground</function>,
+<function>GCLineWidth</function>,
+<function>GCLineStyle</function>,
+<function>GCCapStyle</function>,
+<function>GCJoinStyle</function>,
+<function>GCFillStyle</function>,
+<function>GCFillRule</function>,
+<function>GCTile</function>,
+<function>GCStipple</function>,
+<function>GCTileStipXOrigin</function>,
+<function>GCTileStipYOrigin</function>,
+<function>GCFont</function>,
+<function>GCSubwindowMode</function>,
+<function>GCGraphicsExposures</function>,
+<function>GCClipXOrigin</function>,
+<function>GCCLipYOrigin</function>,
+<function>GCDashOffset</function>,
+or
+<function>GCArcMode</function>)
+and no error occurs,
+<function>XGetGCValues</function>
+sets the requested components in values_return and returns a nonzero status.
+Otherwise, it returns a zero status.
+Note that the clip-mask and dash-list (represented by the
+<function>GCClipMask</function>
+and
+<function>GCDashList</function>
+bits, respectively, in the valuemask)
+cannot be requested.
+Also note that an invalid resource ID (with one or more of the three
+most significant bits set to 1) will be returned for
+<function>GCFont</function>,
+<function>GCTile</function>,
+and
+<function>GCStipple</function>
+if the component has never been explicitly set by the client.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a given GC, use
+<function>XFreeGC</function>.
+<indexterm significance="preferred"><primary>XFreeGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeGC</function>
+function destroys the specified GC as well as all the associated storage.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeGC</function>
+can generate a
+<function>BadGC </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the
+<function>GContext </function>
+resource ID for a given GC, use
+<function>XGContextFromGC</function>.
+<indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GContext<function> XGContextFromGC</function></funcdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Gc for which you want the resource ID -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC (Gc.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+Xlib usually defers sending changes to the components of a GC to the server
+until a graphics function is actually called with that GC.
+This permits batching of component changes into a single server request.
+In some circumstances, however, it may be necessary for the client
+to explicitly force sending the changes to the server.
+An example might be when a protocol extension uses the GC indirectly,
+in such a way that the extension interface cannot know what GC will be used.
+To force sending GC component changes, use
+<function>XFlushGC</function>.
+<indexterm significance="preferred"><primary>XFlushGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XFlushGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect1>
+<sect1 id="Using_Graphics_Context_Convenience_Routines">
+<title>Using Graphics Context Convenience Routines</title>
+<!-- .XS -->
+<!-- (SN Using Graphics Context Convenience Routines -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to set the:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Foreground, background, plane mask, or function components
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Line attributes and dashes components
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Fill style and fill rule components
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Fill tile and stipple components
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Font component
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Clip region component
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Arc mode, subwindow mode, and graphics exposure components
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask">
+<title>Setting the Foreground, Background, Function, or Plane Mask</title>
+<!-- .XS -->
+<!-- (SN Setting the Foreground, Background, Function, or Plane Mask -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the foreground, background, plane mask, and function components
+for a given GC, use
+<function>XSetState</function>.
+<indexterm significance="preferred"><primary>XSetState</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetState</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef>
+ <paramdef>int<parameter> function</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>foreground</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the foreground you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the background you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>function</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the function you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>plane_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetState</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the foreground of a given GC, use
+<function>XSetForeground</function>.
+<indexterm significance="preferred"><primary>XSetForeground</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetForeground</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> foreground</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>foreground</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the foreground you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetForeground</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadGC </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the background of a given GC, use
+<function>XSetBackground</function>.
+<indexterm significance="preferred"><primary>XSetBackground</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetBackground</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> background</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>background</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the background you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetBackground</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadGC </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the display function in a given GC, use
+<function>XSetFunction</function>.
+<indexterm significance="preferred"><primary>XSetFunction</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetFunction</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>int<parameter> function</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>function</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the function you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFunction</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the plane mask of a given GC, use
+<function>XSetPlaneMask</function>.
+<indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetPlaneMask</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>plane_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetPlaneMask</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadGC </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Line_Attributes_and_Dashes">
+<title>Setting the Line Attributes and Dashes</title>
+<!-- .XS -->
+<!-- (SN Setting the Line Attributes and Dashes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the line drawing components of a given GC, use
+<function>XSetLineAttributes</function>.
+<indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetLineAttributes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>unsignedint<parameter> line_width</parameter></paramdef>
+ <paramdef>int<parameter> line_style</parameter></paramdef>
+ <paramdef>int<parameter> cap_style</parameter></paramdef>
+ <paramdef>int<parameter> join_style</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>line_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the line-width you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>line_style</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the line-style you want to set for the specified GC.
+You can pass
+<function>LineSolid</function>,
+<function>LineOnOffDash</function>,
+or
+<function>LineDoubleDash</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cap_style</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the line-style and cap-style you want to set for the specified GC.
+You can pass
+<function>CapNotLast</function>,
+<function>CapButt</function>,
+<function>CapRound</function>,
+or
+<function>CapProjecting</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>join_style</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the line join-style you want to set for the specified GC.
+You can pass
+<function>JoinMiter</function>,
+<function>JoinRound</function>,
+or
+<function>JoinBevel</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetLineAttributes</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the dash-offset and dash-list for dashed line styles of a given GC, use
+<function>XSetDashes</function>.
+<indexterm significance="preferred"><primary>XSetDashes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetDashes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>int<parameter> dash_offset</parameter></paramdef>
+ <paramdef>char<parameter> dash_list[]\^</parameter></paramdef>
+ <paramdef>int<parameter> n</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dash_offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the phase of the pattern for the dashed line-style you want to set
+for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dash_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the dash-list for the dashed line-style
+you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>n</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements in dash_list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetDashes</function>
+function sets the dash-offset and dash-list attributes for dashed line styles
+in the specified GC.
+There must be at least one element in the specified dash_list,
+or a
+<function>BadValue</function>
+error results.
+The initial and alternating elements (second, fourth, and so on)
+of the dash_list are the even dashes, and
+the others are the odd dashes.
+Each element specifies a dash length in pixels.
+All of the elements must be nonzero,
+or a
+<function>BadValue</function>
+error results.
+Specifying an odd-length list is equivalent to specifying the same list
+concatenated with itself to produce an even-length list.
+</para>
+<para>
+<!-- .LP -->
+The dash-offset defines the phase of the pattern,
+specifying how many pixels into the dash-list the pattern
+should actually begin in any single graphics request.
+Dashing is continuous through path elements combined with a join-style
+but is reset to the dash-offset between each sequence of joined lines.
+</para>
+<para>
+<!-- .LP -->
+The unit of measure for dashes is the same for the ordinary coordinate system.
+Ideally, a dash length is measured along the slope of the line, but implementations
+are only required to match this ideal for horizontal and vertical lines.
+Failing the ideal semantics, it is suggested that the length be measured along the
+major axis of the line.
+The major axis is defined as the x axis for lines drawn at an angle of between
+\-45 and +45 degrees or between 135 and 225 degrees from the x axis.
+For all other lines, the major axis is the y axis.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetDashes</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Fill_Style_and_Fill_Rule_">
+<title>Setting the Fill Style and Fill Rule </title>
+<!-- .XS -->
+<!-- (SN Setting the Fill Style and Fill Rule -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the fill-style of a given GC, use
+<function>XSetFillStyle</function>.
+<indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetFillStyle</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>int<parameter> fill_style</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fill_style</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fill-style you want to set for the specified GC.
+You can pass
+<function>FillSolid</function>,
+<function>FillTiled</function>,
+<function>FillStippled</function>,
+or
+<function>FillOpaqueStippled</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFillStyle</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the fill-rule of a given GC, use
+<function>XSetFillRule</function>.
+<indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetFillRule</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>int<parameter> fill_rule</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fill_rule</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fill-rule you want to set for the specified GC.
+You can pass
+<function>EvenOddRule</function>
+or
+<function>WindingRule</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFillRule</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Fill_Tile_and_Stipple_">
+<title>Setting the Fill Tile and Stipple </title>
+<!-- .XS -->
+<!-- (SN Setting the Fill Tile and Stipple -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some displays have hardware support for tiling or
+stippling with patterns of specific sizes.
+Tiling and stippling operations that restrict themselves to those specific
+sizes run much faster than such operations with arbitrary size patterns.
+Xlib provides functions that you can use to determine the best size,
+tile, or stipple for the display
+as well as to set the tile or stipple shape and the tile or stipple origin.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the best size of a tile, stipple, or cursor, use
+<function>XQueryBestSize</function>.
+<indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XQueryBestSize</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> class</parameter></paramdef>
+ <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class that you are interested in.
+You can pass
+<function>TileShape</function>,
+<function>CursorShape</function>,
+or
+<function>StippleShape</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>which_screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any drawable on the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height of the object best supported
+by the display hardware.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryBestSize</function>
+function returns the best or closest size to the specified size.
+For
+<function>CursorShape</function>,
+this is the largest size that can be fully displayed on the screen specified by
+which_screen.
+For
+<function>TileShape</function>,
+this is the size that can be tiled fastest.
+For
+<function>StippleShape</function>,
+this is the size that can be stippled fastest.
+For
+<function>CursorShape</function>,
+the drawable indicates the desired screen.
+For
+<function>TileShape </function>
+and
+<function>StippleShape</function>,
+the drawable indicates the screen and possibly the window class and depth.
+An
+<function>InputOnly </function>
+window cannot be used as the drawable for
+<function>TileShape</function>
+or
+<function>StippleShape</function>,
+or a
+<function>BadMatch </function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestSize</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the best fill tile shape, use
+<function>XQueryBestTile</function>.
+<indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XQueryBestTile</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>which_screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any drawable on the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height of the object best supported
+by the display hardware.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryBestTile</function>
+function returns the best or closest size, that is, the size that can be
+tiled fastest on the screen specified by which_screen.
+The drawable indicates the screen and possibly the window class and depth.
+If an
+<function>InputOnly </function>
+window is used as the drawable, a
+<function>BadMatch </function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestTile</function>
+can generate
+<function>BadDrawable</function>
+and
+<function>BadMatch </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the best stipple shape, use
+<function>XQueryBestStipple</function>.
+<indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XQueryBestStipple</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>which_screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any drawable on the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height of the object best supported
+by the display hardware.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryBestStipple</function>
+function returns the best or closest size, that is, the size that can be
+stippled fastest on the screen specified by which_screen.
+The drawable indicates the screen and possibly the window class and depth.
+If an
+<function>InputOnly</function>
+window is used as the drawable, a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestStipple</function>
+can generate
+<function>BadDrawable</function>
+and
+<function>BadMatch </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the fill tile of a given GC, use
+<function>XSetTile</function>.
+<indexterm significance="preferred"><primary>XSetTile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetTile</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Pixmap<parameter> tile</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>tile</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fill tile you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The tile and GC must have the same depth,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTile</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadPixmap </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the stipple of a given GC, use
+<function>XSetStipple</function>.
+<indexterm significance="preferred"><primary>XSetStipple</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetStipple</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Pixmap<parameter> stipple</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stipple</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the stipple you want to set for the specified GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The stipple must have a depth of one,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetStipple</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadPixmap </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the tile or stipple origin of a given GC, use
+<function>XSetTSOrigin</function>.
+<indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetTSOrigin</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intts_x_origin,<parameter> ts_y_origin</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ts_x_origin</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ts_y_origin</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates of the tile and stipple origin.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When graphics requests call for tiling or stippling,
+the parent's origin will be interpreted relative to whatever destination
+drawable is specified in the graphics request.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTSOrigin</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadGC </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Current_Font_">
+<title>Setting the Current Font </title>
+<!-- .XS -->
+<!-- (SN Setting the Current Font -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the current font of a given GC, use
+<function>XSetFont</function>.
+<indexterm significance="preferred"><primary>XSetFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Font<parameter> font</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFont</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadFont</function>,
+and
+<function>BadGC </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Clip_Region">
+<title>Setting the Clip Region</title>
+<!-- .XS -->
+<!-- (SN Setting the Clip Region -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set the clip-origin
+and the clip-mask or set the clip-mask to a list of rectangles.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-origin of a given GC, use
+<function>XSetClipOrigin</function>.
+<indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetClipOrigin</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>clip_x_origin</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>clip_y_origin</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates of the clip-mask origin.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The clip-mask origin is interpreted relative to the origin of whatever
+destination drawable is specified in the graphics request.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClipOrigin</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadGC </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-mask of a given GC to the specified pixmap, use
+<function>XSetClipMask</function>.
+<indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetClipMask</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pixmap or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the clip-mask is set to
+<function>None</function>,
+the pixels are always drawn (regardless of the clip-origin).
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClipMask</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadPixmap </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-mask of a given GC to the specified list of rectangles, use
+<function>XSetClipRectangles</function>.
+<indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetClipRectangles</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
+ <paramdef>XRectangle<parameter> rectangles[]\^</parameter></paramdef>
+ <paramdef>int<parameter> n</parameter></paramdef>
+ <paramdef>int<parameter> ordering</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>clip_x_origin</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>clip_y_origin</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates of the clip-mask origin.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rectangles</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of rectangles that define the clip-mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>n</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of rectangles.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ordering</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the ordering relations on the rectangles.
+You can pass
+<function>Unsorted</function>,
+<function>YSorted</function>,
+<function>YXSorted</function>,
+or
+<function>YXBanded</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetClipRectangles</function>
+function changes the clip-mask in the specified GC
+to the specified list of rectangles and sets the clip origin.
+The output is clipped to remain contained within the
+rectangles.
+The clip-origin is interpreted relative to the origin of
+whatever destination drawable is specified in a graphics request.
+The rectangle coordinates are interpreted relative to the clip-origin.
+The rectangles should be nonintersecting, or the graphics results will be
+undefined.
+Note that the list of rectangles can be empty,
+which effectively disables output.
+This is the opposite of passing
+<function>None</function>
+as the clip-mask in
+<function>XCreateGC</function>,
+<function>XChangeGC</function>,
+and
+<function>XSetClipMask</function>.
+</para>
+<para>
+<!-- .LP -->
+If known by the client, ordering relations on the rectangles can be
+specified with the ordering argument.
+This may provide faster operation
+by the server.
+If an incorrect ordering is specified, the X server may generate a
+<function>BadMatch</function>
+error, but it is not required to do so.
+If no error is generated, the graphics
+results are undefined.
+<function>Unsorted </function>
+means the rectangles are in arbitrary order.
+<function>YSorted </function>
+means that the rectangles are nondecreasing in their Y origin.
+<function>YXSorted </function>
+additionally constrains
+<function>YSorted </function>
+order in that all
+rectangles with an equal Y origin are nondecreasing in their X
+origin.
+<function>YXBanded </function>
+additionally constrains
+<function>YXSorted </function>
+by requiring that,
+for every possible Y scanline, all rectangles that include that
+scanline have an identical Y origins and Y extents.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClipRectangles</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides a set of basic functions for performing
+region arithmetic.
+For information about these functions,
+see section 16.5.
+</para>
+</sect2>
+<sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_">
+<title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure </title>
+<!-- .XS -->
+<!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the arc mode of a given GC, use
+<function>XSetArcMode</function>.
+<indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetArcMode</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>int<parameter> arc_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arc_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the arc mode.
+You can pass
+<function>ArcChord</function>
+or
+<function>ArcPieSlice</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetArcMode</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the subwindow mode of a given GC, use
+<function>XSetSubwindowMode</function>.
+<indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetSubwindowMode</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>int<parameter> subwindow_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>subwindow_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subwindow mode.
+You can pass
+<function>ClipByChildren</function>
+or
+<function>IncludeInferiors</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetSubwindowMode</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the graphics-exposures flag of a given GC, use
+<function>XSetGraphicsExposures</function>.
+<indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetGraphicsExposures</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Bool<parameter> graphics_exposures</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>graphics_exposures</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether you want
+<function>GraphicsExpose</function>
+and
+<function>NoExpose</function>
+events to be reported when calling
+<function>XCopyArea</function>
+and
+<function>XCopyPlane</function>
+with this GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetGraphicsExposures</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadGC</function>,
+and
+<function>BadValue </function>
+errors.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH08 b/libX11/specs/libX11/CH08 deleted file mode 100644 index 3d2161fb2..000000000 --- a/libX11/specs/libX11/CH08 +++ /dev/null @@ -1,3468 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 8\fP\s-1 - -\s+1\fBGraphics Functions\fP\s-1 -.sp 2 -.nr H1 8 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 8: Graphics Functions -.XE -Once you have established a connection to a display, -you can use the Xlib graphics functions to: -.IP \(bu 5 -Clear and copy areas -.IP \(bu 5 -Draw points, lines, rectangles, and arcs -.IP \(bu 5 -Fill areas -.IP \(bu 5 -Manipulate fonts -.IP \(bu 5 -Draw text -.IP \(bu 5 -Transfer images between clients and the server -.LP -If the same drawable and GC is used for each call, -Xlib batches back-to-back calls to -.PN XDrawPoint , -.PN XDrawLine , -.PN XDrawRectangle , -.PN XFillArc , -and -.PN XFillRectangle . -Note that this reduces the total number of requests sent to the server. -.NH 2 -Clearing Areas -.XS -\*(SN Clearing Areas -.XE -.LP -Xlib provides functions that you can use to clear an area or the entire window. -Because pixmaps do not have defined backgrounds, -they cannot be filled by using the functions described in this section. -Instead, to accomplish an analogous operation on a pixmap, -you should use -.PN XFillRectangle , -which sets the pixmap to a known value. -.LP -.sp -To clear a rectangular area of a given window, use -.PN XClearArea . -.IN "Areas" "clearing" -.IN "Clearing" "areas" -.IN "XClearArea" "" "@DEF@" -.sM -.FD 0 -XClearArea\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIexposures\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - Bool \fIexposures\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.ds Xy , which are relative to the origin of the window \ -and specify the upper-left corner of the rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which are the dimensions of the rectangle -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIexposures\fP 1i -Specifies a Boolean value that indicates if -.PN Expose -events are to be generated. -.LP -.eM -The -.PN XClearArea -function paints a rectangular area in the specified window according to the -specified dimensions with the window's background pixel or pixmap. -The subwindow-mode effectively is -.PN ClipByChildren . -If width is zero, it -is replaced with the current width of the window minus x. -If height is -zero, it is replaced with the current height of the window minus y. -If the window has a defined background tile, -the rectangle clipped by any children is filled with this tile. -If the window has -background -.PN None , -the contents of the window are not changed. -In either -case, if exposures is -.PN True , -one or more -.PN Expose -events are generated for regions of the rectangle that are either visible or are -being retained in a backing store. -If you specify a window whose class is -.PN InputOnly , -a -.PN BadMatch -error results. -.LP -.PN XClearArea -can generate -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To clear the entire area in a given window, use -.PN XClearWindow . -.IN "Window" "clearing" -.IN "Clearing" "windows" -.IN "XClearWindow" "" "@DEF@" -.sM -.FD 0 -XClearWindow\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XClearWindow -function clears the entire area in the specified window and is -equivalent to -.PN XClearArea -(display, w, 0, 0, 0, 0, -.PN False ). -If the window has a defined background tile, the rectangle is tiled with a -plane-mask of all ones and -.PN GXcopy -function. -If the window has -background -.PN None , -the contents of the window are not changed. -If you specify a window whose class is -.PN InputOnly , -a -.PN BadMatch -error results. -.LP -.PN XClearWindow -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.NH 2 -Copying Areas -.XS -\*(SN Copying Areas -.XE -.LP -Xlib provides functions that you can use to copy an area or a bit plane. -.LP -.sp -To copy an area between drawables of the same -root and depth, use -.PN XCopyArea . -.IN "Areas" "copying" -.IN "Copying" "areas" -.IN "XCopyArea" "" "@DEF@" -.sM -.FD 0 -XCopyArea\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fIsrc\fP\^, \fIdest\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIsrc_x\fP\^, \fIsrc_y\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - int \fIdest_x\fP\^, \fIdest_y\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsrc\fP 1i -.br -.ns -.IP \fIdest\fP 1i -Specify the source and destination rectangles to be combined. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIsrc_x\fP 1i -.br -.ns -.IP \fIsrc_y\fP 1i -Specify the x and y coordinates, -which are relative to the origin of the source rectangle -and specify its upper-left corner. -.ds Wh , which are the dimensions of both the source \ -and destination rectangles -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.ds Dx , which are relative to the origin of the destination rectangle \ -and specify its upper-left corner -.IP \fIdest_x\fP 1i -.br -.ns -.IP \fIdest_y\fP 1i -Specify the x and y coordinates\*(Dx. -.LP -.eM -The -.PN XCopyArea -function combines the specified rectangle of src with the specified rectangle -of dest. -The drawables must have the same root and depth, -or a -.PN BadMatch -error results. -.LP -If regions of the source rectangle are obscured and have not been -retained in backing store -or if regions outside the boundaries of the source drawable are specified, -those regions are not copied. -Instead, the -following occurs on all corresponding destination regions that are either -visible or are retained in backing store. -If the destination is a window with a background other than -.PN None , -corresponding regions -of the destination are tiled with that background -(with plane-mask of all ones and -.PN GXcopy -function). -Regardless of tiling or whether the destination is a window or a pixmap, -if graphics-exposures is -.PN True , -then -.PN GraphicsExpose -events for all corresponding destination regions are generated. -If graphics-exposures is -.PN True -but no -.PN GraphicsExpose -events are generated, a -.PN NoExpose -event is generated. -Note that by default graphics-exposures is -.PN True -in new GCs. -.LP -This function uses these GC components: function, plane-mask, -subwindow-mode, graphics-exposures, clip-x-origin, -clip-y-origin, and clip-mask. -.LP -.PN XCopyArea -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.sp -.LP -To copy a single bit plane of a given drawable, use -.PN XCopyPlane . -.IN "Plane" "copying" -.IN "Copying" "planes" -.IN "XCopyPlane" "" "@DEF@" -.sM -.FD 0 -XCopyPlane\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIplane\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fIsrc\fP\^, \fIdest\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIsrc_x\fP\^, \fIsrc_y\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - int \fIdest_x\fP\^, \fIdest_y\fP\^; -.br - unsigned long \fIplane\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsrc\fP 1i -.br -.ns -.IP \fIdest\fP 1i -Specify the source and destination rectangles to be combined. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIsrc_x\fP 1i -.br -.ns -.IP \fIsrc_y\fP 1i -Specify the x and y coordinates, -which are relative to the origin of the source rectangle -and specify its upper-left corner. -.ds Wh , which are the dimensions of both the source and destination rectangles -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.ds Dx , which are relative to the origin of the destination rectangle \ -and specify its upper-left corner -.IP \fIdest_x\fP 1i -.br -.ns -.IP \fIdest_y\fP 1i -Specify the x and y coordinates\*(Dx. -.IP \fIplane\fP 1i -Specifies the bit plane. -You must set exactly one bit to 1. -.LP -.eM -The -.PN XCopyPlane -function uses a single bit plane of the specified source rectangle -combined with the specified GC to modify the specified rectangle of dest. -The drawables must have the same root but need not have the same depth. -If the drawables do not have the same root, a -.PN BadMatch -error results. -If plane does not have exactly one bit set to 1 and the value of plane -is not less than %2 sup n%, where \fIn\fP is the depth of src, a -.PN BadValue -error results. -.LP -Effectively, -.PN XCopyPlane -forms a pixmap of the same depth as the rectangle of dest and with a -size specified by the source region. -It uses the foreground/background pixels in the GC (foreground -everywhere the bit plane in src contains a bit set to 1, -background everywhere the bit plane in src contains a bit set to 0) -and the equivalent of a -.PN CopyArea -protocol request is performed with all the same exposure semantics. -This can also be thought of as using the specified region of the source -bit plane as a stipple with a fill-style of -.PN FillOpaqueStippled -for filling a rectangular area of the destination. -.LP -This function uses these GC components: function, plane-mask, foreground, -background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, -and clip-mask. -.LP -.PN XCopyPlane -can generate -.PN BadDrawable , -.PN BadGC , -.PN BadMatch , -and -.PN BadValue -errors. -.NH 2 -Drawing Points, Lines, Rectangles, and Arcs -.XS -\*(SN Drawing Points, Lines, Rectangles, and Arcs -.XE -.LP -Xlib provides functions that you can use to draw: -.IP \(bu 5 -A single point or multiple points -.IP \(bu 5 -A single line or multiple lines -.IP \(bu 5 -A single rectangle or multiple rectangles -.IP \(bu 5 -A single arc or multiple arcs -.LP -Some of the functions described in the following sections -use these structures: -.LP -.IN "XSegment" "" "@DEF@" -.sM -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - short x1, y1, x2, y2; -} XSegment; -.De -.LP -.eM -.IN "XPoint" "" "@DEF@" -.sM -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - short x, y; -} XPoint; -.De -.LP -.eM -.IN "XRectangle" "" "@DEF@" -.sM -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - short x, y; - unsigned short width, height; -} XRectangle; -.De -.LP -.eM -.IN "XArc" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - short x, y; - unsigned short width, height; - short angle1, angle2; /* Degrees * 64 */ -} XArc; -.De -.LP -.eM -All x and y members are signed integers. -The width and height members are 16-bit unsigned integers. -You should be careful not to generate coordinates and sizes -out of the 16-bit ranges, because the protocol only has 16-bit fields -for these values. -.NH 3 -Drawing Single and Multiple Points -.XS -\*(SN Drawing Single and Multiple Points -.XE -.LP -.IN "Points" "drawing" -.IN "Drawing" "points" -.IN "XDrawPoints" -.IN "XDrawPoint" -.LP -To draw a single point in a given drawable, use -.PN XDrawPoint . -.IN "XDrawPoint" "" "@DEF@" -.sM -.FD 0 -XDrawPoint\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates where you want the point drawn. -.LP -.eM -.sp -To draw multiple points in a given drawable, use -.PN XDrawPoints . -.IN "XDrawPoints" "" "@DEF@" -.sM -.FD 0 -XDrawPoints\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XPoint *\fIpoints\fP\^; -.br - int \fInpoints\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIpoints\fP 1i -Specifies an array of points. -.IP \fInpoints\fP 1i -Specifies the number of points in the array. -.IP \fImode\fP 1i -Specifies the coordinate mode. -You can pass -.PN CoordModeOrigin -or -.PN CoordModePrevious . -.LP -.eM -The -.PN XDrawPoint -function uses the foreground pixel and function components of the -GC to draw a single point into the specified drawable; -.PN XDrawPoints -draws multiple points this way. -.PN CoordModeOrigin -treats all coordinates as relative to the origin, -and -.PN CoordModePrevious -treats all coordinates after the first as relative to the previous point. -.PN XDrawPoints -draws the points in the order listed in the array. -.LP -Both functions use these GC components: function, plane-mask, -foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. -.LP -.PN XDrawPoint -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.PN XDrawPoints -can generate -.PN BadDrawable , -.PN BadGC , -.PN BadMatch , -and -.PN BadValue -errors. -.NH 3 -Drawing Single and Multiple Lines -.XS -\*(SN Drawing Single and Multiple Lines -.XE -.LP -.IN "Lines" "drawing" -.IN "Drawing" "lines" -.IN "XDrawLine" -.IN "XDrawLines" -.IN "Polygons" "drawing" -.IN "Drawing" "polygons" -.IN "XDrawSegments" -.LP -To draw a single line between two points in a given drawable, use -.PN XDrawLine . -.IN "XDrawLine" "" "@DEF@" -.sM -.FD 0 -XDrawLine\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIx1\fP 1i -.br -.ns -.IP \fIy1\fP 1i -.br -.ns -.IP \fIx2\fP 1i -.br -.ns -.IP \fIy2\fP 1i -Specify the points (x1, y1) and (x2, y2) to be connected. -.LP -.eM -.sp -To draw multiple lines in a given drawable, use -.PN XDrawLines . -.IN "XDrawLines" "" "@DEF@" -.sM -.FD 0 -XDrawLines\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XPoint *\fIpoints\fP\^; -.br - int \fInpoints\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIpoints\fP 1i -Specifies an array of points. -.IP \fInpoints\fP 1i -Specifies the number of points in the array. -.IP \fImode\fP 1i -Specifies the coordinate mode. -You can pass -.PN CoordModeOrigin -or -.PN CoordModePrevious . -.LP -.eM -.sp -To draw multiple, unconnected lines in a given drawable, -use -.PN XDrawSegments . -.IN "XDrawSegments" "" "@DEF@" -.sM -.FD 0 -XDrawSegments\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIsegments\fP\^, \fInsegments\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XSegment *\fIsegments\fP\^; -.br - int \fInsegments\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIsegments\fP 1i -Specifies an array of segments. -.IP \fInsegments\fP 1i -Specifies the number of segments in the array. -.LP -.eM -The -.PN XDrawLine -function uses the components of the specified GC to -draw a line between the specified set of points (x1, y1) and (x2, y2). -It does not perform joining at coincident endpoints. -For any given line, -.PN XDrawLine -does not draw a pixel more than once. -If lines intersect, the intersecting pixels are drawn multiple times. -.LP -The -.PN XDrawLines -function uses the components of the specified GC to draw -npoints\-1 lines between each pair of points (point[i], point[i+1]) -in the array of -.PN XPoint -structures. -It draws the lines in the order listed in the array. -The lines join correctly at all intermediate points, and if the first and last -points coincide, the first and last lines also join correctly. -For any given line, -.PN XDrawLines -does not draw a pixel more than once. -If thin (zero line-width) lines intersect, -the intersecting pixels are drawn multiple times. -If wide lines intersect, the intersecting pixels are drawn only once, as though -the entire -.PN PolyLine -protocol request were a single, filled shape. -.PN CoordModeOrigin -treats all coordinates as relative to the origin, -and -.PN CoordModePrevious -treats all coordinates after the first as relative to the previous point. -.LP -The -.PN XDrawSegments -function draws multiple, unconnected lines. -For each segment, -.PN XDrawSegments -draws a -line between (x1, y1) and (x2, y2). -It draws the lines in the order listed in the array of -.PN XSegment -structures and does not perform joining at coincident endpoints. -For any given line, -.PN XDrawSegments -does not draw a pixel more than once. -If lines intersect, the intersecting pixels are drawn multiple times. -.LP -All three functions use these GC components: -function, plane-mask, line-width, -line-style, cap-style, fill-style, subwindow-mode, -clip-x-origin, clip-y-origin, and clip-mask. -The -.PN XDrawLines -function also uses the join-style GC component. -All three functions also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -tile-stipple-y-origin, dash-offset, and dash-list. -.LP -.PN XDrawLine , -.PN XDrawLines , -and -.PN XDrawSegments -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.PN XDrawLines -also can generate -.PN BadValue -errors. -.NH 3 -Drawing Single and Multiple Rectangles -.XS -\*(SN Drawing Single and Multiple Rectangles -.XE -.LP -.IN "Rectangles" "drawing" -.IN "Drawing" "rectangles" -.IN "XDrawRectangle" -.IN "XDrawRectangles" -.LP -To draw the outline of a single rectangle in a given drawable, use -.PN XDrawRectangle . -.IN "XDrawRectangle" "" "@DEF@" -.sM -.FD 0 -XDrawRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which specify the upper-left corner of the rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which specify the dimensions of the rectangle -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.LP -.eM -.sp -To draw the outline of multiple rectangles -in a given drawable, use -.PN XDrawRectangles . -.IN "XDrawRectangles" "" "@DEF@" -.sM -.FD 0 -XDrawRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XRectangle \fIrectangles\fP\^[\^]\^; -.br - int \fInrectangles\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIrectangles\fP 1i -Specifies an array of rectangles. -.IP \fInrectangles\fP 1i -Specifies the number of rectangles in the array. -.LP -.eM -The -.PN XDrawRectangle -and -.PN XDrawRectangles -functions draw the outlines of the specified rectangle or rectangles as -if a five-point -.PN PolyLine -protocol request were specified for each rectangle: -.IP -[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] -.LP -For the specified rectangle or rectangles, -these functions do not draw a pixel more than once. -.PN XDrawRectangles -draws the rectangles in the order listed in the array. -If rectangles intersect, -the intersecting pixels are drawn multiple times. -.LP -Both functions use these GC components: -function, plane-mask, line-width, -line-style, cap-style, join-style, fill-style, -subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. -They also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -tile-stipple-y-origin, dash-offset, and dash-list. -.LP -.PN XDrawRectangle -and -.PN XDrawRectangles -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.NH 3 -Drawing Single and Multiple Arcs -.XS -\*(SN Drawing Single and Multiple Arcs -.XE -.LP -.IN "Drawing" "arcs" -.IN "XDrawArc" -.IN "Arcs" "drawing" -.IN "XDrawArcs" -.LP -.sp -To draw a single arc in a given drawable, use -.PN XDrawArc . -.IN "XDrawArc" "" "@DEF@" -.sM -.FD 0 -XDrawArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - int \fIangle1\fP\^, \fIangle2\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the drawable \ -and specify the upper-left corner of the bounding rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which are the major and minor axes of the arc -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIangle1\fP 1i -Specifies the start of the arc relative to the three-o'clock position -from the center, in units of degrees * 64. -.IP \fIangle2\fP 1i -Specifies the path and extent of the arc relative to the start of the -arc, in units of degrees * 64. -.LP -.eM -.sp -To draw multiple arcs in a given drawable, use -.PN XDrawArcs . -.IN "XDrawArcs" "" "@DEF@" -.sM -.FD 0 -XDrawArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XArc *\fIarcs\fP\^; -.br - int \fInarcs\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIarcs\fP 1i -Specifies an array of arcs. -.IP \fInarcs\fP 1i -Specifies the number of arcs in the array. -.LP -.eM -.EQ -delim %% -.EN -.PN XDrawArc -draws a single circular or elliptical arc, and -.PN XDrawArcs -draws multiple circular or elliptical arcs. -Each arc is specified by a rectangle and two angles. -The center of the circle or ellipse is the center of the -rectangle, and the major and minor axes are specified by the width and height. -Positive angles indicate counterclockwise motion, -and negative angles indicate clockwise motion. -If the magnitude of angle2 is greater than 360 degrees, -.PN XDrawArc -or -.PN XDrawArcs -truncates it to 360 degrees. -.LP -For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, -the origin of the major and minor axes is at -% [ x +^ {width over 2} , ~y +^ {height over 2} ]%, -and the infinitely thin path describing the entire circle or ellipse -intersects the horizontal axis at % [ x, ~y +^ {height over 2} ]% and -% [ x +^ width , ~y +^ { height over 2 }] % -and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and -% [ x +^ { width over 2 }, ~y +^ height ]%. -These coordinates can be fractional -and so are not truncated to discrete coordinates. -The path should be defined by the ideal mathematical path. -For a wide line with line-width lw, -the bounding outlines for filling are given -by the two infinitely thin paths consisting of all points whose perpendicular -distance from the path of the circle/ellipse is equal to lw/2 -(which may be a fractional value). -The cap-style and join-style are applied the same as for a line -corresponding to the tangent of the circle/ellipse at the endpoint. -.LP -For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]%, -the angles must be specified -in the effectively skewed coordinate system of the ellipse (for a -circle, the angles and coordinate systems are identical). The -relationship between these angles and angles expressed in the normal -coordinate system of the screen (as measured with a protractor) is as -follows: -.LP -.Ds -% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" ) - * width over height right ) +^ adjust% -.De -.LP -The skewed-angle and normal-angle are expressed in radians (rather -than in degrees scaled by 64) in the range % [ 0 , ~2 pi ]% and where atan -returns a value in the range % [ - pi over 2 , ~pi over 2 ] % -and adjust is: -.LP -.Ds -.TA 1i 2i -.ta 1i 2i -%0% for normal-angle in the range % [ 0 , ~pi over 2 ]% -%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]% -%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]% -.De -.LP -For any given arc, -.PN XDrawArc -and -.PN XDrawArcs -do not draw a pixel more than once. -If two arcs join correctly and if the line-width is greater than zero -and the arcs intersect, -.PN XDrawArc -and -.PN XDrawArcs -do not draw a pixel more than once. -Otherwise, -the intersecting pixels of intersecting arcs are drawn multiple times. -Specifying an arc with one endpoint and a clockwise extent draws the same pixels -as specifying the other endpoint and an equivalent counterclockwise extent, -except as it affects joins. -.LP -If the last point in one arc coincides with the first point in the following -arc, the two arcs will join correctly. -If the first point in the first arc coincides with the last point in the last -arc, the two arcs will join correctly. -By specifying one axis to be zero, a horizontal or vertical line can be -drawn. -Angles are computed based solely on the coordinate system and ignore the -aspect ratio. -.LP -Both functions use these GC components: -function, plane-mask, line-width, line-style, cap-style, join-style, -fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. -They also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -tile-stipple-y-origin, dash-offset, and dash-list. -.LP -.PN XDrawArc -and -.PN XDrawArcs -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.NH 2 -Filling Areas -.XS -\*(SN Filling Areas -.XE -.LP -Xlib provides functions that you can use to fill: -.IP \(bu 5 -A single rectangle or multiple rectangles -.IP \(bu 5 -A single polygon -.IP \(bu 5 -A single arc or multiple arcs -.NH 3 -Filling Single and Multiple Rectangles -.XS -\*(SN Filling Single and Multiple Rectangles -.XE -.LP -.IN "Filling" "rectangles" -.IN "XFillRectangle" -.IN "Rectangle" "filling" -.IN "XFillRectangles" -.LP -.sp -To fill a single rectangular area in a given drawable, use -.PN XFillRectangle . -.IN "XFillRectangle" "" "@DEF@" -.sM -.FD 0 -XFillRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the drawable \ -and specify the upper-left corner of the rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which are the dimensions of the rectangle to be filled -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.LP -.eM -.sp -To fill multiple rectangular areas in a given drawable, use -.PN XFillRectangles . -.IN "XFillRectangles" "" "@DEF@" -.sM -.FD 0 -XFillRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XRectangle *\fIrectangles\fP\^; -.br - int \fInrectangles\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIrectangles\fP 1i -Specifies an array of rectangles. -.IP \fInrectangles\fP 1i -Specifies the number of rectangles in the array. -.LP -.eM -The -.PN XFillRectangle -and -.PN XFillRectangles -functions fill the specified rectangle or rectangles -as if a four-point -.PN FillPolygon -protocol request were specified for each rectangle: -.LP -.Ds -[x,y] [x+width,y] [x+width,y+height] [x,y+height] -.De -.LP -Each function uses the x and y coordinates, -width and height dimensions, and GC you specify. -.LP -.PN XFillRectangles -fills the rectangles in the order listed in the array. -For any given rectangle, -.PN XFillRectangle -and -.PN XFillRectangles -do not draw a pixel more than once. -If rectangles intersect, the intersecting pixels are -drawn multiple times. -.LP -Both functions use these GC components: -function, plane-mask, fill-style, subwindow-mode, -clip-x-origin, clip-y-origin, and clip-mask. -They also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -and tile-stipple-y-origin. -.LP -.PN XFillRectangle -and -.PN XFillRectangles -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.NH 3 -Filling a Single Polygon -.XS -\*(SN Filling a Single Polygon -.XE -.LP -.sp -To fill a polygon area in a given drawable, use -.PN XFillPolygon . -.IN "Polygons" "filling" -.IN "Filling" "polygon" -.IN "XFillPolygon" "" "@DEF@" -.sM -.FD 0 -XFillPolygon\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fIshape\fP\^, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XPoint *\fIpoints\fP\^; -.br - int \fInpoints\fP\^; -.br - int \fIshape\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIpoints\fP 1i -Specifies an array of points. -.IP \fInpoints\fP 1i -Specifies the number of points in the array. -.IP \fIshape\fP 1i -Specifies a shape that helps the server to improve performance. -You can pass -.PN Complex , -.PN Convex , -or -.PN Nonconvex . -.IP \fImode\fP 1i -Specifies the coordinate mode. -You can pass -.PN CoordModeOrigin -or -.PN CoordModePrevious . -.LP -.eM -.PN XFillPolygon -fills the region closed by the specified path. -The path is closed -automatically if the last point in the list does not coincide with the -first point. -.PN XFillPolygon -does not draw a pixel of the region more than once. -.PN CoordModeOrigin -treats all coordinates as relative to the origin, -and -.PN CoordModePrevious -treats all coordinates after the first as relative to the previous point. -.LP -Depending on the specified shape, the following occurs: -.IP \(bu 5 -If shape is -.PN Complex , -the path may self-intersect. -Note that contiguous coincident points in the path are not treated -as self-intersection. -.IP \(bu 5 -If shape is -.PN Convex , -for every pair of points inside the polygon, -the line segment connecting them does not intersect the path. -If known by the client, -specifying -.PN Convex -can improve performance. -If you specify -.PN Convex -for a path that is not convex, -the graphics results are undefined. -.IP \(bu 5 -If shape is -.PN Nonconvex , -the path does not self-intersect, but the shape is not -wholly convex. -If known by the client, -specifying -.PN Nonconvex -instead of -.PN Complex -may improve performance. -If you specify -.PN Nonconvex -for a self-intersecting path, the graphics results are undefined. -.LP -The fill-rule of the GC controls the filling behavior of -self-intersecting polygons. -.LP -This function uses these GC components: -function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, -clip-y-origin, and clip-mask. -It also uses these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -and tile-stipple-y-origin. -.LP -.PN XFillPolygon -can generate -.PN BadDrawable , -.PN BadGC , -.PN BadMatch , -and -.PN BadValue -errors. -.NH 3 -Filling Single and Multiple Arcs -.XS -\*(SN Filling Single and Multiple Arcs -.XE -.LP -.IN "XFillArc" -.IN "Arcs" "filling" -.IN "Filling" "arcs" -To fill a single arc in a given drawable, use -.PN XFillArc . -.IN "XFillArc" "" "@DEF@" -.sM -.FD 0 -XFillArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - int \fIangle1\fP\^, \fIangle2\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the drawable \ -and specify the upper-left corner of the bounding rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which are the major and minor axes of the arc -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIangle1\fP 1i -Specifies the start of the arc relative to the three-o'clock position -from the center, in units of degrees * 64. -.IP \fIangle2\fP 1i -Specifies the path and extent of the arc relative to the start of the -arc, in units of degrees * 64. -.LP -.eM -.sp -To fill multiple arcs in a given drawable, use -.PN XFillArcs . -.IN "XFillArcs" "" "@DEF@" -.sM -.FD 0 -XFillArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XArc *\fIarcs\fP\^; -.br - int \fInarcs\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIarcs\fP 1i -Specifies an array of arcs. -.IP \fInarcs\fP 1i -Specifies the number of arcs in the array. -.LP -.eM -For each arc, -.PN XFillArc -or -.PN XFillArcs -fills the region closed by the infinitely thin path -described by the specified arc and, depending on the -arc-mode specified in the GC, one or two line segments. -For -.PN ArcChord , -the single line segment joining the endpoints of the arc is used. -For -.PN ArcPieSlice , -the two line segments joining the endpoints of the arc with the center -point are used. -.PN XFillArcs -fills the arcs in the order listed in the array. -For any given arc, -.PN XFillArc -and -.PN XFillArcs -do not draw a pixel more than once. -If regions intersect, -the intersecting pixels are drawn multiple times. -.LP -Both functions use these GC components: -function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, -clip-y-origin, and clip-mask. -They also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -and tile-stipple-y-origin. -.LP -.PN XFillArc -and -.PN XFillArcs -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.NH 2 -Font Metrics -.XS -\*(SN Font Metrics -.XE -.LP -.IN "Font" -A font is a graphical description of a set of characters that are used to -increase efficiency whenever a set of small, similar sized patterns are -repeatedly used. -.LP -This section discusses how to: -.IP \(bu 5 -Load and free fonts -.IP \(bu 5 -Obtain and free font names -.IP \(bu 5 -Compute character string sizes -.IP \(bu 5 -Compute logical extents -.IP \(bu 5 -Query character string sizes -.LP -The X server loads fonts whenever a program requests a new font. -The server can cache fonts for quick lookup. -Fonts are global across all screens in a server. -Several levels are possible when dealing with fonts. -Most applications simply use -.PN XLoadQueryFont -to load a font and query the font metrics. -.LP -Characters in fonts are regarded as masks. -Except for image text requests, -the only pixels modified are those in which bits are set to 1 in the character. -This means that it makes sense to draw text using stipples or tiles -(for example, many menus gray-out unusable entries). -.LP -.sM -The -.PN XFontStruct -structure contains all of the information for the font -and consists of the font-specific information as well as -a pointer to an array of -.PN XCharStruct -structures for the -characters contained in the font. -The -.PN XFontStruct , -.PN XFontProp , -and -.PN XCharStruct -structures contain: -.LP -.IN "XCharStruct" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - short lbearing; /* origin to left edge of raster */ - short rbearing; /* origin to right edge of raster */ - short width; /* advance to next char's origin */ - short ascent; /* baseline to top edge of raster */ - short descent; /* baseline to bottom edge of raster */ - unsigned short attributes; /* per char flags (not predefined) */ -} XCharStruct; -.De -.LP -.IN "XFontProp" "" "@DEF@" -.Ds 0 -.TA .5i 1i 3i -.ta .5i 1i 3i -typedef struct { - Atom name; - unsigned long card32; -} XFontProp; -.De -.LP -.IN "XChar2b" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { /* normal 16 bit characters are two bytes */ - unsigned char byte1; - unsigned char byte2; -} XChar2b; -.De -.LP -.IN "XFontStruct" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - XExtData *ext_data; /* hook for extension to hang data */ - Font fid; /* Font id for this font */ - unsigned direction; /* hint about the direction font is painted */ - unsigned min_char_or_byte2; /* first character */ - unsigned max_char_or_byte2; /* last character */ - unsigned min_byte1; /* first row that exists */ - unsigned max_byte1; /* last row that exists */ - Bool all_chars_exist; /* flag if all characters have nonzero size */ - unsigned default_char; /* char to print for undefined character */ - int n_properties; /* how many properties there are */ - XFontProp *properties; /* pointer to array of additional properties */ - XCharStruct min_bounds; /* minimum bounds over all existing char */ - XCharStruct max_bounds; /* maximum bounds over all existing char */ - XCharStruct *per_char; /* first_char to last_char information */ - int ascent; /* logical extent above baseline for spacing */ - int descent; /* logical descent below baseline for spacing */ -} XFontStruct; -.De -.LP -.eM -X supports single byte/character, two bytes/character matrix, -and 16-bit character text operations. -Note that any of these forms can be used with a font, but a -single byte/character text request can only specify a single byte -(that is, the first row of a 2-byte font). -You should view 2-byte fonts as a two-dimensional matrix of defined -characters: byte1 specifies the range of defined rows and -byte2 defines the range of defined columns of the font. -Single byte/character fonts have one row defined, and the byte2 range -specified in the structure defines a range of characters. -.LP -The bounding box of a character is defined by the -.PN XCharStruct -of that character. -When characters are absent from a font, -the default_char is used. -When fonts have all characters of the same size, -only the information in the -.PN XFontStruct -min and max bounds are used. -.LP -The members of the -.PN XFontStruct -have the following semantics: -.IP \(bu 5 -The direction member can be either -.PN FontLeftToRight -or -.PN FontRightToLeft . -It is just a hint as to whether most -.PN XCharStruct -elements -have a positive -.Pn ( FontLeftToRight ) -or a negative -.Pn ( FontRightToLeft ) -character width -metric. -The core protocol defines no support for vertical text. -.IP \(bu 5 -If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2 -specifies the linear character index corresponding to the first element -of the per_char array, and max_char_or_byte2 specifies the linear character -index of the last element. -.IP -If either min_byte1 or max_byte1 are nonzero, both -min_char_or_byte2 and max_char_or_byte2 are less than 256, -and the 2-byte character index values corresponding to the -per_char array element N (counting from 0) are: -.IP -.nf - byte1 = N/D + min_byte1 -.br - byte2 = N\\D + min_char_or_byte2 -.IP -.fi -where: -.IP -.nf - D = max_char_or_byte2 \- min_char_or_byte2 + 1 - / = integer division - \\ = integer modulus -.fi -.IP \(bu 5 -If the per_char pointer is NULL, -all glyphs between the first and last character indexes -inclusive have the same information, -as given by both min_bounds and max_bounds. -.IP \(bu 5 -If all_chars_exist is -.PN True , -all characters in the per_char array have nonzero bounding boxes. -.IP \(bu 5 -The default_char member specifies the character that will be used when an -undefined or nonexistent character is printed. -The default_char is a 16-bit character (not a 2-byte character). -For a font using 2-byte matrix format, -the default_char has byte1 in the most-significant byte -and byte2 in the least significant byte. -If the default_char itself specifies an undefined or nonexistent character, -no printing is performed for an undefined or nonexistent character. -.IP \(bu 5 -The min_bounds and max_bounds members contain the most extreme values of -each individual -.PN XCharStruct -component over all elements of this array -(and ignore nonexistent characters). -The bounding box of the font (the smallest -rectangle enclosing the shape obtained by superimposing all of the -characters at the same origin [x,y]) has its upper-left coordinate at: -.Ds - [x + min_bounds.lbearing, y \- max_bounds.ascent] -.De -.IP -Its width is: -.Ds - max_bounds.rbearing \- min_bounds.lbearing -.De -.IP -Its height is: -.Ds - max_bounds.ascent + max_bounds.descent -.De -.IP \(bu 5 -The ascent member is the logical extent of the font above the baseline that is -used for determining line spacing. -Specific characters may extend beyond -this. -.IP \(bu 5 -The descent member is the logical extent of the font at or below the -baseline that is used for determining line spacing. -Specific characters may extend beyond this. -.IP \(bu 5 -If the baseline is at Y-coordinate y, -the logical extent of the font is inclusive between the Y-coordinate -values (y \- font.ascent) and (y + font.descent \- 1). -Typically, -the minimum interline spacing between rows of text is given -by ascent + descent. -.LP -For a character origin at [x,y], -the bounding box of a character (that is, -the smallest rectangle that encloses the character's shape) -described in terms of -.PN XCharStruct -components is a rectangle with its upper-left corner at: -.LP -.Ds -[x + lbearing, y \- ascent] -.De -.LP -Its width is: -.LP -.Ds -rbearing \- lbearing -.De -.LP -Its height is: -.LP -.Ds -ascent + descent -.De -.LP -The origin for the next character is defined to be: -.LP -.Ds -[x + width, y] -.De -.LP -The lbearing member defines the extent of the left edge of the character ink -from the origin. -The rbearing member defines the extent of the right edge of the character ink -from the origin. -The ascent member defines the extent of the top edge of the character ink -from the origin. -The descent member defines the extent of the bottom edge of the character ink -from the origin. -The width member defines the logical width of the character. -.LP -Note that the baseline (the y position of the character origin) -is logically viewed as being the scanline just below nondescending characters. -When descent is zero, -only pixels with Y-coordinates less than y are drawn, -and the origin is logically viewed as being coincident with the left edge of -a nonkerned character. -When lbearing is zero, -no pixels with X-coordinate less than x are drawn. -Any of the -.PN XCharStruct -metric members could be negative. -If the width is negative, -the next character will be placed to the left of the current origin. -.LP -The X protocol does not define the interpretation of the attributes member -in the -.PN XCharStruct -structure. -A nonexistent character is represented with all members of its -.PN XCharStruct -set to zero. -.LP -A font is not guaranteed to have any properties. -The interpretation of the property value (for example, long or unsigned long) -must be derived from \fIa priori\fP knowledge of the property. -A basic set of font properties is specified in the X Consortium standard -\fIX Logical Font Description Conventions\fP. -.NH 3 -Loading and Freeing Fonts -.XS -\*(SN Loading and Freeing Fonts -.XE -.LP -Xlib provides functions that you can use to load fonts, get font information, -unload fonts, and free font information. -.IN "Fonts" "getting information" -.IN "Fonts" "unloading" -.IN "Fonts" "freeing font information" -A few font functions use a -.PN GContext -resource ID or a font ID interchangeably. -.LP -.sp -To load a given font, use -.PN XLoadFont . -.IN "XLoadFont" "" "@DEF@" -.sM -.FD 0 -Font XLoadFont\^(\^\fIdisplay\fP, \fIname\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIname\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIname\fP 1i -Specifies the name of the font, -which is a null-terminated string. -.LP -.eM -The -.PN XLoadFont -function loads the specified font and returns its associated font ID. -If the font name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -When the characters ``?'' and ``*'' are used in a font name, a -pattern match is performed and any matching font is used. -In the pattern, -the ``?'' character will match any single character, -and the ``*'' character will match any number of characters. -A structured format for font names is specified in the X Consortium standard -\fIX Logical Font Description Conventions\fP. -If -.PN XLoadFont -was unsuccessful at loading the specified font, -a -.PN BadName -error results. -Fonts are not associated with a particular screen -and can be stored as a component -of any GC. -When the font is no longer needed, call -.PN XUnloadFont . -.LP -.PN XLoadFont -can generate -.PN BadAlloc -and -.PN BadName -errors. -.LP -.sp -To return information about an available font, use -.PN XQueryFont . -.IN "XQueryFont" "" "@DEF@" -.sM -.FD 0 -XFontStruct *XQueryFont\^(\^\fIdisplay\fP, \fIfont_ID\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIfont_ID\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfont_ID\fP 1i -Specifies the font ID or the -.PN GContext -ID. -.LP -.eM -The -.PN XQueryFont -function returns a pointer to the -.PN XFontStruct -structure, which contains information associated with the font. -You can query a font or the font stored in a GC. -The font ID stored in the -.PN XFontStruct -structure will be the -.PN GContext -ID, and you need to be careful when using this ID in other functions -(see -.PN XGContextFromGC ). -If the font does not exist, -.PN XQueryFont -returns NULL. -To free this data, use -.PN XFreeFontInfo . -.LP -.sp -To perform a -.PN XLoadFont -and -.PN XQueryFont -in a single operation, use -.PN XLoadQueryFont . -.IN "XLoadQueryFont" "" "@DEF@" -.sM -.FD 0 -XFontStruct *XLoadQueryFont\^(\^\fIdisplay\fP, \fIname\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIname\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIname\fP 1i -Specifies the name of the font, -which is a null-terminated string. -.LP -.eM -The -.PN XLoadQueryFont -function provides the most common way for accessing a font. -.PN XLoadQueryFont -both opens (loads) the specified font and returns a pointer to the -appropriate -.PN XFontStruct -structure. -If the font name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -If the font does not exist, -.PN XLoadQueryFont -returns NULL. -.LP -.PN XLoadQueryFont -can generate a -.PN BadAlloc -error. -.LP -.sp -To unload the font and free the storage used by the font structure -that was allocated by -.PN XQueryFont -or -.PN XLoadQueryFont , -use -.PN XFreeFont . -.IN "XFreeFont" "" "@DEF@" -.sM -.FD 0 -XFreeFont\^(\^\fIdisplay\fP, \fIfont_struct\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XFontStruct *\fIfont_struct\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfont_struct\fP 1i -Specifies the storage associated with the font. -.LP -.eM -The -.PN XFreeFont -function deletes the association between the font resource ID and the specified -font and frees the -.PN XFontStruct -structure. -The font itself will be freed when no other resource references it. -The data and the font should not be referenced again. -.LP -.PN XFreeFont -can generate a -.PN BadFont -error. -.LP -.sp -To return a given font property, use -.PN XGetFontProperty . -.IN "XGetFontProperty" "" "@DEF@" -.sM -.FD 0 -Bool XGetFontProperty\^(\^\fIfont_struct\fP\^, \^\fIatom\fP\^, \^\fIvalue_return\fP\^) -.br - XFontStruct *\fIfont_struct\fP\^; -.br - Atom \fIatom\fP\^; -.br - unsigned long *\fIvalue_return\fP\^; -.FN -.IP \fIfont_struct\fP 1i -Specifies the storage associated with the font. -.IP \fIatom\fP 1i -Specifies the atom for the property name you want returned. -.IP \fIvalue_return\fP 1i -Returns the value of the font property. -.LP -.eM -Given the atom for that property, -the -.PN XGetFontProperty -function returns the value of the specified font property. -.PN XGetFontProperty -also returns -.PN False -if the property was not defined or -.PN True -if it was defined. -A set of predefined atoms exists for font properties, -which can be found in -.hN X11/Xatom.h . -This set contains the standard properties associated with -a font. -Although it is not guaranteed, -it is likely that the predefined font properties will be present. -.LP -.sp -To unload a font that was loaded by -.PN XLoadFont , -use -.PN XUnloadFont . -.IN "XUnloadFont" "" "@DEF@" -.sM -.FD 0 -XUnloadFont\^(\^\fIdisplay\fP, \fIfont\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Font \fIfont\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfont\fP 1i -Specifies the font. -.LP -.eM -The -.PN XUnloadFont -function deletes the association between the font resource ID and the specified font. -The font itself will be freed when no other resource references it. -The font should not be referenced again. -.LP -.PN XUnloadFont -can generate a -.PN BadFont -error. -.NH 3 -Obtaining and Freeing Font Names and Information -.XS -\*(SN Obtaining and Freeing Font Names and Information -.XE -.LP -You obtain font names and information by matching a wildcard specification -when querying a font type for a list of available sizes and so on. -.LP -.sp -To return a list of the available font names, use -.PN XListFonts . -.IN "XListFonts" "" "@DEF@" -.sM -.FD 0 -char **XListFonts\^(\^\fIdisplay\fP, \fIpattern\fP\^, \fImaxnames\fP, \fIactual_count_return\fP\^) -.br - Display *\^\fIdisplay\fP\^; -.br - char *\^\fIpattern\fP\^; -.br - int \fImaxnames\fP\^; -.br - int *\^\fIactual_count_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIpattern\fP 1i -Specifies the null-terminated pattern string that can contain wildcard -characters. -.IP \fImaxnames\fP 1i -Specifies the maximum number of names to be returned. -.IP \fIactual_count_return\fP 1i -Returns the actual number of font names. -.LP -.eM -The -.PN XListFonts -function returns an array of available font names -(as controlled by the font search path; see -.PN XSetFontPath ) -that match the string you passed to the pattern argument. -The pattern string can contain any characters, -but each asterisk (*) is a wildcard for any number of characters, -and each question mark (?) is a wildcard for a single character. -If the pattern string is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -Each returned string is null-terminated. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned strings are in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -If there are no matching font names, -.PN XListFonts -returns NULL. -The client should call -.PN XFreeFontNames -when finished with the result to free the memory. -.LP -.sp -To free a font name array, use -.PN XFreeFontNames . -.IN "XFreeFontNames" "" "@DEF@" -.sM -.FD 0 -XFreeFontNames\^(\^\fIlist\fP\^) -.br - char *\fIlist\fP\^[\^]\^; -.FN -.IP \fIlist\fP 1i -Specifies the array of strings you want to free. -.LP -.eM -The -.PN XFreeFontNames -function frees the array and strings returned by -.PN XListFonts -or -.PN XListFontsWithInfo . -.LP -.sp -To obtain the names and information about available fonts, use -.PN XListFontsWithInfo . -.IN "XListFontsWithInfo" "" "@DEF@" -.sM -.FD 0 -char **XListFontsWithInfo\^(\^\fIdisplay\fP, \fIpattern\fP, \fImaxnames\fP, \fIcount_return\fP, \fIinfo_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIpattern\fP\^; -.br - int \fImaxnames\fP\^; -.br - int *\fIcount_return\fP\^; -.br - XFontStruct **\fIinfo_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIpattern\fP 1i -Specifies the null-terminated pattern string that can contain wildcard -characters. -.IP \fImaxnames\fP 1i -Specifies the maximum number of names to be returned. -.IP \fIcount_return\fP 1i -Returns the actual number of matched font names. -.IP \fIinfo_return\fP 1i -Returns the font information. -.LP -.eM -The -.PN XListFontsWithInfo -function returns a list of font names that match the specified pattern and their -associated font information. -The list of names is limited to size specified by maxnames. -The information returned for each font is identical to what -.PN XLoadQueryFont -would return except that the per-character metrics are not returned. -The pattern string can contain any characters, -but each asterisk (*) is a wildcard for any number of characters, -and each question mark (?) is a wildcard for a single character. -If the pattern string is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Use of uppercase or lowercase does not matter. -Each returned string is null-terminated. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned strings are in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -If there are no matching font names, -.PN XListFontsWithInfo -returns NULL. -.LP -To free only the allocated name array, -the client should call -.PN XFreeFontNames . -To free both the name array and the font information array -or to free just the font information array, -the client should call -.PN XFreeFontInfo . -.LP -.sp -To free font structures and font names, use -.PN XFreeFontInfo . -.IN "XFreeFontInfo" "" "@DEF@" -.sM -.FD 0 -XFreeFontInfo(\^\fInames\fP, \fIfree_info\fP, \fIactual_count\fP\^) -.br - char **\fInames\fP\^; -.br - XFontStruct *\fIfree_info\fP; -.br - int \fIactual_count\fP\^; -.FN -.IP \fInames\fP 1i -Specifies the list of font names. - -.IP \fIfree_info\fP 1i -Specifies the font information. - -.IP \fIactual_count\fP 1i -Specifies the actual number of font names. - -.LP -.eM -The -.PN XFreeFontInfo -function frees a font structure or an array of font structures -and optionally an array of font names. -If NULL is passed for names, no font names are freed. -If a font structure for an open font (returned by -.PN XLoadQueryFont ) -is passed, the structure is freed, -but the font is not closed; use -.PN XUnloadFont -to close the font. -.NH 3 -Computing Character String Sizes -.XS -\*(SN Computing Character String Sizes -.XE -.LP -Xlib provides functions that you can use to compute the width, -the logical extents, -and the server information about 8-bit and 2-byte text strings. -.IN "XTextWidth" -.IN "XTextWidth16" -The width is computed by adding the character widths of all the characters. -It does not matter if the font is an 8-bit or 2-byte font. -These functions return the sum of the character metrics in pixels. -.LP -.sp -To determine the width of an 8-bit character string, use -.PN XTextWidth . -.IN "XTextWidth" "" "@DEF@" -.sM -.FD 0 -int XTextWidth\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^) -.br - XFontStruct *\fIfont_struct\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fIcount\fP\^; -.FN -.IP \fIfont_struct\fP 1i -Specifies the font used for the width computation. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fIcount\fP 1i -Specifies the character count in the specified string. -.LP -.eM -.sp -To determine the width of a 2-byte character string, use -.PN XTextWidth16 . -.IN "XTextWidth16" "" "@DEF@" -.sM -.FD 0 -int XTextWidth16\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^) -.br - XFontStruct *\fIfont_struct\fP\^; -.br - XChar2b *\fIstring\fP\^; -.br - int \fIcount\fP\^; -.FN -.IP \fIfont_struct\fP 1i -Specifies the font used for the width computation. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fIcount\fP 1i -Specifies the character count in the specified string. -.LP -.eM -.NH 3 -Computing Logical Extents -.XS -\*(SN Computing Logical Extents -.XE -.LP -To compute the bounding box of an 8-bit character string in a given font, use -.PN XTextExtents . -.IN "XTextExtents" "" "@DEF@" -.sM -.FD 0 -XTextExtents\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \ -\fIdirection_return\fP, \fIfont_ascent_return\fP, -.br - \fIfont_descent_return\fP, \fIoverall_return\fP\^) -.br - XFontStruct *\fIfont_struct\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInchars\fP\^; -.br - int *\fIdirection_return\fP\^; -.br - int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; -.br - XCharStruct *\fIoverall_return\fP\^; - -.FN -.IP \fIfont_struct\fP 1i -Specifies the -.PN XFontStruct -structure. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInchars\fP 1i -Specifies the number of characters in the character string. -.IP \fIdirection_return\fP 1i -Returns the value of the direction hint -.Pn ( FontLeftToRight -or -.PN FontRightToLeft ). -.IP \fIfont_ascent_return\fP 1i -Returns the font ascent. -.IP \fIfont_descent_return\fP 1i -Returns the font descent. -.IP \fIoverall_return\fP 1i -Returns the overall size in the specified -.PN XCharStruct -structure. -.LP -.eM -.sp -To compute the bounding box of a 2-byte character string in a given font, use -.PN XTextExtents16 . -.IN "XTextExtents16" "" "@DEF@" -.sM -.FD 0 -XTextExtents16\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \ -\fIdirection_return\fP, \fIfont_ascent_return\fP, -.br - \fIfont_descent_return\fP, \fIoverall_return\fP\^) -.br - XFontStruct *\fIfont_struct\fP\^; -.br - XChar2b *\fIstring\fP\^; -.br - int \fInchars\fP\^; -.br - int *\fIdirection_return\fP\^; -.br - int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; -.br - XCharStruct *\fIoverall_return\fP\^; - -.FN -.IP \fIfont_struct\fP 1i -Specifies the -.PN XFontStruct -structure. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInchars\fP 1i -Specifies the number of characters in the character string. -.IP \fIdirection_return\fP 1i -Returns the value of the direction hint -.Pn ( FontLeftToRight -or -.PN FontRightToLeft ). -.IP \fIfont_ascent_return\fP 1i -Returns the font ascent. -.IP \fIfont_descent_return\fP 1i -Returns the font descent. -.IP \fIoverall_return\fP 1i -Returns the overall size in the specified -.PN XCharStruct -structure. -.LP -.eM -The -.PN XTextExtents -and -.PN XTextExtents16 -functions -perform the size computation locally and, thereby, -avoid the round-trip overhead of -.PN XQueryTextExtents -and -.PN XQueryTextExtents16 . -Both functions return an -.PN XCharStruct -structure, whose members are set to the values as follows. -.LP -The ascent member is set to the maximum of the ascent metrics of all -characters in the string. -The descent member is set to the maximum of the descent metrics. -The width member is set to the sum of the character-width metrics of all -characters in the string. -For each character in the string, -let W be the sum of the character-width metrics of all characters preceding -it in the string. -Let L be the left-side-bearing metric of the character plus W. -Let R be the right-side-bearing metric of the character plus W. -The lbearing member is set to the minimum L of all characters in the string. -The rbearing member is set to the maximum R. -.LP -For fonts defined with linear indexing rather than 2-byte matrix indexing, -each -.PN XChar2b -structure is interpreted as a 16-bit number with byte1 as the -most significant byte. -If the font has no defined default character, -undefined characters in the string are taken to have all zero metrics. -.NH 3 -Querying Character String Sizes -.XS -\*(SN Querying Character String Sizes -.XE -.LP -To query the server for the bounding box of an 8-bit character string in a -given font, use -.PN XQueryTextExtents . -.IN "XQueryTextExtents" "" "@DEF@" -.sM -.FD 0 -XQueryTextExtents\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \ -\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, -.br - \fIfont_descent_return\fP, \fIoverall_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIfont_ID\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInchars\fP\^; -.br - int *\fIdirection_return\fP\^; -.br - int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; -.br - XCharStruct *\fIoverall_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfont_ID\fP 1i -Specifies either the font ID or the -.PN GContext -ID that contains the font. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInchars\fP 1i -Specifies the number of characters in the character string. -.IP \fIdirection_return\fP 1i -Returns the value of the direction hint -.Pn ( FontLeftToRight -or -.PN FontRightToLeft ). -.IP \fIfont_ascent_return\fP 1i -Returns the font ascent. -.IP \fIfont_descent_return\fP 1i -Returns the font descent. -.IP \fIoverall_return\fP 1i -Returns the overall size in the specified -.PN XCharStruct -structure. -.LP -.eM -.sp -To query the server for the bounding box of a 2-byte character string -in a given font, use -.PN XQueryTextExtents16 . -.IN "XQueryTextExtents16" "" "@DEF@" -.sM -.FD 0 -XQueryTextExtents16\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \ -\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, -.br - \fIfont_descent_return\fP, \fIoverall_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIfont_ID\fP\^; -.br - XChar2b *\fIstring\fP\^; -.br - int \fInchars\fP\^; -.br - int *\fIdirection_return\fP\^; -.br - int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; -.br - XCharStruct *\fIoverall_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfont_ID\fP 1i -Specifies either the font ID or the -.PN GContext -ID that contains the font. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInchars\fP 1i -Specifies the number of characters in the character string. -.IP \fIdirection_return\fP 1i -Returns the value of the direction hint -.Pn ( FontLeftToRight -or -.PN FontRightToLeft ). -.IP \fIfont_ascent_return\fP 1i -Returns the font ascent. -.IP \fIfont_descent_return\fP 1i -Returns the font descent. -.IP \fIoverall_return\fP 1i -Returns the overall size in the specified -.PN XCharStruct -structure. -.LP -.eM -The -.PN XQueryTextExtents -and -.PN XQueryTextExtents16 -functions return the bounding box of the specified 8-bit and 16-bit -character string in the specified font or the font contained in the -specified GC. -These functions query the X server and, therefore, suffer the round-trip -overhead that is avoided by -.PN XTextExtents -and -.PN XTextExtents16 . -Both functions return a -.PN XCharStruct -structure, whose members are set to the values as follows. -.LP -The ascent member is set to the maximum of the ascent metrics -of all characters in the string. -The descent member is set to the maximum of the descent metrics. -The width member is set to the sum of the character-width metrics -of all characters in the string. -For each character in the string, -let W be the sum of the character-width metrics of all characters preceding -it in the string. -Let L be the left-side-bearing metric of the character plus W. -Let R be the right-side-bearing metric of the character plus W. -The lbearing member is set to the minimum L of all characters in the string. -The rbearing member is set to the maximum R. -.LP -For fonts defined with linear indexing rather than 2-byte matrix indexing, -each -.PN XChar2b -structure is interpreted as a 16-bit number with byte1 as the -most significant byte. -If the font has no defined default character, -undefined characters in the string are taken to have all zero metrics. -.LP -Characters with all zero metrics are ignored. -If the font has no defined default_char, -the undefined characters in the string are also ignored. -.LP -.PN XQueryTextExtents -and -.PN XQueryTextExtents16 -can generate -.PN BadFont -and -.PN BadGC -errors. -.NH 2 -Drawing Text -.XS -\*(SN Drawing Text -.XE -.LP -This section discusses how to draw: -.IP \(bu 5 -Complex text -.IP \(bu 5 -Text characters -.IP \(bu 5 -Image text characters -.LP -The fundamental text functions -.PN XDrawText -and -.PN XDrawText16 -use the following structures: -.LP -.IN "XTextItem" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - char *chars; /* pointer to string */ - int nchars; /* number of characters */ - int delta; /* delta between strings */ - Font font; /* Font to print it in, None don't change */ -} XTextItem; -.De -.LP -.IN "XTextItem16" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - XChar2b *chars; /* pointer to two-byte characters */ - int nchars; /* number of characters */ - int delta; /* delta between strings */ - Font font; /* font to print it in, None don't change */ -} XTextItem16; -.De -.LP -.eM -If the font member is not -.PN None , -the font is changed before printing and also is stored in the GC. -If an error was generated during text drawing, -the previous items may have been drawn. -The baseline of the characters are drawn starting at the x and y -coordinates that you pass in the text drawing functions. -.LP -For example, consider the background rectangle drawn by -.PN XDrawImageString . -If you want the upper-left corner of the background rectangle -to be at pixel coordinate (x,y), pass the (x,y + ascent) -as the baseline origin coordinates to the text functions. -The ascent is the font ascent, as given in the -.PN XFontStruct -structure. -If you want the lower-left corner of the background rectangle -to be at pixel coordinate (x,y), pass the (x,y \- descent + 1) -as the baseline origin coordinates to the text functions. -The descent is the font descent, as given in the -.PN XFontStruct -structure. -.NH 3 -Drawing Complex Text -.XS -\*(SN Drawing Complex Text -.XE -.LP -.IN "Text" "drawing" -.IN "Drawing" "text items" -.LP -To draw 8-bit characters in a given drawable, use -.PN XDrawText . -.IN "XDrawText" "" "@DEF@" -.sM -.FD 0 -XDrawText\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - XTextItem *\fIitems\fP\^; -.br - int \fInitems\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the specified drawable \ -and define the origin of the first character -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIitems\fP 1i -Specifies an array of text items. -.IP \fInitems\fP 1i -Specifies the number of text items in the array. -.LP -.eM -.sp -To draw 2-byte characters in a given drawable, use -.PN XDrawText16 . -.IN "XDrawText16" "" "@DEF@" -.sM -.FD 0 -XDrawText16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - XTextItem16 *\fIitems\fP\^; -.br - int \fInitems\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the specified drawable \ -and define the origin of the first character -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIitems\fP 1i -Specifies an array of text items. -.IP \fInitems\fP 1i -Specifies the number of text items in the array. -.LP -.eM -The -.PN XDrawText16 -function is similar to -.PN XDrawText -except that it uses 2-byte or 16-bit characters. -Both functions allow complex spacing and font shifts between counted strings. -.LP -Each text item is processed in turn. -A font member other than -.PN None -in an item causes the font to be stored in the GC -and used for subsequent text. -A text element delta specifies an additional change -in the position along the x axis before the string is drawn. -The delta is always added to the character origin -and is not dependent on any characteristics of the font. -Each character image, as defined by the font in the GC, is treated as an -additional mask for a fill operation on the drawable. -The drawable is modified only where the font character has a bit set to 1. -If a text item generates a -.PN BadFont -error, the previous text items may have been drawn. -.LP -For fonts defined with linear indexing rather than 2-byte matrix indexing, -each -.PN XChar2b -structure is interpreted as a 16-bit number with byte1 as the -most significant byte. -.LP -Both functions use these GC components: -function, plane-mask, fill-style, font, subwindow-mode, -clip-x-origin, clip-y-origin, and clip-mask. -They also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -and tile-stipple-y-origin. -.LP -.PN XDrawText -and -.PN XDrawText16 -can generate -.PN BadDrawable , -.PN BadFont , -.PN BadGC , -and -.PN BadMatch -errors. -.NH 3 -Drawing Text Characters -.XS -\*(SN Drawing Text Characters -.XE -.LP -.IN "Strings" "drawing" -.IN "Drawing" "strings" -To draw 8-bit characters in a given drawable, use -.PN XDrawString . -.IN "XDrawString" "" "@DEF@" -.sM -.FD 0 -XDrawString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the specified drawable \ -and define the origin of the first character -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fIlength\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -.sp -To draw 2-byte characters in a given drawable, use -.PN XDrawString16 . -.IN "XDrawString16" "" "@DEF@" -.sM -.FD 0 -XDrawString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - XChar2b *\fIstring\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the specified drawable \ -and define the origin of the first character -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fIlength\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -Each character image, as defined by the font in the GC, is treated as an -additional mask for a fill operation on the drawable. -The drawable is modified only where the font character has a bit set to 1. -For fonts defined with 2-byte matrix indexing -and used with -.PN XDrawString16 , -each byte is used as a byte2 with a byte1 of zero. -.LP -Both functions use these GC components: -function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, -clip-y-origin, and clip-mask. -They also use these GC mode-dependent components: -foreground, background, tile, stipple, tile-stipple-x-origin, -and tile-stipple-y-origin. -.LP -.PN XDrawString -and -.PN XDrawString16 -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.NH 3 -Drawing Image Text Characters -.XS -\*(SN Drawing Image Text Characters -.XE -.LP -.IN "Image text" "drawing" -.IN "Drawing" "image text" -Some applications, in particular terminal emulators, need to -print image text in which both the foreground and background bits of -each character are painted. -This prevents annoying flicker on many displays. -.IN "XDrawImageString" -.IN "XDrawImageString16" -.LP -.sp -To draw 8-bit image text characters in a given drawable, use -.PN XDrawImageString . -.IN "XDrawImageString" "" "@DEF@" -.sM -.FD 0 -XDrawImageString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the specified drawable \ -and define the origin of the first character -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fIlength\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -.sp -To draw 2-byte image text characters in a given drawable, use -.PN XDrawImageString16 . -.IN "XDrawImageString16" "" "@DEF@" -.sM -.FD 0 -XDrawImageString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - XChar2b *\fIstring\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy , which are relative to the origin of the specified drawable \ -and define the origin of the first character -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fIlength\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -The -.PN XDrawImageString16 -function is similar to -.PN XDrawImageString -except that it uses 2-byte or 16-bit characters. -Both functions also use both the foreground and background pixels -of the GC in the destination. -.LP -The effect is first to fill a -destination rectangle with the background pixel defined in the GC and then -to paint the text with the foreground pixel. -The upper-left corner of the filled rectangle is at: -.LP -.Ds -[x, y \- font-ascent] -.De -.LP -The width is: -.LP -.Ds -overall-width -.De -.LP -The height is: -.LP -.Ds -font-ascent + font-descent -.De -.LP -The overall-width, font-ascent, and font-descent -are as would be returned by -.PN XQueryTextExtents -using gc and string. -The function and fill-style defined in the GC are ignored for these functions. -The effective function is -.PN GXcopy , -and the effective fill-style is -.PN FillSolid . -.LP -For fonts defined with 2-byte matrix indexing -and used with -.PN XDrawImageString , -each byte is used as a byte2 with a byte1 of zero. -.LP -Both functions use these GC components: -plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, -clip-y-origin, and clip-mask. -.LP -.PN XDrawImageString -and -.PN XDrawImageString16 -can generate -.PN BadDrawable , -.PN BadGC , -and -.PN BadMatch -errors. -.LP -.NH 2 -Transferring Images between Client and Server -.XS -\*(SN Transferring Images between Client and Server -.XE -.LP -Xlib provides functions that you can use to transfer images between a client -and the server. -Because the server may require diverse data formats, -Xlib provides an image object that fully describes the data in memory -and that provides for basic operations on that data. -You should reference the data -through the image object rather than referencing the data directly. -However, some implementations of the Xlib library may efficiently deal with -frequently used data formats by replacing -functions in the procedure vector with special case functions. -Supported operations include destroying the image, getting a pixel, -storing a pixel, extracting a subimage of an image, and adding a constant -to an image (see section 16.8). -.LP -All the image manipulation functions discussed in this section make use of -the -.PN XImage -structure, -which describes an image as it exists in the client's memory. -.LP -.IN "XImage" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 1i 3i -.ta .5i 1i 3i -typedef struct _XImage { - int width, height; /* size of image */ - int xoffset; /* number of pixels offset in X direction */ - int format; /* XYBitmap, XYPixmap, ZPixmap */ - char *data; /* pointer to image data */ - int byte_order; /* data byte order, LSBFirst, MSBFirst */ - int bitmap_unit; /* quant. of scanline 8, 16, 32 */ - int bitmap_bit_order; /* LSBFirst, MSBFirst */ - int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ - int depth; /* depth of image */ - int bytes_per_line; /* accelerator to next scanline */ - int bits_per_pixel; /* bits per pixel (ZPixmap) */ - unsigned long red_mask; /* bits in z arrangement */ - unsigned long green_mask; - unsigned long blue_mask; - XPointer obdata; /* hook for the object routines to hang on */ - struct funcs { /* image manipulation routines */ - struct _XImage *(*create_image)(); - int (*destroy_image)(); - unsigned long (*get_pixel)(); - int (*put_pixel)(); - struct _XImage *(*sub_image)(); - int (*add_pixel)(); - } f; -} XImage; -.De -.LP -.eM -.sp -To initialize the image manipulation routines of an image structure, use -.PN XInitImage . -.IN "XInitImage" "" "@DEF@" -.sM -.FD 0 -Status XInitImage\^(\^\fIimage\fP\^) -.br - XImage *\fIimage\fP\^; -.FN -.IP \fIximage\fP 1i -Specifies the image. -.LP -.eM -The -.PN XInitImage -function initializes the internal image manipulation routines of an -image structure, based on the values of the various structure members. -All fields other than the manipulation routines must already be initialized. -If the bytes_per_line member is zero, -.PN XInitImage -will assume the image data is contiguous in memory and set the -bytes_per_line member to an appropriate value based on the other -members; otherwise, the value of bytes_per_line is not changed. -All of the manipulation routines are initialized to functions -that other Xlib image manipulation functions need to operate on the -type of image specified by the rest of the structure. -.LP -This function must be called for any image constructed by the client -before passing it to any other Xlib function. -Image structures created or returned by Xlib do not need to be -initialized in this fashion. -.LP -This function returns a nonzero status if initialization of the -structure is successful. It returns zero if it detected some error -or inconsistency in the structure, in which case the image is not changed. -.LP -.sp -To combine an image with a rectangle of a drawable on the display, -use -.PN XPutImage . -.IN "XPutImage" "" "@DEF@" -.sM -.FD 0 -XPutImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIimage\fP\^, \fIsrc_x\fP, \fIsrc_y\fP, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - XImage *\fIimage\fP\^; -.br - int \fIsrc_x\fP\^, \fIsrc_y\fP\^; -.br - int \fIdest_x\fP\^, \fIdest_y\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIimage\fP 1i -Specifies the image you want combined with the rectangle. -.IP \fIsrc_x\fP 1i -Specifies the offset in X from the left edge of the image defined -by the -.PN XImage -structure. -.IP \fIsrc_y\fP 1i -Specifies the offset in Y from the top edge of the image defined -by the -.PN XImage -structure. -.ds Dx , which are relative to the origin of the drawable \ -and are the coordinates of the subimage -.IP \fIdest_x\fP 1i -.br -.ns -.IP \fIdest_y\fP 1i -Specify the x and y coordinates\*(Dx. -.ds Wh \ of the subimage, which define the dimensions of the rectangle -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.LP -.eM -The -.PN XPutImage -function -combines an image with a rectangle of the specified drawable. -The section of the image defined by the src_x, src_y, width, and height -arguments is drawn on the specified part of the drawable. -If -.PN XYBitmap -format is used, the depth of the image must be one, -or a -.PN BadMatch -error results. -The foreground pixel in the GC defines the source for the one bits in the image, -and the background pixel defines the source for the zero bits. -For -.PN XYPixmap -and -.PN ZPixmap , -the depth of the image must match the depth of the drawable, -or a -.PN BadMatch -error results. -.LP -If the characteristics of the image (for example, byte_order and bitmap_unit) -differ from what the server requires, -.PN XPutImage -automatically makes the appropriate -conversions. -.LP -This function uses these GC components: -function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, -and clip-mask. -It also uses these GC mode-dependent components: -foreground and background. -.LP -.PN XPutImage -can generate -.PN BadDrawable , -.PN BadGC , -.PN BadMatch , -and -.PN BadValue -errors. -.LP -.sp -To return the contents of a rectangle in a given drawable on the display, -use -.PN XGetImage . -This function specifically supports rudimentary screen dumps. -.IN "XGetImage" "" "@DEF@" -.sM -.FD 0 -XImage *XGetImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned long \fIplane_mask\fP\^; -.br - int \fIformat\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.ds Xy , which are relative to the origin of the drawable \ -and define the upper-left corner of the rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh \ of the subimage, which define the dimensions of the rectangle -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIplane_mask\fP 1i -Specifies the plane mask. -.\" *** JIM: NEED MORE INFO FOR THIS. *** -.IP \fIformat\fP 1i -Specifies the format for the image. -You can pass -.PN XYPixmap -or -.PN ZPixmap . -.LP -.eM -The -.PN XGetImage -function returns a pointer to an -.PN XImage -structure. -This structure provides you with the contents of the specified rectangle of -the drawable in the format you specify. -If the format argument is -.PN XYPixmap , -the image contains only the bit planes you passed to the plane_mask argument. -If the plane_mask argument only requests a subset of the planes of the -display, the depth of the returned image will be the number of planes -requested. -If the format argument is -.PN ZPixmap , -.PN XGetImage -returns as zero the bits in all planes not -specified in the plane_mask argument. -The function performs no range checking on the values in plane_mask and ignores -extraneous bits. -.LP -.PN XGetImage -returns the depth of the image to the depth member of the -.PN XImage -structure. -The depth of the image is as specified when the drawable was created, -except when getting a subset of the planes in -.PN XYPixmap -format, when the depth is given by the number of bits set to 1 in plane_mask. -.LP -If the drawable is a pixmap, -the given rectangle must be wholly contained within the pixmap, -or a -.PN BadMatch -error results. -If the drawable is a window, -the window must be viewable, -and it must be the case that if there were no inferiors or overlapping windows, -the specified rectangle of the window would be fully visible on the screen -and wholly contained within the outside edges of the window, -or a -.PN BadMatch -error results. -Note that the borders of the window can be included and read with -this request. -If the window has backing-store, the backing-store contents are -returned for regions of the window that are obscured by noninferior -windows. -If the window does not have backing-store, -the returned contents of such obscured regions are undefined. -The returned contents of visible regions of inferiors -of a different depth than the specified window's depth are also undefined. -The pointer cursor image is not included in the returned contents. -If a problem occurs, -.PN XGetImage -returns NULL. -.LP -.PN XGetImage -can generate -.PN BadDrawable , -.PN BadMatch , -and -.PN BadValue -errors. -.sp -.LP -To copy the contents of a rectangle on the display -to a location within a preexisting image structure, use -.PN XGetSubImage . -.IN "XGetSubImage" "" "@DEF@" -.sM -.FD 0 -XImage *XGetSubImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^, \fIdest_image\fP\^, \fIdest_x\fP\^, -.br - \fIdest_y\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned long \fIplane_mask\fP\^; -.br - int \fIformat\fP\^; -.br - XImage *\fIdest_image\fP\^; -.br - int \fIdest_x\fP\^, \fIdest_y\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.ds Xy , which are relative to the origin of the drawable \ -and define the upper-left corner of the rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh \ of the subimage, which define the dimensions of the rectangle -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIplane_mask\fP 1i -Specifies the plane mask. -.\" *** JIM: NEED MORE INFO FOR THIS. *** -.IP \fIformat\fP 1i -Specifies the format for the image. -You can pass -.PN XYPixmap -or -.PN ZPixmap . -.IP \fIdest_image\fP 1i -Specifies the destination image. -.ds Dx , which are relative to the origin of the destination rectangle, \ -specify its upper-left corner, and determine where the subimage \ -is placed in the destination image -.IP \fIdest_x\fP 1i -.br -.ns -.IP \fIdest_y\fP 1i -Specify the x and y coordinates\*(Dx. -.LP -.eM -The -.PN XGetSubImage -function updates dest_image with the specified subimage in the same manner as -.PN XGetImage . -If the format argument is -.PN XYPixmap , -the image contains only the bit planes you passed to the plane_mask argument. -If the format argument is -.PN ZPixmap , -.PN XGetSubImage -returns as zero the bits in all planes not -specified in the plane_mask argument. -The function performs no range checking on the values in plane_mask and ignores -extraneous bits. -As a convenience, -.PN XGetSubImage -returns a pointer to the same -.PN XImage -structure specified by dest_image. -.LP -The depth of the destination -.PN XImage -structure must be the same as that of the drawable. -If the specified subimage does not fit at the specified location -on the destination image, the right and bottom edges are clipped. -If the drawable is a pixmap, -the given rectangle must be wholly contained within the pixmap, -or a -.PN BadMatch -error results. -If the drawable is a window, -the window must be viewable, -and it must be the case that if there were no inferiors or overlapping windows, -the specified rectangle of the window would be fully visible on the screen -and wholly contained within the outside edges of the window, -or a -.PN BadMatch -error results. -If the window has backing-store, -then the backing-store contents are returned for regions of the window -that are obscured by noninferior windows. -If the window does not have backing-store, -the returned contents of such obscured regions are undefined. -The returned contents of visible regions of inferiors -of a different depth than the specified window's depth are also undefined. -If a problem occurs, -.PN XGetSubImage -returns NULL. -.LP -.PN XGetSubImage -can generate -.PN BadDrawable , -.PN BadGC , -.PN BadMatch , -and -.PN BadValue -errors. -.bp diff --git a/libX11/specs/libX11/CH08.xml b/libX11/specs/libX11/CH08.xml new file mode 100644 index 000000000..5f08f93f3 --- /dev/null +++ b/libX11/specs/libX11/CH08.xml @@ -0,0 +1,5960 @@ +<chapter id="graphics_functions">
+<title>Graphics Functions</title>
+<para>
+Once you have established a connection to a display, you can use the Xlib graphics functions to:
+</para>
+<itemizedlist>
+ <listitem><para>Clear and copy areas</para></listitem>
+ <listitem><para>Draw points, lines, rectangles, and arcs</para></listitem>
+ <listitem><para>Fill areas</para></listitem>
+ <listitem><para>Manipulate fonts</para></listitem>
+ <listitem><para>Draw text</para></listitem>
+ <listitem><para>Transfer images between clients and the server</para></listitem>
+</itemizedlist>
+<para>
+If the same drawable and GC is used for each call, Xlib batches back-to-back calls to XDraw-
+Point, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle. Note that this reduces
+the total number of requests sent to the server.
+</para>
+<sect1 id="Clearing_Areas">
+<title>Clearing Areas</title>
+<!-- .XS -->
+<!-- (SN Clearing Areas -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to clear an area or the entire window.
+Because pixmaps do not have defined backgrounds,
+they cannot be filled by using the functions described in this section.
+Instead, to accomplish an analogous operation on a pixmap,
+you should use
+<function>XFillRectangle</function>,
+which sets the pixmap to a known value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear a rectangular area of a given window, use
+<function>XClearArea</function>.
+<indexterm><primary>Areas</primary><secondary>clearing</secondary></indexterm>
+<indexterm><primary>Clearing</primary><secondary>areas</secondary></indexterm>
+<indexterm significance="preferred"><primary>XClearArea</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XClearArea</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>Bool<parameter> exposures</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+<!-- .ds Xy , which are relative to the origin of the window \ -->
+and specify the upper-left corner of the rectangle
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the dimensions of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>exposures</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates if
+<function>Expose</function>
+events are to be generated.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XClearArea</function>
+function paints a rectangular area in the specified window according to the
+specified dimensions with the window's background pixel or pixmap.
+The subwindow-mode effectively is
+<function>ClipByChildren</function>.
+If width is zero, it
+is replaced with the current width of the window minus x.
+If height is
+zero, it is replaced with the current height of the window minus y.
+If the window has a defined background tile,
+the rectangle clipped by any children is filled with this tile.
+If the window has
+background
+<function>None</function>,
+the contents of the window are not changed.
+In either
+case, if exposures is
+<function>True</function>,
+one or more
+<function>Expose </function>
+events are generated for regions of the rectangle that are either visible or are
+being retained in a backing store.
+If you specify a window whose class is
+<function>InputOnly</function>,
+a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XClearArea</function>
+can generate
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear the entire area in a given window, use
+<function>XClearWindow</function>.
+<indexterm><primary>Window</primary><secondary>clearing</secondary></indexterm>
+<indexterm><primary>Clearing</primary><secondary>windows</secondary></indexterm>
+<indexterm significance="preferred"><primary>XClearWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XClearWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XClearWindow</function>
+function clears the entire area in the specified window and is
+equivalent to
+<function>XClearArea</function>
+(display, w, 0, 0, 0, 0,
+<function>False</function>).
+If the window has a defined background tile, the rectangle is tiled with a
+plane-mask of all ones and
+<function>GXcopy</function>
+function.
+If the window has
+background
+<function>None</function>,
+the contents of the window are not changed.
+If you specify a window whose class is
+<function>InputOnly</function>,
+a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XClearWindow</function>
+can generate
+<function>BadMatch</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Copying_Areas">
+<title>Copying Areas</title>
+<!-- .XS -->
+<!-- (SN Copying Areas -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to copy an area or a bit plane.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To copy an area between drawables of the same
+root and depth, use
+<function>XCopyArea</function>.
+<indexterm><primary>Areas</primary><secondary>copying</secondary></indexterm>
+<indexterm><primary>Copying</primary><secondary>areas</secondary></indexterm>
+<indexterm significance="preferred"><primary>XCopyArea</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XCopyArea</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the source and destination rectangles to be combined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates,
+which are relative to the origin of the source rectangle
+and specify its upper-left corner.
+<!-- .ds Wh , which are the dimensions of both the source \ -->
+and destination rectangles
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->
+and specify its upper-left corner
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Dx.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyArea</function>
+function combines the specified rectangle of src with the specified rectangle
+of dest.
+The drawables must have the same root and depth,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If regions of the source rectangle are obscured and have not been
+retained in backing store
+or if regions outside the boundaries of the source drawable are specified,
+those regions are not copied.
+Instead, the
+following occurs on all corresponding destination regions that are either
+visible or are retained in backing store.
+If the destination is a window with a background other than
+<function>None</function>,
+corresponding regions
+of the destination are tiled with that background
+(with plane-mask of all ones and
+<function>GXcopy </function>
+function).
+Regardless of tiling or whether the destination is a window or a pixmap,
+if graphics-exposures is
+<function>True</function>,
+then
+<function>GraphicsExpose</function>
+events for all corresponding destination regions are generated.
+If graphics-exposures is
+<function>True </function>
+but no
+<function>GraphicsExpose</function>
+events are generated, a
+<function>NoExpose </function>
+event is generated.
+Note that by default graphics-exposures is
+<function>True</function>
+in new GCs.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components: function, plane-mask,
+subwindow-mode, graphics-exposures, clip-x-origin,
+clip-y-origin, and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyArea</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To copy a single bit plane of a given drawable, use
+<function>XCopyPlane</function>.
+<indexterm><primary>Plane</primary><secondary>copying</secondary></indexterm>
+<indexterm><primary>Copying</primary><secondary>planes</secondary></indexterm>
+<indexterm significance="preferred"><primary>XCopyPlane</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XCopyPlane</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> plane</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the source and destination rectangles to be combined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates,
+which are relative to the origin of the source rectangle
+and specify its upper-left corner.
+<!-- .ds Wh , which are the dimensions of both the source and destination rectangles -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->
+and specify its upper-left corner
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Dx.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>plane</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the bit plane.
+You must set exactly one bit to 1.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyPlane</function>
+function uses a single bit plane of the specified source rectangle
+combined with the specified GC to modify the specified rectangle of dest.
+The drawables must have the same root but need not have the same depth.
+If the drawables do not have the same root, a
+<function>BadMatch</function>
+error results.
+If plane does not have exactly one bit set to 1 and the value of plane
+is not less than %2 sup n%, where <emphasis remap='I'>n</emphasis> is the depth of src, a
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+Effectively,
+<function>XCopyPlane</function>
+forms a pixmap of the same depth as the rectangle of dest and with a
+size specified by the source region.
+It uses the foreground/background pixels in the GC (foreground
+everywhere the bit plane in src contains a bit set to 1,
+background everywhere the bit plane in src contains a bit set to 0)
+and the equivalent of a
+<function>CopyArea</function>
+protocol request is performed with all the same exposure semantics.
+This can also be thought of as using the specified region of the source
+bit plane as a stipple with a fill-style of
+<function>FillOpaqueStippled</function>
+for filling a rectangular area of the destination.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components: function, plane-mask, foreground,
+background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
+and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyPlane</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Drawing_Points_Lines_Rectangles_and_Arcs">
+<title>Drawing Points, Lines, Rectangles, and Arcs</title>
+<!-- .XS -->
+<!-- (SN Drawing Points, Lines, Rectangles, and Arcs -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to draw:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A single point or multiple points
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A single line or multiple lines
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A single rectangle or multiple rectangles
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A single arc or multiple arcs
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Some of the functions described in the following sections
+use these structures:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSegment</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ short x1, y1, x2, y2;
+} XSegment;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XPoint</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ short x, y;
+} XPoint;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XRectangle</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ short x, y;
+ unsigned short width, height;
+} XRectangle;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XArc</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ short x, y;
+ unsigned short width, height;
+ short angle1, angle2; /* Degrees * 64 */
+} XArc;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+All x and y members are signed integers.
+The width and height members are 16-bit unsigned integers.
+You should be careful not to generate coordinates and sizes
+out of the 16-bit ranges, because the protocol only has 16-bit fields
+for these values.
+</para>
+<sect2 id="Drawing_Single_and_Multiple_Points">
+<title>Drawing Single and Multiple Points</title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Points -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Points</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>points</secondary></indexterm>
+<indexterm><primary>XDrawPoints</primary></indexterm>
+<indexterm><primary>XDrawPoint</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw a single point in a given drawable, use
+<function>XDrawPoint</function>.
+<indexterm significance="preferred"><primary>XDrawPoint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawPoint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates where you want the point drawn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple points in a given drawable, use
+<function>XDrawPoints</function>.
+<indexterm significance="preferred"><primary>XDrawPoints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawPoints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XPoint<parameter> *points</parameter></paramdef>
+ <paramdef>int<parameter> npoints</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>points</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of points.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npoints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of points in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the coordinate mode.
+You can pass
+<function>CoordModeOrigin</function>
+or
+<function>CoordModePrevious</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawPoint</function>
+function uses the foreground pixel and function components of the
+GC to draw a single point into the specified drawable;
+<function>XDrawPoints</function>
+draws multiple points this way.
+<function>CoordModeOrigin</function>
+treats all coordinates as relative to the origin,
+and
+<function>CoordModePrevious</function>
+treats all coordinates after the first as relative to the previous point.
+<function>XDrawPoints</function>
+draws the points in the order listed in the array.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: function, plane-mask,
+foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawPoint</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+<function>XDrawPoints</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Single_and_Multiple_Lines">
+<title>Drawing Single and Multiple Lines</title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Lines -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Lines</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>lines</secondary></indexterm>
+<indexterm><primary>XDrawLine</primary></indexterm>
+<indexterm><primary>XDrawLines</primary></indexterm>
+<indexterm><primary>Polygons</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>polygons</secondary></indexterm>
+<indexterm><primary>XDrawSegments</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw a single line between two points in a given drawable, use
+<function>XDrawLine</function>.
+<indexterm significance="preferred"><primary>XDrawLine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawLine</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx1,y1,x2,<parameter> y2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x1</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y1</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x2</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the points (x1, y1) and (x2, y2) to be connected.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple lines in a given drawable, use
+<function>XDrawLines</function>.
+<indexterm significance="preferred"><primary>XDrawLines</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawLines</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XPoint<parameter> *points</parameter></paramdef>
+ <paramdef>int<parameter> npoints</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>points</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of points.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npoints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of points in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the coordinate mode.
+You can pass
+<function>CoordModeOrigin</function>
+or
+<function>CoordModePrevious</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple, unconnected lines in a given drawable,
+use
+<function>XDrawSegments</function>.
+<indexterm significance="preferred"><primary>XDrawSegments</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawSegments</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XSegment<parameter> *segments</parameter></paramdef>
+ <paramdef>int<parameter> nsegments</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>segments</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of segments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nsegments</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of segments in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawLine</function>
+function uses the components of the specified GC to
+draw a line between the specified set of points (x1, y1) and (x2, y2).
+It does not perform joining at coincident endpoints.
+For any given line,
+<function>XDrawLine </function>
+does not draw a pixel more than once.
+If lines intersect, the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XDrawLines</function>
+function uses the components of the specified GC to draw
+npoints-1 lines between each pair of points (point[i], point[i+1])
+in the array of
+<function>XPoint</function>
+structures.
+It draws the lines in the order listed in the array.
+The lines join correctly at all intermediate points, and if the first and last
+points coincide, the first and last lines also join correctly.
+For any given line,
+<function>XDrawLines</function>
+does not draw a pixel more than once.
+If thin (zero line-width) lines intersect,
+the intersecting pixels are drawn multiple times.
+If wide lines intersect, the intersecting pixels are drawn only once, as though
+the entire
+<function>PolyLine </function>
+protocol request were a single, filled shape.
+<function>CoordModeOrigin</function>
+treats all coordinates as relative to the origin,
+and
+<function>CoordModePrevious</function>
+treats all coordinates after the first as relative to the previous point.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XDrawSegments </function>
+function draws multiple, unconnected lines.
+For each segment,
+<function>XDrawSegments </function>
+draws a
+line between (x1, y1) and (x2, y2).
+It draws the lines in the order listed in the array of
+<function>XSegment</function>
+structures and does not perform joining at coincident endpoints.
+For any given line,
+<function>XDrawSegments</function>
+does not draw a pixel more than once.
+If lines intersect, the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+All three functions use these GC components:
+function, plane-mask, line-width,
+line-style, cap-style, fill-style, subwindow-mode,
+clip-x-origin, clip-y-origin, and clip-mask.
+The
+<function>XDrawLines</function>
+function also uses the join-style GC component.
+All three functions also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawLine</function>,
+<function>XDrawLines</function>,
+and
+<function>XDrawSegments</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+<function>XDrawLines</function>
+also can generate
+<function>BadValue </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Single_and_Multiple_Rectangles_">
+<title>Drawing Single and Multiple Rectangles </title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Rectangles -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Rectangles</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>rectangles</secondary></indexterm>
+<indexterm><primary>XDrawRectangle</primary></indexterm>
+<indexterm><primary>XDrawRectangles</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw the outline of a single rectangle in a given drawable, use
+<function>XDrawRectangle</function>.
+<indexterm significance="preferred"><primary>XDrawRectangle</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawRectangle</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which specify the upper-left corner of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which specify the dimensions of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw the outline of multiple rectangles
+in a given drawable, use
+<function>XDrawRectangles</function>.
+<indexterm significance="preferred"><primary>XDrawRectangles</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawRectangles</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>
+ <paramdef>int<parameter> nrectangles</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rectangles</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of rectangles.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nrectangles</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of rectangles in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawRectangle</function>
+and
+<function>XDrawRectangles</function>
+functions draw the outlines of the specified rectangle or rectangles as
+if a five-point
+<function>PolyLine </function>
+protocol request were specified for each rectangle:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For the specified rectangle or rectangles,
+these functions do not draw a pixel more than once.
+<function>XDrawRectangles</function>
+draws the rectangles in the order listed in the array.
+If rectangles intersect,
+the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, line-width,
+line-style, cap-style, join-style, fill-style,
+subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawRectangle</function>
+and
+<function>XDrawRectangles</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Single_and_Multiple_Arcs">
+<title>Drawing Single and Multiple Arcs</title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Arcs -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Drawing</primary><secondary>arcs</secondary></indexterm>
+<indexterm><primary>XDrawArc</primary></indexterm>
+<indexterm><primary>Arcs</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>XDrawArcs</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw a single arc in a given drawable, use
+<function>XDrawArc</function>.
+<indexterm significance="preferred"><primary>XDrawArc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawArc</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>intangle1,<parameter> angle2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and specify the upper-left corner of the bounding rectangle
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the major and minor axes of the arc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>angle1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the start of the arc relative to the three-o'clock position
+from the center, in units of degrees * 64.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>angle2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the path and extent of the arc relative to the start of the
+arc, in units of degrees * 64.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple arcs in a given drawable, use
+<function>XDrawArcs</function>.
+<indexterm significance="preferred"><primary>XDrawArcs</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawArcs</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XArc<parameter> *arcs</parameter></paramdef>
+ <paramdef>int<parameter> narcs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arcs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of arcs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>narcs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arcs in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+<function>XDrawArc</function>
+draws a single circular or elliptical arc, and
+<function>XDrawArcs</function>
+draws multiple circular or elliptical arcs.
+Each arc is specified by a rectangle and two angles.
+The center of the circle or ellipse is the center of the
+rectangle, and the major and minor axes are specified by the width and height.
+Positive angles indicate counterclockwise motion,
+and negative angles indicate clockwise motion.
+If the magnitude of angle2 is greater than 360 degrees,
+<function>XDrawArc</function>
+or
+<function>XDrawArcs</function>
+truncates it to 360 degrees.
+</para>
+<para>
+<!-- .LP -->
+For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%,
+the origin of the major and minor axes is at
+% [ x +^ {width over 2} , ~y +^ {height over 2} ]%,
+and the infinitely thin path describing the entire circle or ellipse
+intersects the horizontal axis at % [ x, ~y +^ {height over 2} ]% and
+% [ x +^ width , ~y +^ { height over 2 }] %
+and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and
+% [ x +^ { width over 2 }, ~y +^ height ]%.
+These coordinates can be fractional
+and so are not truncated to discrete coordinates.
+The path should be defined by the ideal mathematical path.
+For a wide line with line-width lw,
+the bounding outlines for filling are given
+by the two infinitely thin paths consisting of all points whose perpendicular
+distance from the path of the circle/ellipse is equal to lw/2
+(which may be a fractional value).
+The cap-style and join-style are applied the same as for a line
+corresponding to the tangent of the circle/ellipse at the endpoint.
+</para>
+<para>
+<!-- .LP -->
+For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]%,
+the angles must be specified
+in the effectively skewed coordinate system of the ellipse (for a
+circle, the angles and coordinate systems are identical). The
+relationship between these angles and angles expressed in the normal
+coordinate system of the screen (as measured with a protractor) is as
+follows:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
+ * width over height right ) +^ adjust%
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The skewed-angle and normal-angle are expressed in radians (rather
+than in degrees scaled by 64) in the range % [ 0 , ~2 pi ]% and where atan
+returns a value in the range % [ - pi over 2 , ~pi over 2 ] %
+and adjust is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 1i 2i -->
+<!-- .ta 1i 2i -->
+%0% for normal-angle in the range % [ 0 , ~pi over 2 ]%
+%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]%
+%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]%
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+For any given arc,
+<function>XDrawArc</function>
+and
+<function>XDrawArcs</function>
+do not draw a pixel more than once.
+If two arcs join correctly and if the line-width is greater than zero
+and the arcs intersect,
+<function>XDrawArc</function>
+and
+<function>XDrawArcs</function>
+do not draw a pixel more than once.
+Otherwise,
+the intersecting pixels of intersecting arcs are drawn multiple times.
+Specifying an arc with one endpoint and a clockwise extent draws the same pixels
+as specifying the other endpoint and an equivalent counterclockwise extent,
+except as it affects joins.
+</para>
+<para>
+<!-- .LP -->
+If the last point in one arc coincides with the first point in the following
+arc, the two arcs will join correctly.
+If the first point in the first arc coincides with the last point in the last
+arc, the two arcs will join correctly.
+By specifying one axis to be zero, a horizontal or vertical line can be
+drawn.
+Angles are computed based solely on the coordinate system and ignore the
+aspect ratio.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawArc</function>
+and
+<function>XDrawArcs</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Filling_Areas">
+<title>Filling Areas</title>
+<!-- .XS -->
+<!-- (SN Filling Areas -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to fill:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A single rectangle or multiple rectangles
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A single polygon
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A single arc or multiple arcs
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Filling_Single_and_Multiple_Rectangles">
+<title>Filling Single and Multiple Rectangles</title>
+<!-- .XS -->
+<!-- (SN Filling Single and Multiple Rectangles -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Filling</primary><secondary>rectangles</secondary></indexterm>
+<indexterm><primary>XFillRectangle</primary></indexterm>
+<indexterm><primary>Rectangle</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>XFillRectangles</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To fill a single rectangular area in a given drawable, use
+<function>XFillRectangle</function>.
+<indexterm significance="preferred"><primary>XFillRectangle</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFillRectangle</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and specify the upper-left corner of the rectangle
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the dimensions of the rectangle to be filled -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To fill multiple rectangular areas in a given drawable, use
+<function>XFillRectangles</function>.
+<indexterm significance="preferred"><primary>XFillRectangles</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFillRectangles</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>
+ <paramdef>int<parameter> nrectangles</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rectangles</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of rectangles.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nrectangles</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of rectangles in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFillRectangle</function>
+and
+<function>XFillRectangles</function>
+functions fill the specified rectangle or rectangles
+as if a four-point
+<function>FillPolygon</function>
+protocol request were specified for each rectangle:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x,y] [x+width,y] [x+width,y+height] [x,y+height]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Each function uses the x and y coordinates,
+width and height dimensions, and GC you specify.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillRectangles</function>
+fills the rectangles in the order listed in the array.
+For any given rectangle,
+<function>XFillRectangle</function>
+and
+<function>XFillRectangles</function>
+do not draw a pixel more than once.
+If rectangles intersect, the intersecting pixels are
+drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, fill-style, subwindow-mode,
+clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillRectangle</function>
+and
+<function>XFillRectangles</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Filling_a_Single_Polygon">
+<title>Filling a Single Polygon</title>
+<!-- .XS -->
+<!-- (SN Filling a Single Polygon -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To fill a polygon area in a given drawable, use
+<function>XFillPolygon</function>.
+<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm>
+<indexterm significance="preferred"><primary>XFillPolygon</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFillPolygon</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XPoint<parameter> *points</parameter></paramdef>
+ <paramdef>int<parameter> npoints</parameter></paramdef>
+ <paramdef>int<parameter> shape</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>points</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of points.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npoints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of points in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>shape</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a shape that helps the server to improve performance.
+You can pass
+<function>Complex</function>,
+<function>Convex</function>,
+or
+<function>Nonconvex</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the coordinate mode.
+You can pass
+<function>CoordModeOrigin</function>
+or
+<function>CoordModePrevious</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XFillPolygon </function>
+fills the region closed by the specified path.
+The path is closed
+automatically if the last point in the list does not coincide with the
+first point.
+<function>XFillPolygon</function>
+does not draw a pixel of the region more than once.
+<function>CoordModeOrigin</function>
+treats all coordinates as relative to the origin,
+and
+<function>CoordModePrevious</function>
+treats all coordinates after the first as relative to the previous point.
+</para>
+<para>
+<!-- .LP -->
+Depending on the specified shape, the following occurs:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If shape is
+<function>Complex</function>,
+the path may self-intersect.
+Note that contiguous coincident points in the path are not treated
+as self-intersection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If shape is
+<function>Convex</function>,
+for every pair of points inside the polygon,
+the line segment connecting them does not intersect the path.
+If known by the client,
+specifying
+<function>Convex </function>
+can improve performance.
+If you specify
+<function>Convex </function>
+for a path that is not convex,
+the graphics results are undefined.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If shape is
+<function>Nonconvex</function>,
+the path does not self-intersect, but the shape is not
+wholly convex.
+If known by the client,
+specifying
+<function>Nonconvex </function>
+instead of
+<function>Complex </function>
+may improve performance.
+If you specify
+<function>Nonconvex </function>
+for a self-intersecting path, the graphics results are undefined.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The fill-rule of the GC controls the filling behavior of
+self-intersecting polygons.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components:
+function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin,
+clip-y-origin, and clip-mask.
+It also uses these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillPolygon</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Filling_Single_and_Multiple_Arcs">
+<title>Filling Single and Multiple Arcs</title>
+<!-- .XS -->
+<!-- (SN Filling Single and Multiple Arcs -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>XFillArc</primary></indexterm>
+<indexterm><primary>Arcs</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>Filling</primary><secondary>arcs</secondary></indexterm>
+To fill a single arc in a given drawable, use
+<function>XFillArc</function>.
+<indexterm significance="preferred"><primary>XFillArc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFillArc</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>intangle1,<parameter> angle2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and specify the upper-left corner of the bounding rectangle
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the major and minor axes of the arc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>angle1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the start of the arc relative to the three-o'clock position
+from the center, in units of degrees * 64.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>angle2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the path and extent of the arc relative to the start of the
+arc, in units of degrees * 64.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To fill multiple arcs in a given drawable, use
+<function>XFillArcs</function>.
+<indexterm significance="preferred"><primary>XFillArcs</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFillArcs</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XArc<parameter> *arcs</parameter></paramdef>
+ <paramdef>int<parameter> narcs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arcs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of arcs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>narcs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arcs in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For each arc,
+<function>XFillArc</function>
+or
+<function>XFillArcs</function>
+fills the region closed by the infinitely thin path
+described by the specified arc and, depending on the
+arc-mode specified in the GC, one or two line segments.
+For
+<function>ArcChord</function>,
+the single line segment joining the endpoints of the arc is used.
+For
+<function>ArcPieSlice</function>,
+the two line segments joining the endpoints of the arc with the center
+point are used.
+<function>XFillArcs</function>
+fills the arcs in the order listed in the array.
+For any given arc,
+<function>XFillArc</function>
+and
+<function>XFillArcs</function>
+do not draw a pixel more than once.
+If regions intersect,
+the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin,
+clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillArc</function>
+and
+<function>XFillArcs</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Font_Metrics">
+<title>Font Metrics</title>
+<!-- .XS -->
+<!-- (SN Font Metrics -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Font</primary></indexterm>
+A font is a graphical description of a set of characters that are used to
+increase efficiency whenever a set of small, similar sized patterns are
+repeatedly used.
+</para>
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Load and free fonts
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain and free font names
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Compute character string sizes
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Compute logical extents
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Query character string sizes
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The X server loads fonts whenever a program requests a new font.
+The server can cache fonts for quick lookup.
+Fonts are global across all screens in a server.
+Several levels are possible when dealing with fonts.
+Most applications simply use
+<function>XLoadQueryFont</function>
+to load a font and query the font metrics.
+</para>
+<para>
+<!-- .LP -->
+Characters in fonts are regarded as masks.
+Except for image text requests,
+the only pixels modified are those in which bits are set to 1 in the character.
+This means that it makes sense to draw text using stipples or tiles
+(for example, many menus gray-out unusable entries).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+The
+<function>XFontStruct</function>
+structure contains all of the information for the font
+and consists of the font-specific information as well as
+a pointer to an array of
+<function>XCharStruct</function>
+structures for the
+characters contained in the font.
+The
+<function>XFontStruct</function>,
+<function>XFontProp</function>,
+and
+<function>XCharStruct</function>
+structures contain:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCharStruct</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ short lbearing; /* origin to left edge of raster */
+ short rbearing; /* origin to right edge of raster */
+ short width; /* advance to next char's origin */
+ short ascent; /* baseline to top edge of raster */
+ short descent; /* baseline to bottom edge of raster */
+ unsigned short attributes; /* per char flags (not predefined) */
+} XCharStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XFontProp</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef struct {
+ Atom name;
+ unsigned long card32;
+} XFontProp;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XChar2b</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct { /* normal 16 bit characters are two bytes */
+ unsigned char byte1;
+ unsigned char byte2;
+} XChar2b;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XFontStruct</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ XExtData *ext_data; /* hook for extension to hang data */
+ Font fid; /* Font id for this font */
+ unsigned direction; /* hint about the direction font is painted */
+ unsigned min_char_or_byte2; /* first character */
+ unsigned max_char_or_byte2; /* last character */
+ unsigned min_byte1; /* first row that exists */
+ unsigned max_byte1; /* last row that exists */
+ Bool all_chars_exist; /* flag if all characters have nonzero size */
+ unsigned default_char; /* char to print for undefined character */
+ int n_properties; /* how many properties there are */
+ XFontProp *properties; /* pointer to array of additional properties */
+ XCharStruct min_bounds; /* minimum bounds over all existing char */
+ XCharStruct max_bounds; /* maximum bounds over all existing char */
+ XCharStruct *per_char; /* first_char to last_char information */
+ int ascent; /* logical extent above baseline for spacing */
+ int descent; /* logical descent below baseline for spacing */
+} XFontStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+X supports single byte/character, two bytes/character matrix,
+and 16-bit character text operations.
+Note that any of these forms can be used with a font, but a
+single byte/character text request can only specify a single byte
+(that is, the first row of a 2-byte font).
+You should view 2-byte fonts as a two-dimensional matrix of defined
+characters: byte1 specifies the range of defined rows and
+byte2 defines the range of defined columns of the font.
+Single byte/character fonts have one row defined, and the byte2 range
+specified in the structure defines a range of characters.
+</para>
+<para>
+<!-- .LP -->
+The bounding box of a character is defined by the
+<function>XCharStruct </function>
+of that character.
+When characters are absent from a font,
+the default_char is used.
+When fonts have all characters of the same size,
+only the information in the
+<function>XFontStruct</function>
+min and max bounds are used.
+</para>
+<para>
+<!-- .LP -->
+The members of the
+<function>XFontStruct </function>
+have the following semantics:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The direction member can be either
+<function>FontLeftToRight </function>
+or
+<function>FontRightToLeft</function>.
+It is just a hint as to whether most
+<function>XCharStruct </function>
+elements
+have a positive
+(<function>FontLeftToRight</function>)
+or a negative
+(<function>FontRightToLeft</function>)
+character width
+metric.
+The core protocol defines no support for vertical text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
+specifies the linear character index corresponding to the first element
+of the per_char array, and max_char_or_byte2 specifies the linear character
+index of the last element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If either min_byte1 or max_byte1 are nonzero, both
+min_char_or_byte2 and max_char_or_byte2 are less than 256,
+and the 2-byte character index values corresponding to the
+per_char array element N (counting from 0) are:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- .nf -->
+ byte1 = N/D + min_byte1
+<!-- .br -->
+ byte2 = N\\D + min_char_or_byte2
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- .fi -->
+where:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- .nf -->
+ D = max_char_or_byte2 - min_char_or_byte2 + 1
+ / = integer division
+ \\ = integer modulus
+<!-- .fi -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the per_char pointer is NULL,
+all glyphs between the first and last character indexes
+inclusive have the same information,
+as given by both min_bounds and max_bounds.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If all_chars_exist is
+<function>True</function>,
+all characters in the per_char array have nonzero bounding boxes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The default_char member specifies the character that will be used when an
+undefined or nonexistent character is printed.
+The default_char is a 16-bit character (not a 2-byte character).
+For a font using 2-byte matrix format,
+the default_char has byte1 in the most-significant byte
+and byte2 in the least significant byte.
+If the default_char itself specifies an undefined or nonexistent character,
+no printing is performed for an undefined or nonexistent character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The min_bounds and max_bounds members contain the most extreme values of
+each individual
+<function>XCharStruct </function>
+component over all elements of this array
+(and ignore nonexistent characters).
+The bounding box of the font (the smallest
+rectangle enclosing the shape obtained by superimposing all of the
+characters at the same origin [x,y]) has its upper-left coordinate at:
+<literallayout class="monospaced">
+ [x + min_bounds.lbearing, y - max_bounds.ascent]
+</literallayout>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Its width is:
+<literallayout class="monospaced">
+ max_bounds.rbearing - min_bounds.lbearing
+</literallayout>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Its height is:
+<literallayout class="monospaced">
+ max_bounds.ascent + max_bounds.descent
+</literallayout>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The ascent member is the logical extent of the font above the baseline that is
+used for determining line spacing.
+Specific characters may extend beyond
+this.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The descent member is the logical extent of the font at or below the
+baseline that is used for determining line spacing.
+Specific characters may extend beyond this.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the baseline is at Y-coordinate y,
+the logical extent of the font is inclusive between the Y-coordinate
+values (y - font.ascent) and (y + font.descent - 1).
+Typically,
+the minimum interline spacing between rows of text is given
+by ascent + descent.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For a character origin at [x,y],
+the bounding box of a character (that is,
+the smallest rectangle that encloses the character's shape)
+described in terms of
+<function>XCharStruct </function>
+components is a rectangle with its upper-left corner at:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x + lbearing, y - ascent]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Its width is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+rbearing - lbearing
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Its height is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+ascent + descent
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The origin for the next character is defined to be:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x + width, y]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The lbearing member defines the extent of the left edge of the character ink
+from the origin.
+The rbearing member defines the extent of the right edge of the character ink
+from the origin.
+The ascent member defines the extent of the top edge of the character ink
+from the origin.
+The descent member defines the extent of the bottom edge of the character ink
+from the origin.
+The width member defines the logical width of the character.
+</para>
+<para>
+<!-- .LP -->
+Note that the baseline (the y position of the character origin)
+is logically viewed as being the scanline just below nondescending characters.
+When descent is zero,
+only pixels with Y-coordinates less than y are drawn,
+and the origin is logically viewed as being coincident with the left edge of
+a nonkerned character.
+When lbearing is zero,
+no pixels with X-coordinate less than x are drawn.
+Any of the
+<function>XCharStruct</function>
+metric members could be negative.
+If the width is negative,
+the next character will be placed to the left of the current origin.
+</para>
+<para>
+<!-- .LP -->
+The X protocol does not define the interpretation of the attributes member
+in the
+<function>XCharStruct</function>
+structure.
+A nonexistent character is represented with all members of its
+<function>XCharStruct</function>
+set to zero.
+</para>
+<para>
+<!-- .LP -->
+A font is not guaranteed to have any properties.
+The interpretation of the property value (for example, long or unsigned long)
+must be derived from <emphasis remap='I'>a priori</emphasis> knowledge of the property.
+A basic set of font properties is specified in the X Consortium standard
+<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
+</para>
+<sect2 id="Loading_and_Freeing_Fonts">
+<title>Loading and Freeing Fonts</title>
+<!-- .XS -->
+<!-- (SN Loading and Freeing Fonts -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to load fonts, get font information,
+unload fonts, and free font information.
+<indexterm><primary>Fonts</primary><secondary>getting information</secondary></indexterm>
+<indexterm><primary>Fonts</primary><secondary>unloading</secondary></indexterm>
+<indexterm><primary>Fonts</primary><secondary>freeing font information</secondary></indexterm>
+A few font functions use a
+<function>GContext </function>
+resource ID or a font ID interchangeably.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To load a given font, use
+<function>XLoadFont</function>.
+<indexterm significance="preferred"><primary>XLoadFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Font<function> XLoadFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the font,
+which is a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLoadFont</function>
+function loads the specified font and returns its associated font ID.
+If the font name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+When the characters ``?'' and ``*'' are used in a font name, a
+pattern match is performed and any matching font is used.
+In the pattern,
+the ``?'' character will match any single character,
+and the ``*'' character will match any number of characters.
+A structured format for font names is specified in the X Consortium standard
+<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
+If
+<function>XLoadFont</function>
+was unsuccessful at loading the specified font,
+a
+<function>BadName </function>
+error results.
+Fonts are not associated with a particular screen
+and can be stored as a component
+of any GC.
+When the font is no longer needed, call
+<function>XUnloadFont</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XLoadFont</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadName </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return information about an available font, use
+<function>XQueryFont</function>.
+<indexterm significance="preferred"><primary>XQueryFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XFontStruct<function> *XQueryFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> font_ID</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ID</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font ID or the
+<function>GContext</function>
+ID.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryFont</function>
+function returns a pointer to the
+<function>XFontStruct</function>
+structure, which contains information associated with the font.
+You can query a font or the font stored in a GC.
+The font ID stored in the
+<function>XFontStruct</function>
+structure will be the
+<function>GContext </function>
+ID, and you need to be careful when using this ID in other functions
+(see
+<function>XGContextFromGC</function>).
+If the font does not exist,
+<function>XQueryFont</function>
+returns NULL.
+To free this data, use
+<function>XFreeFontInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To perform a
+<function>XLoadFont</function>
+and
+<function>XQueryFont</function>
+in a single operation, use
+<function>XLoadQueryFont</function>.
+<indexterm significance="preferred"><primary>XLoadQueryFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XFontStruct<function> *XLoadQueryFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the font,
+which is a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLoadQueryFont</function>
+function provides the most common way for accessing a font.
+<function>XLoadQueryFont</function>
+both opens (loads) the specified font and returns a pointer to the
+appropriate
+<function>XFontStruct</function>
+structure.
+If the font name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+If the font does not exist,
+<function>XLoadQueryFont</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<function>XLoadQueryFont</function>
+can generate a
+<function>BadAlloc </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unload the font and free the storage used by the font structure
+that was allocated by
+<function>XQueryFont</function>
+or
+<function>XLoadQueryFont</function>,
+use
+<function>XFreeFont</function>.
+<indexterm significance="preferred"><primary>XFreeFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the storage associated with the font.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFont</function>
+function deletes the association between the font resource ID and the specified
+font and frees the
+<function>XFontStruct</function>
+structure.
+The font itself will be freed when no other resource references it.
+The data and the font should not be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeFont</function>
+can generate a
+<function>BadFont </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a given font property, use
+<function>XGetFontProperty</function>.
+<indexterm significance="preferred"><primary>XGetFontProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XGetFontProperty</function></funcdef>
+ <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+ <paramdef>Atom<parameter> atom</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the storage associated with the font.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atom</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom for the property name you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value of the font property.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Given the atom for that property,
+the
+<function>XGetFontProperty</function>
+function returns the value of the specified font property.
+<function>XGetFontProperty</function>
+also returns
+<function>False</function>
+if the property was not defined or
+<function>True</function>
+if it was defined.
+A set of predefined atoms exists for font properties,
+which can be found in
+<!-- .hN X11/Xatom.h . -->
+This set contains the standard properties associated with
+a font.
+Although it is not guaranteed,
+it is likely that the predefined font properties will be present.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unload a font that was loaded by
+<function>XLoadFont</function>,
+use
+<function>XUnloadFont</function>.
+<indexterm significance="preferred"><primary>XUnloadFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUnloadFont</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Font<parameter> font</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnloadFont</function>
+function deletes the association between the font resource ID and the specified font.
+The font itself will be freed when no other resource references it.
+The font should not be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XUnloadFont</function>
+can generate a
+<function>BadFont </function>
+error.
+</para>
+</sect2>
+<sect2 id="Obtaining_and_Freeing_Font_Names_and_Information">
+<title>Obtaining and Freeing Font Names and Information</title>
+<!-- .XS -->
+<!-- (SN Obtaining and Freeing Font Names and Information -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You obtain font names and information by matching a wildcard specification
+when querying a font type for a list of available sizes and so on.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a list of the available font names, use
+<function>XListFonts</function>.
+<indexterm significance="preferred"><primary>XListFonts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> **XListFonts</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *pattern</parameter></paramdef>
+ <paramdef>int<parameter> maxnames</parameter></paramdef>
+ <paramdef>int<parameter> *actual_count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pattern</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the null-terminated pattern string that can contain wildcard
+characters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>maxnames</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the maximum number of names to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actual_count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual number of font names.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListFonts</function>
+function returns an array of available font names
+(as controlled by the font search path; see
+<function>XSetFontPath</function>)
+that match the string you passed to the pattern argument.
+The pattern string can contain any characters,
+but each asterisk (*) is a wildcard for any number of characters,
+and each question mark (?) is a wildcard for a single character.
+If the pattern string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+Each returned string is null-terminated.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+If there are no matching font names,
+<function>XListFonts</function>
+returns NULL.
+The client should call
+<function>XFreeFontNames</function>
+when finished with the result to free the memory.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a font name array, use
+<function>XFreeFontNames</function>.
+<indexterm significance="preferred"><primary>XFreeFontNames</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeFontNames</function></funcdef>
+ <paramdef>char<parameter> *list[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of strings you want to free.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontNames</function>
+function frees the array and strings returned by
+<function>XListFonts </function>
+or
+<function>XListFontsWithInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the names and information about available fonts, use
+<function>XListFontsWithInfo</function>.
+<indexterm significance="preferred"><primary>XListFontsWithInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> **XListFontsWithInfo</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *pattern</parameter></paramdef>
+ <paramdef>int<parameter> maxnames</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+ <paramdef>XFontStruct<parameter> **info_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pattern</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the null-terminated pattern string that can contain wildcard
+characters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>maxnames</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the maximum number of names to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual number of matched font names.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>info_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font information.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListFontsWithInfo</function>
+function returns a list of font names that match the specified pattern and their
+associated font information.
+The list of names is limited to size specified by maxnames.
+The information returned for each font is identical to what
+<function>XLoadQueryFont</function>
+would return except that the per-character metrics are not returned.
+The pattern string can contain any characters,
+but each asterisk (*) is a wildcard for any number of characters,
+and each question mark (?) is a wildcard for a single character.
+If the pattern string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+Each returned string is null-terminated.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+If there are no matching font names,
+<function>XListFontsWithInfo</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+To free only the allocated name array,
+the client should call
+<function>XFreeFontNames</function>.
+To free both the name array and the font information array
+or to free just the font information array,
+the client should call
+<function>XFreeFontInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free font structures and font names, use
+<function>XFreeFontInfo</function>.
+<indexterm significance="preferred"><primary>XFreeFontInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeFontInfo</function></funcdef>
+ <paramdef>char<parameter> **names</parameter></paramdef>
+ <paramdef>XFontStruct<parameter> *free_info</parameter></paramdef>
+ <paramdef>int<parameter> actual_count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of font names.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>free_info</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font information.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actual_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the actual number of font names.
+
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontInfo</function>
+function frees a font structure or an array of font structures
+and optionally an array of font names.
+If NULL is passed for names, no font names are freed.
+If a font structure for an open font (returned by
+<function>XLoadQueryFont</function>)
+is passed, the structure is freed,
+but the font is not closed; use
+<function>XUnloadFont</function>
+to close the font.
+</para>
+</sect2>
+<sect2 id="Computing_Character_String_Sizes">
+<title>Computing Character String Sizes</title>
+<!-- .XS -->
+<!-- (SN Computing Character String Sizes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to compute the width,
+the logical extents,
+and the server information about 8-bit and 2-byte text strings.
+<indexterm><primary>XTextWidth</primary></indexterm>
+<indexterm><primary>XTextWidth16</primary></indexterm>
+The width is computed by adding the character widths of all the characters.
+It does not matter if the font is an 8-bit or 2-byte font.
+These functions return the sum of the character metrics in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine the width of an 8-bit character string, use
+<function>XTextWidth</function>.
+<indexterm significance="preferred"><primary>XTextWidth</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XTextWidth</function></funcdef>
+ <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font used for the width computation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character count in the specified string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To determine the width of a 2-byte character string, use
+<function>XTextWidth16</function>.
+<indexterm significance="preferred"><primary>XTextWidth16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XTextWidth16</function></funcdef>
+ <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+ <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font used for the width computation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character count in the specified string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Computing_Logical_Extents">
+<title>Computing Logical Extents</title>
+<!-- .XS -->
+<!-- (SN Computing Logical Extents -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To compute the bounding box of an 8-bit character string in a given font, use
+<function>XTextExtents</function>.
+<indexterm significance="preferred"><primary>XTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XTextExtents</function></funcdef>
+ <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> nchars</parameter></paramdef>
+ <paramdef>int<parameter> *direction_return</parameter></paramdef>
+ <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+ <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XFontStruct </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>direction_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value of the direction hint
+(<function>FontLeftToRight</function>
+or
+<function>FontRightToLeft</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ascent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font ascent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_descent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font descent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall size in the specified
+<function>XCharStruct </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To compute the bounding box of a 2-byte character string in a given font, use
+<function>XTextExtents16</function>.
+<indexterm significance="preferred"><primary>XTextExtents16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XTextExtents16</function></funcdef>
+ <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+ <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> nchars</parameter></paramdef>
+ <paramdef>int<parameter> *direction_return</parameter></paramdef>
+ <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+ <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XFontStruct </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>direction_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value of the direction hint
+(<function>FontLeftToRight</function>
+or
+<function>FontRightToLeft</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ascent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font ascent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_descent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font descent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall size in the specified
+<function>XCharStruct </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XTextExtents</function>
+and
+<function>XTextExtents16</function>
+functions
+perform the size computation locally and, thereby,
+avoid the round-trip overhead of
+<function>XQueryTextExtents </function>
+and
+<function>XQueryTextExtents16</function>.
+Both functions return an
+<function>XCharStruct</function>
+structure, whose members are set to the values as follows.
+</para>
+<para>
+<!-- .LP -->
+The ascent member is set to the maximum of the ascent metrics of all
+characters in the string.
+The descent member is set to the maximum of the descent metrics.
+The width member is set to the sum of the character-width metrics of all
+characters in the string.
+For each character in the string,
+let W be the sum of the character-width metrics of all characters preceding
+it in the string.
+Let L be the left-side-bearing metric of the character plus W.
+Let R be the right-side-bearing metric of the character plus W.
+The lbearing member is set to the minimum L of all characters in the string.
+The rbearing member is set to the maximum R.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each
+<function>XChar2b </function>
+structure is interpreted as a 16-bit number with byte1 as the
+most significant byte.
+If the font has no defined default character,
+undefined characters in the string are taken to have all zero metrics.
+</para>
+</sect2>
+<sect2 id="Querying_Character_String_Sizes">
+<title>Querying Character String Sizes</title>
+<!-- .XS -->
+<!-- (SN Querying Character String Sizes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To query the server for the bounding box of an 8-bit character string in a
+given font, use
+<function>XQueryTextExtents</function>.
+<indexterm significance="preferred"><primary>XQueryTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XQueryTextExtents</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> font_ID</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> nchars</parameter></paramdef>
+ <paramdef>int<parameter> *direction_return</parameter></paramdef>
+ <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+ <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ID</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies either the font ID or the
+<function>GContext</function>
+ID that contains the font.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>direction_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value of the direction hint
+(<function>FontLeftToRight</function>
+or
+<function>FontRightToLeft</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ascent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font ascent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_descent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font descent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall size in the specified
+<function>XCharStruct </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To query the server for the bounding box of a 2-byte character string
+in a given font, use
+<function>XQueryTextExtents16</function>.
+<indexterm significance="preferred"><primary>XQueryTextExtents16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XQueryTextExtents16</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> font_ID</parameter></paramdef>
+ <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> nchars</parameter></paramdef>
+ <paramdef>int<parameter> *direction_return</parameter></paramdef>
+ <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+ <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ID</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies either the font ID or the
+<function>GContext</function>
+ID that contains the font.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>direction_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value of the direction hint
+(<function>FontLeftToRight</function>
+or
+<function>FontRightToLeft</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_ascent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font ascent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_descent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the font descent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall size in the specified
+<function>XCharStruct </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryTextExtents</function>
+and
+<function>XQueryTextExtents16</function>
+functions return the bounding box of the specified 8-bit and 16-bit
+character string in the specified font or the font contained in the
+specified GC.
+These functions query the X server and, therefore, suffer the round-trip
+overhead that is avoided by
+<function>XTextExtents</function>
+and
+<function>XTextExtents16</function>.
+Both functions return a
+<function>XCharStruct </function>
+structure, whose members are set to the values as follows.
+</para>
+<para>
+<!-- .LP -->
+The ascent member is set to the maximum of the ascent metrics
+of all characters in the string.
+The descent member is set to the maximum of the descent metrics.
+The width member is set to the sum of the character-width metrics
+of all characters in the string.
+For each character in the string,
+let W be the sum of the character-width metrics of all characters preceding
+it in the string.
+Let L be the left-side-bearing metric of the character plus W.
+Let R be the right-side-bearing metric of the character plus W.
+The lbearing member is set to the minimum L of all characters in the string.
+The rbearing member is set to the maximum R.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each
+<function>XChar2b </function>
+structure is interpreted as a 16-bit number with byte1 as the
+most significant byte.
+If the font has no defined default character,
+undefined characters in the string are taken to have all zero metrics.
+</para>
+<para>
+<!-- .LP -->
+Characters with all zero metrics are ignored.
+If the font has no defined default_char,
+the undefined characters in the string are also ignored.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryTextExtents</function>
+and
+<function>XQueryTextExtents16</function>
+can generate
+<function>BadFont</function>
+and
+<function>BadGC </function>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Drawing_Text">
+<title>Drawing Text</title>
+<!-- .XS -->
+<!-- (SN Drawing Text -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to draw:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Complex text
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Text characters
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Image text characters
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The fundamental text functions
+<function>XDrawText</function>
+and
+<function>XDrawText16</function>
+use the following structures:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTextItem</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ char *chars; /* pointer to string */
+ int nchars; /* number of characters */
+ int delta; /* delta between strings */
+ Font font; /* Font to print it in, None don't change */
+} XTextItem;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTextItem16</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ XChar2b *chars; /* pointer to two-byte characters */
+ int nchars; /* number of characters */
+ int delta; /* delta between strings */
+ Font font; /* font to print it in, None don't change */
+} XTextItem16;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the font member is not
+<function>None</function>,
+the font is changed before printing and also is stored in the GC.
+If an error was generated during text drawing,
+the previous items may have been drawn.
+The baseline of the characters are drawn starting at the x and y
+coordinates that you pass in the text drawing functions.
+</para>
+<para>
+<!-- .LP -->
+For example, consider the background rectangle drawn by
+<function>XDrawImageString</function>.
+If you want the upper-left corner of the background rectangle
+to be at pixel coordinate (x,y), pass the (x,y + ascent)
+as the baseline origin coordinates to the text functions.
+The ascent is the font ascent, as given in the
+<function>XFontStruct</function>
+structure.
+If you want the lower-left corner of the background rectangle
+to be at pixel coordinate (x,y), pass the (x,y - descent + 1)
+as the baseline origin coordinates to the text functions.
+The descent is the font descent, as given in the
+<function>XFontStruct</function>
+structure.
+</para>
+<sect2 id="Drawing_Complex_Text">
+<title>Drawing Complex Text</title>
+<!-- .XS -->
+<!-- (SN Drawing Complex Text -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Text</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>text items</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw 8-bit characters in a given drawable, use
+<function>XDrawText</function>.
+<indexterm significance="preferred"><primary>XDrawText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>XTextItem<parameter> *items</parameter></paramdef>
+ <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>items</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of text items.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of text items in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte characters in a given drawable, use
+<function>XDrawText16</function>.
+<indexterm significance="preferred"><primary>XDrawText16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawText16</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>XTextItem16<parameter> *items</parameter></paramdef>
+ <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>items</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of text items.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of text items in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawText16</function>
+function is similar to
+<function>XDrawText </function>
+except that it uses 2-byte or 16-bit characters.
+Both functions allow complex spacing and font shifts between counted strings.
+</para>
+<para>
+<!-- .LP -->
+Each text item is processed in turn.
+A font member other than
+<function>None</function>
+in an item causes the font to be stored in the GC
+and used for subsequent text.
+A text element delta specifies an additional change
+in the position along the x axis before the string is drawn.
+The delta is always added to the character origin
+and is not dependent on any characteristics of the font.
+Each character image, as defined by the font in the GC, is treated as an
+additional mask for a fill operation on the drawable.
+The drawable is modified only where the font character has a bit set to 1.
+If a text item generates a
+<function>BadFont</function>
+error, the previous text items may have been drawn.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each
+<function>XChar2b</function>
+structure is interpreted as a 16-bit number with byte1 as the
+most significant byte.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, fill-style, font, subwindow-mode,
+clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawText</function>
+and
+<function>XDrawText16</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadFont</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Text_Characters">
+<title>Drawing Text Characters</title>
+<!-- .XS -->
+<!-- (SN Drawing Text Characters -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Strings</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>strings</secondary></indexterm>
+To draw 8-bit characters in a given drawable, use
+<function>XDrawString</function>.
+<indexterm significance="preferred"><primary>XDrawString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte characters in a given drawable, use
+<function>XDrawString16</function>.
+<indexterm significance="preferred"><primary>XDrawString16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawString16</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Each character image, as defined by the font in the GC, is treated as an
+additional mask for a fill operation on the drawable.
+The drawable is modified only where the font character has a bit set to 1.
+For fonts defined with 2-byte matrix indexing
+and used with
+<function>XDrawString16</function>,
+each byte is used as a byte2 with a byte1 of zero.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin,
+clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin,
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawString</function>
+and
+<function>XDrawString16</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Image_Text_Characters">
+<title>Drawing Image Text Characters</title>
+<!-- .XS -->
+<!-- (SN Drawing Image Text Characters -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Image text</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>image text</secondary></indexterm>
+Some applications, in particular terminal emulators, need to
+print image text in which both the foreground and background bits of
+each character are painted.
+This prevents annoying flicker on many displays.
+<indexterm><primary>XDrawImageString</primary></indexterm>
+<indexterm><primary>XDrawImageString16</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw 8-bit image text characters in a given drawable, use
+<function>XDrawImageString</function>.
+<indexterm significance="preferred"><primary>XDrawImageString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawImageString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte image text characters in a given drawable, use
+<function>XDrawImageString16</function>.
+<indexterm significance="preferred"><primary>XDrawImageString16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDrawImageString16</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawImageString16</function>
+function is similar to
+<function>XDrawImageString </function>
+except that it uses 2-byte or 16-bit characters.
+Both functions also use both the foreground and background pixels
+of the GC in the destination.
+</para>
+<para>
+<!-- .LP -->
+The effect is first to fill a
+destination rectangle with the background pixel defined in the GC and then
+to paint the text with the foreground pixel.
+The upper-left corner of the filled rectangle is at:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x, y - font-ascent]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The width is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+overall-width
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The height is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+font-ascent + font-descent
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The overall-width, font-ascent, and font-descent
+are as would be returned by
+<function>XQueryTextExtents </function>
+using gc and string.
+The function and fill-style defined in the GC are ignored for these functions.
+The effective function is
+<function>GXcopy</function>,
+and the effective fill-style is
+<function>FillSolid</function>.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with 2-byte matrix indexing
+and used with
+<function>XDrawImageString</function>,
+each byte is used as a byte2 with a byte1 of zero.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+plane-mask, foreground, background, font, subwindow-mode, clip-x-origin,
+clip-y-origin, and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawImageString</function>
+and
+<function>XDrawImageString16</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadMatch </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+</sect1>
+<sect1 id="Transferring_Images_between_Client_and_Server">
+<title>Transferring Images between Client and Server</title>
+<!-- .XS -->
+<!-- (SN Transferring Images between Client and Server -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to transfer images between a client
+and the server.
+Because the server may require diverse data formats,
+Xlib provides an image object that fully describes the data in memory
+and that provides for basic operations on that data.
+You should reference the data
+through the image object rather than referencing the data directly.
+However, some implementations of the Xlib library may efficiently deal with
+frequently used data formats by replacing
+functions in the procedure vector with special case functions.
+Supported operations include destroying the image, getting a pixel,
+storing a pixel, extracting a subimage of an image, and adding a constant
+to an image (see section 16.8).
+</para>
+<para>
+<!-- .LP -->
+All the image manipulation functions discussed in this section make use of
+the
+<function>XImage </function>
+structure,
+which describes an image as it exists in the client's memory.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XImage</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef struct _XImage {
+ int width, height; /* size of image */
+ int xoffset; /* number of pixels offset in X direction */
+ int format; /* XYBitmap, XYPixmap, ZPixmap */
+ char *data; /* pointer to image data */
+ int byte_order; /* data byte order, LSBFirst, MSBFirst */
+ int bitmap_unit; /* quant. of scanline 8, 16, 32 */
+ int bitmap_bit_order; /* LSBFirst, MSBFirst */
+ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */
+ int depth; /* depth of image */
+ int bytes_per_line; /* accelerator to next scanline */
+ int bits_per_pixel; /* bits per pixel (ZPixmap) */
+ unsigned long red_mask; /* bits in z arrangement */
+ unsigned long green_mask;
+ unsigned long blue_mask;
+ XPointer obdata; /* hook for the object routines to hang on */
+ struct funcs { /* image manipulation routines */
+ struct _XImage *(*create_image)();
+ int (*destroy_image)();
+ unsigned long (*get_pixel)();
+ int (*put_pixel)();
+ struct _XImage *(*sub_image)();
+ int (*add_pixel)();
+ } f;
+} XImage;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To initialize the image manipulation routines of an image structure, use
+<function>XInitImage</function>.
+<indexterm significance="preferred"><primary>XInitImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XInitImage</function></funcdef>
+ <paramdef>XImage<parameter> *image</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ximage</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitImage</function>
+function initializes the internal image manipulation routines of an
+image structure, based on the values of the various structure members.
+All fields other than the manipulation routines must already be initialized.
+If the bytes_per_line member is zero,
+<function>XInitImage</function>
+will assume the image data is contiguous in memory and set the
+bytes_per_line member to an appropriate value based on the other
+members; otherwise, the value of bytes_per_line is not changed.
+All of the manipulation routines are initialized to functions
+that other Xlib image manipulation functions need to operate on the
+type of image specified by the rest of the structure.
+</para>
+<para>
+<!-- .LP -->
+This function must be called for any image constructed by the client
+before passing it to any other Xlib function.
+Image structures created or returned by Xlib do not need to be
+initialized in this fashion.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if initialization of the
+structure is successful. It returns zero if it detected some error
+or inconsistency in the structure, in which case the image is not changed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To combine an image with a rectangle of a drawable on the display,
+use
+<function>XPutImage</function>.
+<indexterm significance="preferred"><primary>XPutImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPutImage</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>XImage<parameter> *image</parameter></paramdef>
+ <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+ <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>image</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image you want combined with the rectangle.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset in X from the left edge of the image defined
+by the
+<function>XImage </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset in Y from the top edge of the image defined
+by the
+<function>XImage </function>
+structure.
+<!-- .ds Dx , which are relative to the origin of the drawable \ -->
+and are the coordinates of the subimage
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Dx.
+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPutImage</function>
+function
+combines an image with a rectangle of the specified drawable.
+The section of the image defined by the src_x, src_y, width, and height
+arguments is drawn on the specified part of the drawable.
+If
+<function>XYBitmap </function>
+format is used, the depth of the image must be one,
+or a
+<function>BadMatch </function>
+error results.
+The foreground pixel in the GC defines the source for the one bits in the image,
+and the background pixel defines the source for the zero bits.
+For
+<function>XYPixmap </function>
+and
+<function>ZPixmap</function>,
+the depth of the image must match the depth of the drawable,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If the characteristics of the image (for example, byte_order and bitmap_unit)
+differ from what the server requires,
+<function>XPutImage </function>
+automatically makes the appropriate
+conversions.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components:
+function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin,
+and clip-mask.
+It also uses these GC mode-dependent components:
+foreground and background.
+</para>
+<para>
+<!-- .LP -->
+<function>XPutImage</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the contents of a rectangle in a given drawable on the display,
+use
+<function>XGetImage</function>.
+This function specifically supports rudimentary screen dumps.
+<indexterm significance="preferred"><primary>XGetImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XImage<function> *XGetImage</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+ <paramdef>int<parameter> format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and define the upper-left corner of the rectangle
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>plane_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the format for the image.
+You can pass
+<function>XYPixmap</function>
+or
+<function>ZPixmap</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetImage</function>
+function returns a pointer to an
+<function>XImage</function>
+structure.
+This structure provides you with the contents of the specified rectangle of
+the drawable in the format you specify.
+If the format argument is
+<function>XYPixmap</function>,
+the image contains only the bit planes you passed to the plane_mask argument.
+If the plane_mask argument only requests a subset of the planes of the
+display, the depth of the returned image will be the number of planes
+requested.
+If the format argument is
+<function>ZPixmap</function>,
+<function>XGetImage</function>
+returns as zero the bits in all planes not
+specified in the plane_mask argument.
+The function performs no range checking on the values in plane_mask and ignores
+extraneous bits.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetImage</function>
+returns the depth of the image to the depth member of the
+<function>XImage</function>
+structure.
+The depth of the image is as specified when the drawable was created,
+except when getting a subset of the planes in
+<function>XYPixmap</function>
+format, when the depth is given by the number of bits set to 1 in plane_mask.
+</para>
+<para>
+<!-- .LP -->
+If the drawable is a pixmap,
+the given rectangle must be wholly contained within the pixmap,
+or a
+<function>BadMatch</function>
+error results.
+If the drawable is a window,
+the window must be viewable,
+and it must be the case that if there were no inferiors or overlapping windows,
+the specified rectangle of the window would be fully visible on the screen
+and wholly contained within the outside edges of the window,
+or a
+<function>BadMatch</function>
+error results.
+Note that the borders of the window can be included and read with
+this request.
+If the window has backing-store, the backing-store contents are
+returned for regions of the window that are obscured by noninferior
+windows.
+If the window does not have backing-store,
+the returned contents of such obscured regions are undefined.
+The returned contents of visible regions of inferiors
+of a different depth than the specified window's depth are also undefined.
+The pointer cursor image is not included in the returned contents.
+If a problem occurs,
+<function>XGetImage</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetImage</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To copy the contents of a rectangle on the display
+to a location within a preexisting image structure, use
+<function>XGetSubImage</function>.
+<indexterm significance="preferred"><primary>XGetSubImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XImage<function> *XGetSubImage</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+ <paramdef>int<parameter> format</parameter></paramdef>
+ <paramdef>XImage<parameter> *dest_image</parameter></paramdef>
+ <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and define the upper-left corner of the rectangle
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>plane_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the format for the image.
+You can pass
+<function>XYPixmap</function>
+or
+<function>ZPixmap</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_image</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination image.
+<!-- .ds Dx , which are relative to the origin of the destination rectangle, \ -->
+specify its upper-left corner, and determine where the subimage \
+is placed in the destination image
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Dx.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetSubImage </function>
+function updates dest_image with the specified subimage in the same manner as
+<function>XGetImage</function>.
+If the format argument is
+<function>XYPixmap</function>,
+the image contains only the bit planes you passed to the plane_mask argument.
+If the format argument is
+<function>ZPixmap</function>,
+<function>XGetSubImage</function>
+returns as zero the bits in all planes not
+specified in the plane_mask argument.
+The function performs no range checking on the values in plane_mask and ignores
+extraneous bits.
+As a convenience,
+<function>XGetSubImage</function>
+returns a pointer to the same
+<function>XImage</function>
+structure specified by dest_image.
+</para>
+<para>
+<!-- .LP -->
+The depth of the destination
+<function>XImage</function>
+structure must be the same as that of the drawable.
+If the specified subimage does not fit at the specified location
+on the destination image, the right and bottom edges are clipped.
+If the drawable is a pixmap,
+the given rectangle must be wholly contained within the pixmap,
+or a
+<function>BadMatch</function>
+error results.
+If the drawable is a window,
+the window must be viewable,
+and it must be the case that if there were no inferiors or overlapping windows,
+the specified rectangle of the window would be fully visible on the screen
+and wholly contained within the outside edges of the window,
+or a
+<function>BadMatch</function>
+error results.
+If the window has backing-store,
+then the backing-store contents are returned for regions of the window
+that are obscured by noninferior windows.
+If the window does not have backing-store,
+the returned contents of such obscured regions are undefined.
+The returned contents of visible regions of inferiors
+of a different depth than the specified window's depth are also undefined.
+If a problem occurs,
+<function>XGetSubImage</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetSubImage</function>
+can generate
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+<function>BadMatch</function>,
+and
+<function>BadValue </function>
+errors.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH09 b/libX11/specs/libX11/CH09 deleted file mode 100644 index 2b79d3880..000000000 --- a/libX11/specs/libX11/CH09 +++ /dev/null @@ -1,1290 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 The Open Group -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of The Open Group shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from The Open Group. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 9\fP\s-1 - -\s+1\fBWindow and Session Manager Functions\fP\s-1 -.sp 2 -.nr H1 9 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 9: Window and Session Manager Functions -.XE -Although it is difficult to categorize functions as exclusively -for an application, a window manager, or a session manager, -the functions in this chapter are most often used by window managers -and session managers. -It is not expected that these functions will be used by most -application programs. -Xlib provides management functions to: -.IP \(bu 5 -Change the parent of a window -.IP \(bu 5 -Control the lifetime of a window -.IP \(bu 5 -Manage installed colormaps -.IP \(bu 5 -Set and retrieve the font search path -.IP \(bu 5 -Grab the server -.IP \(bu 5 -Kill a client -.IP \(bu 5 -Control the screen saver -.IP \(bu 5 -Control host access -.NH 2 -Changing the Parent of a Window -.XS -\*(SN Changing the Parent of a Window -.XE -.LP -To change a window's parent to another window on the same screen, use -.PN XReparentWindow . -There is no way to move a window between screens. -.IN "XReparentWindow" "" "@DEF@" -.sM -.FD 0 -XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window \fIparent\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIparent\fP 1i -Specifies the parent window. -.ds Xy \ of the position in the new parent window -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.LP -.eM -If the specified window is mapped, -.PN XReparentWindow -automatically performs an -.PN UnmapWindow -request on it, removes it from its current position in the hierarchy, -and inserts it as the child of the specified parent. -The window is placed in the stacking order on top with respect to -sibling windows. -.LP -After reparenting the specified window, -.PN XReparentWindow -causes the X server to generate a -.PN ReparentNotify -event. -The override_redirect member returned in this event is -set to the window's corresponding attribute. -Window manager clients usually should ignore this window if this member -is set to -.PN True . -Finally, if the specified window was originally mapped, -the X server automatically performs a -.PN MapWindow -request on it. -.LP -The X server performs normal exposure processing on formerly obscured -windows. -The X server might not generate -.PN Expose -events for regions from the initial -.PN UnmapWindow -request that are immediately obscured by the final -.PN MapWindow -request. -A -.PN BadMatch -error results if: -.IP \(bu 5 -The new parent window is not on the same screen as -the old parent window. -.IP \(bu 5 -The new parent window is the specified window or an inferior of the -specified window. -.IP \(bu 5 -The new parent is -.PN InputOnly , -and the window is not. -.IP \(bu 5 -The specified window has a -.PN ParentRelative -background, and the new parent window is not the same depth as the -specified window. -.LP -.PN XReparentWindow -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.NH 2 -Controlling the Lifetime of a Window -.XS -\*(SN Controlling the Lifetime of a Window -.XE -.LP -The save-set of a client is a list of other clients' windows that, -if they are inferiors of one of the client's windows at connection close, -should not be destroyed and should be remapped if they are unmapped. -For further information about close-connection processing, -see section 2.6. -To allow an application's window to survive when a window manager that -has reparented a window fails, -Xlib provides the save-set functions that you can -use to control the longevity of subwindows -that are normally destroyed when the parent is destroyed. -For example, a window manager that wants to add decoration -to a window by adding a frame might reparent an application's -window. -When the frame is destroyed, -the application's window should not be destroyed -but be returned to its previous place in the window hierarchy. -.LP -The X server automatically removes windows from the save-set -when they are destroyed. -.LP -.sp -To add or remove a window from the client's save-set, use -.PN XChangeSaveSet . -.IN "XChangeSaveSet" "" "@DEF@" -.sM -.FD 0 -XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIchange_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that you want to add to or delete from the client's save-set -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIchange_mode\fP 1i -Specifies the mode. -You can pass -.PN SetModeInsert -or -.PN SetModeDelete . -.LP -.eM -Depending on the specified mode, -.PN XChangeSaveSet -either inserts or deletes the specified window from the client's save-set. -The specified window must have been created by some other client, -or a -.PN BadMatch -error results. -.LP -.PN XChangeSaveSet -can generate -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To add a window to the client's save-set, use -.PN XAddToSaveSet . -.IN "XAddToSaveSet" "" "@DEF@" -.sM -.FD 0 -XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that you want to add to the client's save-set -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.LP -.eM -The -.PN XAddToSaveSet -function adds the specified window to the client's save-set. -The specified window must have been created by some other client, -or a -.PN BadMatch -error results. -.LP -.PN XAddToSaveSet -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.LP -.sp -To remove a window from the client's save-set, use -.PN XRemoveFromSaveSet . -.IN "XRemoveFromSaveSet" "" "@DEF@" -.sM -.FD 0 -XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that you want to delete from the client's save-set -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.LP -.eM -The -.PN XRemoveFromSaveSet -function removes the specified window from the client's save-set. -The specified window must have been created by some other client, -or a -.PN BadMatch -error results. -.LP -.PN XRemoveFromSaveSet -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.NH 2 -Managing Installed Colormaps -.XS -\*(SN Managing Installed Colormaps -.XE -.LP -The X server maintains a list of installed colormaps. -Windows using these colormaps are guaranteed to display with -correct colors; windows using other colormaps may or may not display -with correct colors. -Xlib provides functions that you can use to install a colormap, -uninstall a colormap, and obtain a list of installed colormaps. -.LP -At any time, -there is a subset of the installed maps that is viewed as an ordered list -and is called the required list. -The length of the required list is at most M, -where M is the minimum number of installed colormaps specified for the screen -in the connection setup. -The required list is maintained as follows. -When a colormap is specified to -.PN XInstallColormap , -it is added to the head of the list; -the list is truncated at the tail, if necessary, to keep its length to -at most M. -When a colormap is specified to -.PN XUninstallColormap -and it is in the required list, -it is removed from the list. -A colormap is not added to the required list when it is implicitly installed -by the X server, -and the X server cannot implicitly uninstall a colormap that is in the -required list. -.LP -.sp -To install a colormap, use -.PN XInstallColormap . -.IN "XInstallColormap" "" "@DEF@" -.sM -.FD 0 -XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XInstallColormap -function installs the specified colormap for its associated screen. -All windows associated with this colormap immediately display with -true colors. -You associated the windows with this colormap when you created them by calling -.PN XCreateWindow , -.PN XCreateSimpleWindow , -.PN XChangeWindowAttributes , -or -.PN XSetWindowColormap . -.LP -If the specified colormap is not already an installed colormap, -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -In addition, for every other colormap that is installed as -a result of a call to -.PN XInstallColormap , -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -.LP -.PN XInstallColormap -can generate a -.PN BadColor -error. -.LP -.sp -To uninstall a colormap, use -.PN XUninstallColormap . -.IN "XUninstallColormap" "" "@DEF@" -.sM -.FD 0 -XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XUninstallColormap -function removes the specified colormap from the required -list for its screen. -As a result, -the specified colormap might be uninstalled, -and the X server might implicitly install or uninstall additional colormaps. -Which colormaps get installed or uninstalled is server dependent -except that the required list must remain installed. -.LP -If the specified colormap becomes uninstalled, -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -In addition, for every other colormap that is installed or uninstalled as a -result of a call to -.PN XUninstallColormap , -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -.LP -.PN XUninstallColormap -can generate a -.PN BadColor -error. -.LP -.sp -To obtain a list of the currently installed colormaps for a given screen, use -.PN XListInstalledColormaps . -.IN "XListInstalledColormaps" "" "@DEF@" -.sM -.FD 0 -Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int *\fInum_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that determines the screen -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fInum_return\fP 1i -Returns the number of currently installed colormaps. -.LP -.eM -The -.PN XListInstalledColormaps -function returns a list of the currently installed colormaps for the screen -of the specified window. -The order of the colormaps in the list is not significant -and is no explicit indication of the required list. -When the allocated list is no longer needed, -free it by using -.PN XFree . -.LP -.PN XListInstalledColormaps -can generate a -.PN BadWindow -error. -.NH 2 -Setting and Retrieving the Font Search Path -.XS -\*(SN Setting and Retrieving the Font Search Path -.XE -.LP -The set of fonts available from a server depends on a font -search path. Xlib provides functions to set and retrieve the -search path for a server. -.LP -.sp -To set the font search path, use -.PN XSetFontPath . -.IN "XSetFontPath" "" "@DEF@" -.sM -.FD 0 -XSetFontPath\^(\^\fIdisplay\fP, \fIdirectories\fP\^, \fIndirs\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char **\fIdirectories\fP\^; -.br - int \fIndirs\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdirectories\fP 1i -Specifies the directory path used to look for a font. -Setting the path to the empty list restores the default path defined -for the X server. -.IP \fIndirs\fP 1i -Specifies the number of directories in the path. -.LP -.eM -The -.PN XSetFontPath -function defines the directory search path for font lookup. -There is only one search path per X server, not one per client. -The encoding and interpretation of the strings are implementation-dependent, -but typically they specify directories or font servers to be searched -in the order listed. -An X server is permitted to cache font information internally; -for example, it might cache an entire font from a file and not -check on subsequent opens of that font to see if the underlying -font file has changed. -However, -when the font path is changed, -the X server is guaranteed to flush all cached information about fonts -for which there currently are no explicit resource IDs allocated. -The meaning of an error from this request is implementation-dependent. -.LP -.PN XSetFontPath -can generate a -.PN BadValue -error. -.LP -.sp -To get the current font search path, use -.PN XGetFontPath . -.IN "XGetFontPath" "" "@DEF@" -.sM -.FD 0 -char **XGetFontPath\^(\^\fIdisplay\fP, \fInpaths_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInpaths_return\fP\^; - -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInpaths_return\fP 1i -Returns the number of strings in the font path array. -.LP -.eM -The -.PN XGetFontPath -function allocates and returns an array of strings containing the search path. -The contents of these strings are implementation-dependent -and are not intended to be interpreted by client applications. -When it is no longer needed, -the data in the font path should be freed by using -.PN XFreeFontPath . -.LP -.sp -To free data returned by -.PN XGetFontPath , -use -.PN XFreeFontPath . -.IN "XFreeFontPath" "" "@DEF@" -.sM -.FD 0 -XFreeFontPath\^(\^\fIlist\fP\^) -.br - char **\fIlist\fP\^; - -.FN -.IP \fIlist\fP 1i -Specifies the array of strings you want to free. -.LP -.eM -The -.PN XFreeFontPath -function -frees the data allocated by -.PN XGetFontPath . -.NH 2 -Grabbing the Server -.XS -\*(SN Grabbing the Server -.XE -.LP -Xlib provides functions that you can use to grab and ungrab the server. -These functions can be used to control processing of output on other -connections by the window system server. -While the server is grabbed, -no processing of requests or close downs on any other connection will occur. -A client closing its connection automatically ungrabs the server. -.IN "Menus" -.IN "Window" "managers" -Although grabbing the server is highly discouraged, it is sometimes necessary. -.LP -.sp -To grab the server, use -.PN XGrabServer . -.IN "Server" "grabbing" -.IN "Grabbing" "server" -.IN "XGrabServer" "" "@DEF@" -.sM -.FD 0 -XGrabServer\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XGrabServer -function disables processing of requests and close downs on all other -connections than the one this request arrived on. -You should not grab the X server any more than is absolutely necessary. -.LP -.sp -To ungrab the server, use -.PN XUngrabServer . -.IN "XUngrabServer" "" "@DEF@" -.sM -.FD 0 -XUngrabServer\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XUngrabServer -function restarts processing of requests and close downs on other connections. -You should avoid grabbing the X server as much as possible. -.NH 2 -Killing Clients -.XS -\*(SN Killing Clients -.XE -.LP -Xlib provides a function to cause the connection to -a client to be closed and its resources to be destroyed. -To destroy a client, use -.PN XKillClient . -.IN "XKillClient" "" "@DEF@" -.sM -.FD 0 -XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIresource\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIresource\fP 1i -Specifies any resource associated with the client that you want to destroy or -.PN AllTemporary . -.LP -.eM -The -.PN XKillClient -function -forces a close down of the client -that created the resource -if a valid resource is specified. -If the client has already terminated in -either -.PN RetainPermanent -or -.PN RetainTemporary -mode, all of the client's -resources are destroyed. -If -.PN AllTemporary -is specified, the resources of all clients that have terminated in -.PN RetainTemporary -are destroyed (see section 2.5). -This permits implementation of window manager facilities that aid debugging. -A client can set its close-down mode to -.PN RetainTemporary . -If the client then crashes, -its windows would not be destroyed. -The programmer can then inspect the application's window tree -and use the window manager to destroy the zombie windows. -.LP -.PN XKillClient -can generate a -.PN BadValue -error. -.NH 2 -Controlling the Screen Saver -.XS -\*(SN Controlling the Screen Saver -.XE -.LP -Xlib provides functions that you can use to set or reset the mode -of the screen saver, to force or activate the screen saver, -or to obtain the current screen saver values. -.LP -.sp -To set the screen saver mode, use -.PN XSetScreenSaver . -.IN "XSetScreenSaver" "" "@DEF@" -.sM -.FD 0 -XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fItimeout\fP\^, \fIinterval\fP\^; -.br - int \fIprefer_blanking\fP\^; -.br - int \fIallow_exposures\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItimeout\fP 1i -Specifies the timeout, in seconds, until the screen saver turns on. -.IP \fIinterval\fP 1i -Specifies the interval, in seconds, between screen saver alterations. -.IP \fIprefer_blanking\fP 1i -Specifies how to enable screen blanking. -You can pass -.PN DontPreferBlanking , -.PN PreferBlanking , -or -.PN DefaultBlanking . -.IP \fIallow_exposures\fP 1i -Specifies the screen save control values. -You can pass -.PN DontAllowExposures , -.PN AllowExposures , -or -.PN DefaultExposures . -.LP -.eM -Timeout and interval are specified in seconds. -A timeout of 0 disables the screen saver -(but an activated screen saver is not deactivated), -and a timeout of \-1 restores the default. -Other negative values generate a -.PN BadValue -error. -If the timeout value is nonzero, -.PN XSetScreenSaver -enables the screen saver. -An interval of 0 disables the random-pattern motion. -If no input from devices (keyboard, mouse, and so on) is generated -for the specified number of timeout seconds once the screen saver is enabled, -the screen saver is activated. -.LP -For each screen, -if blanking is preferred and the hardware supports video blanking, -the screen simply goes blank. -Otherwise, if either exposures are allowed or the screen can be regenerated -without sending -.PN Expose -events to clients, -the screen is tiled with the root window background tile randomly -re-origined each interval seconds. -Otherwise, the screens' state do not change, -and the screen saver is not activated. -The screen saver is deactivated, -and all screen states are restored at the next -keyboard or pointer input or at the next call to -.PN XForceScreenSaver -with mode -.PN ScreenSaverReset . -.LP -If the server-dependent screen saver method supports periodic change, -the interval argument serves as a hint about how long the change period -should be, and zero hints that no periodic change should be made. -Examples of ways to change the screen include scrambling the colormap -periodically, moving an icon image around the screen periodically, or tiling -the screen with the root window background tile, randomly re-origined -periodically. -.LP -.PN XSetScreenSaver -can generate a -.PN BadValue -error. -.LP -.sp -To force the screen saver on or off, use -.PN XForceScreenSaver . -.IN "XForceScreenSaver" "" "@DEF@" -.sM -.FD 0 -XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImode\fP 1i -Specifies the mode that is to be applied. -You can pass -.PN ScreenSaverActive -or -.PN ScreenSaverReset . -.LP -.eM -If the specified mode is -.PN ScreenSaverActive -and the screen saver currently is deactivated, -.PN XForceScreenSaver -activates the screen saver even if the screen saver had been disabled -with a timeout of zero. -If the specified mode is -.PN ScreenSaverReset -and the screen saver currently is enabled, -.PN XForceScreenSaver -deactivates the screen saver if it was activated, -and the activation timer is reset to its initial state -(as if device input had been received). -.LP -.PN XForceScreenSaver -can generate a -.PN BadValue -error. -.LP -.sp -To activate the screen saver, use -.PN XActivateScreenSaver . -.IN "XActivateScreenSaver" "" "@DEF@" -.sM -.FD 0 -XActivateScreenSaver\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.sp -To reset the screen saver, use -.PN XResetScreenSaver . -.IN "XResetScreenSaver" "" "@DEF@" -.sM -.FD 0 -XResetScreenSaver\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.sp -To get the current screen saver values, use -.PN XGetScreenSaver . -.IN "XGetScreenSaver" "" "@DEF@" -.sM -.FD 0 -XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^, -.br - \fIallow_exposures_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^; -.br - int *\fIprefer_blanking_return\fP\^; -.br - int *\fIallow_exposures_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItimeout_return\fP 1i -Returns the timeout, in seconds, until the screen saver turns on. -.IP \fIinterval_return\fP 1i -Returns the interval between screen saver invocations. -.IP \fIprefer_blanking_return\fP 1i -Returns the current screen blanking preference -.Pn ( DontPreferBlanking , -.PN PreferBlanking , -or -.PN DefaultBlanking ). -.IP \fIallow_exposures_return\fP 1i -Returns the current screen save control value -.Pn ( DontAllowExposures , -.PN AllowExposures , -or -.PN DefaultExposures ). -.LP -.eM -.NH 2 -Controlling Host Access -.XS -\*(SN Controlling Host Access -.XE -.LP -This section discusses how to: -.IP \(bu 5 -Add, get, or remove hosts from the access control list -.IP \(bu 5 -Change, enable, or disable access -.LP -.IN "Access control list" -.IN "Authentication" -X does not provide any protection on a per-window basis. -If you find out the resource ID of a resource, you can manipulate it. -To provide some minimal level of protection, however, -connections are permitted only from machines you trust. -This is adequate on single-user workstations but obviously -breaks down on timesharing machines. -Although provisions exist in the X protocol for proper connection -authentication, the lack of a standard authentication server -leaves host-level access control as the only common mechanism. -.LP -.IN "Default Protection" -The initial set of hosts allowed to open connections typically consists of: -.IP \(bu 5 -The host the window system is running on. -.IP \(bu 5 -On POSIX-conformant systems, each host listed in the -.PN /etc/X?.hosts -file. -The ? indicates the number of the -display. -.IN "Files" "/etc/X?.hosts" -This file should consist of host names separated by newlines. -DECnet nodes must terminate in :: to distinguish them from Internet hosts. -.LP -If a host is not in the access control list when the access control -mechanism is enabled and if the host attempts to establish a connection, -the server refuses the connection. -To change the access list, -the client must reside on the same host as the server and/or must -have been granted permission in the initial authorization at connection -setup. -.LP -Servers also can implement other access control policies in addition to -or in place of this host access facility. -For further information about other access control implementations, -see ``X Window System Protocol.'' -.NH 3 -Adding, Getting, or Removing Hosts -.XS -\*(SN Adding, Getting, or Removing Hosts -.XE -.LP -Xlib provides functions that you can use to add, get, or remove hosts -from the access control list. -All the host access control functions use the -.PN XHostAddress -structure, which contains: -.LP -.IN "XHostAddress" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int family; /* for example FamilyInternet */ - int length; /* length of address, in bytes */ - char *address; /* pointer to where to find the address */ -} XHostAddress; -.De -.LP -.eM -The family member specifies which protocol address family to use -(for example, TCP/IP or DECnet) and can be -.PN FamilyInternet , -.PN FamilyInternet6 , -.PN FamilyServerInterpreted , -.PN FamilyDECnet , -or -.PN FamilyChaos . -The length member specifies the length of the address in bytes. -The address member specifies a pointer to the address. -.LP -For TCP/IP, the address should be in network byte order. -For IP version 4 addresses, the family should be FamilyInternet -and the length should be 4 bytes. For IP version 6 addresses, the -family should be FamilyInternet6 and the length should be 16 bytes. -.LP -For the DECnet family, -the server performs no automatic swapping on the address bytes. -A Phase IV address is 2 bytes long. -The first byte contains the least significant 8 bits of the node number. -The second byte contains the most significant 2 bits of the -node number in the least significant 2 bits of the byte -and the area in the most significant 6 bits of the byte. -.LP -For the ServerInterpreted family, the length is ignored and the address -member is a pointer to a -.PN XServerInterpretedAddress -structure, which contains: -.LP -.IN "XServerInterpretedAddress" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int typelength; /* length of type string, in bytes */ - int valuelength;/* length of value string, in bytes */ - char *type; /* pointer to where to find the type string */ - char *value; /* pointer to where to find the address */ -} XServerInterpretedAddress; -.De -.LP -.eM -The type and value members point to strings representing the type and value of -the server interpreted entry. These strings may not be NULL-terminated so care -should be used when accessing them. The typelength and valuelength members -specify the length in byte of the type and value strings. -.LP -.sp -To add a single host, use -.PN XAddHost . -.IN "XAddHost" "" "@DEF@" -.sM -.FD 0 -XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhost\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho added -.IP \fIhost\fP 1i -Specifies the host that is to be \*(Ho. -.LP -.eM -The -.PN XAddHost -function adds the specified host to the access control list for that display. -The server must be on the same host as the client issuing the command, or a -.PN BadAccess -error results. -.LP -.PN XAddHost -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To add multiple hosts at one time, use -.PN XAddHosts . -.IN "XAddHosts" "" "@DEF@" -.sM -.FD 0 -XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhosts\fP\^; -.br - int \fInum_hosts\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho added -.IP \fIhosts\fP 1i -Specifies each host that is to be \*(Ho. -.IP \fInum_hosts\fP 1i -Specifies the number of hosts. -.LP -.eM -The -.PN XAddHosts -function adds each specified host to the access control list for that display. -The server must be on the same host as the client issuing the command, or a -.PN BadAccess -error results. -.LP -.PN XAddHosts -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To obtain a host list, use -.PN XListHosts . -.IN "XListHosts" "" "@DEF@" -.sM -.FD 0 -XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInhosts_return\fP\^; -.br - Bool *\fIstate_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInhosts_return\fP 1i -Returns the number of hosts currently in the access control list. -.IP \fIstate_return\fP 1i -Returns the state of the access control. -.LP -.eM -The -.PN XListHosts -function returns the current access control list as well as whether the use -of the list at connection setup was enabled or disabled. -.PN XListHosts -allows a program to find out what machines can make connections. -It also returns a pointer to a list of host structures that -were allocated by the function. -When no longer needed, -this memory should be freed by calling -.PN XFree . -.LP -.sp -To remove a single host, use -.PN XRemoveHost . -.IN "XRemoveHost" "" "@DEF@" -.sM -.FD 0 -XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhost\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho removed -.IP \fIhost\fP 1i -Specifies the host that is to be \*(Ho. -.LP -.eM -The -.PN XRemoveHost -function removes the specified host from the access control list -for that display. -The server must be on the same host as the client process, or a -.PN BadAccess -error results. -If you remove your machine from the access list, -you can no longer connect to that server, -and this operation cannot be reversed unless you reset the server. -.LP -.PN XRemoveHost -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To remove multiple hosts at one time, use -.PN XRemoveHosts . -.IN "XRemoveHosts" "" "@DEF@" -.sM -.FD 0 -XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhosts\fP\^; -.br - int \fInum_hosts\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho removed -.IP \fIhosts\fP 1i -Specifies each host that is to be \*(Ho. -.IP \fInum_hosts\fP 1i -Specifies the number of hosts. -.LP -.eM -The -.PN XRemoveHosts -function removes each specified host from the access control list for that -display. -The X server must be on the same host as the client process, or a -.PN BadAccess -error results. -If you remove your machine from the access list, -you can no longer connect to that server, -and this operation cannot be reversed unless you reset the server. -.LP -.PN XRemoveHosts -can generate -.PN BadAccess -and -.PN BadValue -errors. -.NH 3 -Changing, Enabling, or Disabling Access Control -.XS -\*(SN Changing, Enabling, or Disabling Access Control -.XE -.LP -Xlib provides functions that you can use to enable, disable, -or change access control. -.LP -For these functions to execute successfully, -the client application must reside on the same host as the X server -and/or have been given permission in the initial authorization -at connection setup. -.LP -.sp -To change access control, use -.PN XSetAccessControl . -.IN "XSetAccessControl" "" "@DEF@" -.sM -.FD 0 -XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImode\fP 1i -Specifies the mode. -You can pass -.PN EnableAccess -or -.PN DisableAccess . -.LP -.eM -The -.PN XSetAccessControl -function either enables or disables the use of the access control list -at each connection setup. -.LP -.PN XSetAccessControl -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To enable access control, use -.PN XEnableAccessControl . -.IN "XEnableAccessControl" "" "@DEF@" -.sM -.FD 0 -XEnableAccessControl\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XEnableAccessControl -function enables the use of the access control list at each connection setup. -.LP -.PN XEnableAccessControl -can generate a -.PN BadAccess -error. -.LP -.sp -To disable access control, use -.PN XDisableAccessControl . -.IN "XDisableAccessControl" "" "@DEF@" -.sM -.FD 0 -XDisableAccessControl\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XDisableAccessControl -function disables the use of the access control list at each connection setup. -.LP -.PN XDisableAccessControl -can generate a -.PN BadAccess -error. -.bp diff --git a/libX11/specs/libX11/CH09.xml b/libX11/specs/libX11/CH09.xml new file mode 100644 index 000000000..20b2e99bc --- /dev/null +++ b/libX11/specs/libX11/CH09.xml @@ -0,0 +1,2012 @@ +<chapter id="window_and_session_manager_functions">
+<title>Window and Session Manager Functions</title>
+
+<para>
+Although it is difficult to categorize functions as exclusively for an application, a window man-
+ager, or a session manager, the functions in this chapter are most often used by window managers
+and session managers. It is not expected that these functions will be used by most application
+programs. Xlib provides management functions to:
+</para>
+
+<itemizedlist>
+ <listitem><para>Change the parent of a window</para></listitem>
+ <listitem><para>Control the lifetime of a window</para></listitem>
+ <listitem><para>Manage installed colormaps</para></listitem>
+ <listitem><para>Set and retrieve the font search path</para></listitem>
+ <listitem><para>Grab the server</para></listitem>
+ <listitem><para>Kill a client</para></listitem>
+ <listitem><para>Control the screen saver</para></listitem>
+ <listitem><para>Control host access</para></listitem>
+</itemizedlist>
+
+<sect1 id="Changing_the_Parent_of_a_Window">
+<title>Changing the Parent of a Window</title>
+<!-- .XS -->
+<!-- (SN Changing the Parent of a Window -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To change a window's parent to another window on the same screen, use
+<function>XReparentWindow</function>.
+There is no way to move a window between screens.
+<indexterm significance="preferred"><primary>XReparentWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XReparentWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> parent</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent window.
+<!-- .ds Xy \ of the position in the new parent window -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified window is mapped,
+<function>XReparentWindow</function>
+automatically performs an
+<function>UnmapWindow</function>
+request on it, removes it from its current position in the hierarchy,
+and inserts it as the child of the specified parent.
+The window is placed in the stacking order on top with respect to
+sibling windows.
+</para>
+<para>
+<!-- .LP -->
+After reparenting the specified window,
+<function>XReparentWindow</function>
+causes the X server to generate a
+<function>ReparentNotify</function>
+event.
+The override_redirect member returned in this event is
+set to the window's corresponding attribute.
+Window manager clients usually should ignore this window if this member
+is set to
+<function>True</function>.
+Finally, if the specified window was originally mapped,
+the X server automatically performs a
+<function>MapWindow</function>
+request on it.
+</para>
+<para>
+<!-- .LP -->
+The X server performs normal exposure processing on formerly obscured
+windows.
+The X server might not generate
+<function>Expose </function>
+events for regions from the initial
+<function>UnmapWindow</function>
+request that are immediately obscured by the final
+<function>MapWindow</function>
+request.
+A
+<function>BadMatch</function>
+error results if:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The new parent window is not on the same screen as
+the old parent window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The new parent window is the specified window or an inferior of the
+specified window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The new parent is
+<function>InputOnly</function>,
+and the window is not.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The specified window has a
+<function>ParentRelative</function>
+background, and the new parent window is not the same depth as the
+specified window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XReparentWindow</function>
+can generate
+<function>BadMatch</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Controlling_the_Lifetime_of_a_Window">
+<title>Controlling the Lifetime of a Window</title>
+<!-- .XS -->
+<!-- (SN Controlling the Lifetime of a Window -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The save-set of a client is a list of other clients' windows that,
+if they are inferiors of one of the client's windows at connection close,
+should not be destroyed and should be remapped if they are unmapped.
+For further information about close-connection processing,
+see section 2.6.
+To allow an application's window to survive when a window manager that
+has reparented a window fails,
+Xlib provides the save-set functions that you can
+use to control the longevity of subwindows
+that are normally destroyed when the parent is destroyed.
+For example, a window manager that wants to add decoration
+to a window by adding a frame might reparent an application's
+window.
+When the frame is destroyed,
+the application's window should not be destroyed
+but be returned to its previous place in the window hierarchy.
+</para>
+<para>
+<!-- .LP -->
+The X server automatically removes windows from the save-set
+when they are destroyed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add or remove a window from the client's save-set, use
+<function>XChangeSaveSet</function>.
+<indexterm significance="preferred"><primary>XChangeSaveSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeSaveSet</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> change_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that you want to add to or delete from the client's save-set -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>change_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode.
+You can pass
+<function>SetModeInsert </function>
+or
+<function>SetModeDelete</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Depending on the specified mode,
+<function>XChangeSaveSet</function>
+either inserts or deletes the specified window from the client's save-set.
+The specified window must have been created by some other client,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeSaveSet</function>
+can generate
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a window to the client's save-set, use
+<function>XAddToSaveSet</function>.
+<indexterm significance="preferred"><primary>XAddToSaveSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAddToSaveSet</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that you want to add to the client's save-set -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddToSaveSet</function>
+function adds the specified window to the client's save-set.
+The specified window must have been created by some other client,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XAddToSaveSet</function>
+can generate
+<function>BadMatch</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove a window from the client's save-set, use
+<function>XRemoveFromSaveSet</function>.
+<indexterm significance="preferred"><primary>XRemoveFromSaveSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRemoveFromSaveSet</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that you want to delete from the client's save-set -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveFromSaveSet</function>
+function removes the specified window from the client's save-set.
+The specified window must have been created by some other client,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XRemoveFromSaveSet</function>
+can generate
+<function>BadMatch </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Managing_Installed_Colormaps">
+<title>Managing Installed Colormaps</title>
+<!-- .XS -->
+<!-- (SN Managing Installed Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The X server maintains a list of installed colormaps.
+Windows using these colormaps are guaranteed to display with
+correct colors; windows using other colormaps may or may not display
+with correct colors.
+Xlib provides functions that you can use to install a colormap,
+uninstall a colormap, and obtain a list of installed colormaps.
+</para>
+<para>
+<!-- .LP -->
+At any time,
+there is a subset of the installed maps that is viewed as an ordered list
+and is called the required list.
+The length of the required list is at most M,
+where M is the minimum number of installed colormaps specified for the screen
+in the connection setup.
+The required list is maintained as follows.
+When a colormap is specified to
+<function>XInstallColormap</function>,
+it is added to the head of the list;
+the list is truncated at the tail, if necessary, to keep its length to
+at most M.
+When a colormap is specified to
+<function>XUninstallColormap</function>
+and it is in the required list,
+it is removed from the list.
+A colormap is not added to the required list when it is implicitly installed
+by the X server,
+and the X server cannot implicitly uninstall a colormap that is in the
+required list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To install a colormap, use
+<function>XInstallColormap</function>.
+<indexterm significance="preferred"><primary>XInstallColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XInstallColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInstallColormap</function>
+function installs the specified colormap for its associated screen.
+All windows associated with this colormap immediately display with
+true colors.
+You associated the windows with this colormap when you created them by calling
+<function>XCreateWindow</function>,
+<function>XCreateSimpleWindow</function>,
+<function>XChangeWindowAttributes</function>,
+or
+<function>XSetWindowColormap</function>.
+</para>
+<para>
+<!-- .LP -->
+If the specified colormap is not already an installed colormap,
+the X server generates a
+<function>ColormapNotify</function>
+event on each window that has that colormap.
+In addition, for every other colormap that is installed as
+a result of a call to
+<function>XInstallColormap</function>,
+the X server generates a
+<function>ColormapNotify</function>
+event on each window that has that colormap.
+</para>
+<para>
+<!-- .LP -->
+<function>XInstallColormap</function>
+can generate a
+<function>BadColor </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To uninstall a colormap, use
+<function>XUninstallColormap</function>.
+<indexterm significance="preferred"><primary>XUninstallColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUninstallColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUninstallColormap</function>
+function removes the specified colormap from the required
+list for its screen.
+As a result,
+the specified colormap might be uninstalled,
+and the X server might implicitly install or uninstall additional colormaps.
+Which colormaps get installed or uninstalled is server dependent
+except that the required list must remain installed.
+</para>
+<para>
+<!-- .LP -->
+If the specified colormap becomes uninstalled,
+the X server generates a
+<function>ColormapNotify</function>
+event on each window that has that colormap.
+In addition, for every other colormap that is installed or uninstalled as a
+result of a call to
+<function>XUninstallColormap</function>,
+the X server generates a
+<function>ColormapNotify</function>
+event on each window that has that colormap.
+</para>
+<para>
+<!-- .LP -->
+<function>XUninstallColormap</function>
+can generate a
+<function>BadColor </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of the currently installed colormaps for a given screen, use
+<function>XListInstalledColormaps</function>.
+<indexterm significance="preferred"><primary>XListInstalledColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap<function> *XListInstalledColormaps</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> *num_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that determines the screen -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of currently installed colormaps.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListInstalledColormaps</function>
+function returns a list of the currently installed colormaps for the screen
+of the specified window.
+The order of the colormaps in the list is not significant
+and is no explicit indication of the required list.
+When the allocated list is no longer needed,
+free it by using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XListInstalledColormaps</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Setting_and_Retrieving_the_Font_Search_Path">
+<title>Setting and Retrieving the Font Search Path</title>
+<!-- .XS -->
+<!-- (SN Setting and Retrieving the Font Search Path -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The set of fonts available from a server depends on a font
+search path. Xlib provides functions to set and retrieve the
+search path for a server.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the font search path, use
+<function>XSetFontPath</function>.
+<indexterm significance="preferred"><primary>XSetFontPath</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetFontPath</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> **directories</parameter></paramdef>
+ <paramdef>int<parameter> ndirs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>directories</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the directory path used to look for a font.
+Setting the path to the empty list restores the default path defined
+for the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ndirs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of directories in the path.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetFontPath</function>
+function defines the directory search path for font lookup.
+There is only one search path per X server, not one per client.
+The encoding and interpretation of the strings are implementation-dependent,
+but typically they specify directories or font servers to be searched
+in the order listed.
+An X server is permitted to cache font information internally;
+for example, it might cache an entire font from a file and not
+check on subsequent opens of that font to see if the underlying
+font file has changed.
+However,
+when the font path is changed,
+the X server is guaranteed to flush all cached information about fonts
+for which there currently are no explicit resource IDs allocated.
+The meaning of an error from this request is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetFontPath</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current font search path, use
+<function>XGetFontPath</function>.
+<indexterm significance="preferred"><primary>XGetFontPath</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> **XGetFontPath</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *npaths_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npaths_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of strings in the font path array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetFontPath</function>
+function allocates and returns an array of strings containing the search path.
+The contents of these strings are implementation-dependent
+and are not intended to be interpreted by client applications.
+When it is no longer needed,
+the data in the font path should be freed by using
+<function>XFreeFontPath</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free data returned by
+<function>XGetFontPath</function>,
+use
+<function>XFreeFontPath</function>.
+<indexterm significance="preferred"><primary>XFreeFontPath</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeFontPath</function></funcdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of strings you want to free.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontPath</function>
+function
+frees the data allocated by
+<function>XGetFontPath</function>.
+</para>
+</sect1>
+<sect1 id="Grabbing_the_Server_">
+<title>Grabbing the Server </title>
+<!-- .XS -->
+<!-- (SN Grabbing the Server -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to grab and ungrab the server.
+These functions can be used to control processing of output on other
+connections by the window system server.
+While the server is grabbed,
+no processing of requests or close downs on any other connection will occur.
+A client closing its connection automatically ungrabs the server.
+<indexterm><primary>Menus</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>managers</secondary></indexterm>
+Although grabbing the server is highly discouraged, it is sometimes necessary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the server, use
+<function>XGrabServer</function>.
+<indexterm><primary>Server</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>server</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabServer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGrabServer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabServer</function>
+function disables processing of requests and close downs on all other
+connections than the one this request arrived on.
+You should not grab the X server any more than is absolutely necessary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the server, use
+<function>XUngrabServer</function>.
+<indexterm significance="preferred"><primary>XUngrabServer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabServer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabServer</function>
+function restarts processing of requests and close downs on other connections.
+You should avoid grabbing the X server as much as possible.
+</para>
+</sect1>
+<sect1 id="Killing_Clients">
+<title>Killing Clients</title>
+<!-- .XS -->
+<!-- (SN Killing Clients -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides a function to cause the connection to
+a client to be closed and its resources to be destroyed.
+To destroy a client, use
+<function>XKillClient</function>.
+<indexterm significance="preferred"><primary>XKillClient</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XKillClient</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> resource</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resource</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any resource associated with the client that you want to destroy or
+<function>AllTemporary</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XKillClient</function>
+function
+forces a close down of the client
+that created the resource
+if a valid resource is specified.
+If the client has already terminated in
+either
+<function>RetainPermanent </function>
+or
+<function>RetainTemporary </function>
+mode, all of the client's
+resources are destroyed.
+If
+<function>AllTemporary </function>
+is specified, the resources of all clients that have terminated in
+<function>RetainTemporary </function>
+are destroyed (see section 2.5).
+This permits implementation of window manager facilities that aid debugging.
+A client can set its close-down mode to
+<function>RetainTemporary</function>.
+If the client then crashes,
+its windows would not be destroyed.
+The programmer can then inspect the application's window tree
+and use the window manager to destroy the zombie windows.
+</para>
+<para>
+<!-- .LP -->
+<function>XKillClient</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+</sect1>
+<sect1 id="Controlling_the_Screen_Saver_">
+<title>Controlling the Screen Saver </title>
+<!-- .XS -->
+<!-- (SN Controlling the Screen Saver -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set or reset the mode
+of the screen saver, to force or activate the screen saver,
+or to obtain the current screen saver values.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the screen saver mode, use
+<function>XSetScreenSaver</function>.
+<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetScreenSaver</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>inttimeout,<parameter> interval</parameter></paramdef>
+ <paramdef>int<parameter> prefer_blanking</parameter></paramdef>
+ <paramdef>int<parameter> allow_exposures</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timeout</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timeout, in seconds, until the screen saver turns on.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>interval</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the interval, in seconds, between screen saver alterations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prefer_blanking</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to enable screen blanking.
+You can pass
+<function>DontPreferBlanking</function>,
+<function>PreferBlanking</function>,
+or
+<function>DefaultBlanking</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>allow_exposures</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen save control values.
+You can pass
+<function>DontAllowExposures</function>,
+<function>AllowExposures</function>,
+or
+<function>DefaultExposures</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Timeout and interval are specified in seconds.
+A timeout of 0 disables the screen saver
+(but an activated screen saver is not deactivated),
+and a timeout of \-1 restores the default.
+Other negative values generate a
+<function>BadValue</function>
+error.
+If the timeout value is nonzero,
+<function>XSetScreenSaver</function>
+enables the screen saver.
+An interval of 0 disables the random-pattern motion.
+If no input from devices (keyboard, mouse, and so on) is generated
+for the specified number of timeout seconds once the screen saver is enabled,
+the screen saver is activated.
+</para>
+<para>
+<!-- .LP -->
+For each screen,
+if blanking is preferred and the hardware supports video blanking,
+the screen simply goes blank.
+Otherwise, if either exposures are allowed or the screen can be regenerated
+without sending
+<function>Expose </function>
+events to clients,
+the screen is tiled with the root window background tile randomly
+re-origined each interval seconds.
+Otherwise, the screens' state do not change,
+and the screen saver is not activated.
+The screen saver is deactivated,
+and all screen states are restored at the next
+keyboard or pointer input or at the next call to
+<function>XForceScreenSaver</function>
+with mode
+<function>ScreenSaverReset</function>.
+</para>
+<para>
+<!-- .LP -->
+If the server-dependent screen saver method supports periodic change,
+the interval argument serves as a hint about how long the change period
+should be, and zero hints that no periodic change should be made.
+Examples of ways to change the screen include scrambling the colormap
+periodically, moving an icon image around the screen periodically, or tiling
+the screen with the root window background tile, randomly re-origined
+periodically.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetScreenSaver</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To force the screen saver on or off, use
+<function>XForceScreenSaver</function>.
+<indexterm significance="preferred"><primary>XForceScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XForceScreenSaver</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode that is to be applied.
+You can pass
+<function>ScreenSaverActive</function>
+or
+<function>ScreenSaverReset</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified mode is
+<function>ScreenSaverActive </function>
+and the screen saver currently is deactivated,
+<function>XForceScreenSaver</function>
+activates the screen saver even if the screen saver had been disabled
+with a timeout of zero.
+If the specified mode is
+<function>ScreenSaverReset </function>
+and the screen saver currently is enabled,
+<function>XForceScreenSaver</function>
+deactivates the screen saver if it was activated,
+and the activation timer is reset to its initial state
+(as if device input had been received).
+</para>
+<para>
+<!-- .LP -->
+<function>XForceScreenSaver</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To activate the screen saver, use
+<function>XActivateScreenSaver</function>.
+<indexterm significance="preferred"><primary>XActivateScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XActivateScreenSaver</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To reset the screen saver, use
+<function>XResetScreenSaver</function>.
+<indexterm significance="preferred"><primary>XResetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XResetScreenSaver</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To get the current screen saver values, use
+<function>XGetScreenSaver</function>.
+<indexterm significance="preferred"><primary>XGetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetScreenSaver</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int*timeout_return,<parameter> *interval_return</parameter></paramdef>
+ <paramdef>int<parameter> *prefer_blanking_return</parameter></paramdef>
+ <paramdef>int<parameter> *allow_exposures_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timeout_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the timeout, in seconds, until the screen saver turns on.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>interval_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the interval between screen saver invocations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prefer_blanking_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current screen blanking preference
+(<function>DontPreferBlanking</function>,
+<function>PreferBlanking</function>,
+or
+<function>DefaultBlanking</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>allow_exposures_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current screen save control value
+(<function>DontAllowExposures</function>,
+<function>AllowExposures</function>,
+or
+<function>DefaultExposures</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect1>
+<sect1 id="Controlling_Host_Access">
+<title>Controlling Host Access</title>
+<!-- .XS -->
+<!-- (SN Controlling Host Access -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Add, get, or remove hosts from the access control list
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Change, enable, or disable access
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm><primary>Access control list</primary></indexterm>
+<indexterm><primary>Authentication</primary></indexterm>
+X does not provide any protection on a per-window basis.
+If you find out the resource ID of a resource, you can manipulate it.
+To provide some minimal level of protection, however,
+connections are permitted only from machines you trust.
+This is adequate on single-user workstations but obviously
+breaks down on timesharing machines.
+Although provisions exist in the X protocol for proper connection
+authentication, the lack of a standard authentication server
+leaves host-level access control as the only common mechanism.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Default Protection</primary></indexterm>
+The initial set of hosts allowed to open connections typically consists of:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The host the window system is running on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+On <acronym>POSIX</acronym>-conformant systems, each host listed in the
+<function>/etc/X?.hosts </function>
+file.
+The ? indicates the number of the
+display.
+<indexterm><primary>Files</primary><secondary>/etc/X?.hosts</secondary></indexterm>
+This file should consist of host names separated by newlines.
+DECnet nodes must terminate in :: to distinguish them from Internet hosts.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If a host is not in the access control list when the access control
+mechanism is enabled and if the host attempts to establish a connection,
+the server refuses the connection.
+To change the access list,
+the client must reside on the same host as the server and/or must
+have been granted permission in the initial authorization at connection
+setup.
+</para>
+<para>
+<!-- .LP -->
+Servers also can implement other access control policies in addition to
+or in place of this host access facility.
+For further information about other access control implementations,
+see ``X Window System Protocol.''
+</para>
+<sect2 id="Adding_Getting_or_Removing_Hosts">
+<title>Adding, Getting, or Removing Hosts</title>
+<!-- .XS -->
+<!-- (SN Adding, Getting, or Removing Hosts -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to add, get, or remove hosts
+from the access control list.
+All the host access control functions use the
+<function>XHostAddress </function>
+structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XHostAddress</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int family; /* for example FamilyInternet */
+ int length; /* length of address, in bytes */
+ char *address; /* pointer to where to find the address */
+} XHostAddress;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The family member specifies which protocol address family to use
+(for example, <acronym>TCP</acronym>/<acronym>IP</acronym> or DECnet) and can be
+<function>FamilyInternet</function>,
+<function>FamilyInternet6</function>,
+<function>FamilyServerInterpreted</function>,
+<function>FamilyDECnet</function>,
+or
+<function>FamilyChaos</function>.
+The length member specifies the length of the address in bytes.
+The address member specifies a pointer to the address.
+</para>
+<para>
+<!-- .LP -->
+For <acronym>TCP</acronym>/<acronym>IP</acronym>, the address should be in network byte order.
+For <acronym>IP</acronym> version 4 addresses, the family should be FamilyInternet
+and the length should be 4 bytes. For <acronym>IP</acronym> version 6 addresses, the
+family should be FamilyInternet6 and the length should be 16 bytes.
+</para>
+<para>
+<!-- .LP -->
+For the DECnet family,
+the server performs no automatic swapping on the address bytes.
+A Phase IV address is 2 bytes long.
+The first byte contains the least significant 8 bits of the node number.
+The second byte contains the most significant 2 bits of the
+node number in the least significant 2 bits of the byte
+and the area in the most significant 6 bits of the byte.
+</para>
+<para>
+<!-- .LP -->
+For the ServerInterpreted family, the length is ignored and the address
+member is a pointer to a
+<function>XServerInterpretedAddress</function>
+structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XServerInterpretedAddress</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int typelength; /* length of type string, in bytes */
+ int valuelength; /* length of value string, in bytes */
+ char *type; /* pointer to where to find the type string */
+ char *value; /* pointer to where to find the address */
+} XServerInterpretedAddress;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The type and value members point to strings representing the type and value of
+the server interpreted entry. These strings may not be NULL-terminated so care
+should be used when accessing them. The typelength and valuelength members
+specify the length in byte of the type and value strings.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a single host, use
+<function>XAddHost</function>.
+<indexterm significance="preferred"><primary>XAddHost</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAddHost</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XHostAddress<parameter> *host</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Ho added -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>host</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the host that is to be (Ho.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddHost</function>
+function adds the specified host to the access control list for that display.
+The server must be on the same host as the client issuing the command, or a
+<function>BadAccess</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XAddHost</function>
+can generate
+<function>BadAccess</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add multiple hosts at one time, use
+<function>XAddHosts</function>.
+<indexterm significance="preferred"><primary>XAddHosts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAddHosts</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>
+ <paramdef>int<parameter> num_hosts</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Ho added -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies each host that is to be (Ho.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of hosts.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddHosts</function>
+function adds each specified host to the access control list for that display.
+The server must be on the same host as the client issuing the command, or a
+<function>BadAccess</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XAddHosts</function>
+can generate
+<function>BadAccess</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a host list, use
+<function>XListHosts</function>.
+<indexterm significance="preferred"><primary>XListHosts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XHostAddress<function> *XListHosts</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *nhosts_return</parameter></paramdef>
+ <paramdef>Bool<parameter> *state_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nhosts_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of hosts currently in the access control list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>state_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the state of the access control.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListHosts</function>
+function returns the current access control list as well as whether the use
+of the list at connection setup was enabled or disabled.
+<function>XListHosts</function>
+allows a program to find out what machines can make connections.
+It also returns a pointer to a list of host structures that
+were allocated by the function.
+When no longer needed,
+this memory should be freed by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove a single host, use
+<function>XRemoveHost</function>.
+<indexterm significance="preferred"><primary>XRemoveHost</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRemoveHost</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XHostAddress<parameter> *host</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Ho removed -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>host</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the host that is to be (Ho.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveHost</function>
+function removes the specified host from the access control list
+for that display.
+The server must be on the same host as the client process, or a
+<function>BadAccess</function>
+error results.
+If you remove your machine from the access list,
+you can no longer connect to that server,
+and this operation cannot be reversed unless you reset the server.
+</para>
+<para>
+<!-- .LP -->
+<function>XRemoveHost</function>
+can generate
+<function>BadAccess</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove multiple hosts at one time, use
+<function>XRemoveHosts</function>.
+<indexterm significance="preferred"><primary>XRemoveHosts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRemoveHosts</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>
+ <paramdef>int<parameter> num_hosts</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Ho removed -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies each host that is to be (Ho.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of hosts.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveHosts</function>
+function removes each specified host from the access control list for that
+display.
+The X server must be on the same host as the client process, or a
+<function>BadAccess</function>
+error results.
+If you remove your machine from the access list,
+you can no longer connect to that server,
+and this operation cannot be reversed unless you reset the server.
+</para>
+<para>
+<!-- .LP -->
+<function>XRemoveHosts</function>
+can generate
+<function>BadAccess</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Changing_Enabling_or_Disabling_Access_Control">
+<title>Changing, Enabling, or Disabling Access Control</title>
+<!-- .XS -->
+<!-- (SN Changing, Enabling, or Disabling Access Control -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to enable, disable,
+or change access control.
+</para>
+<para>
+<!-- .LP -->
+For these functions to execute successfully,
+the client application must reside on the same host as the X server
+and/or have been given permission in the initial authorization
+at connection setup.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change access control, use
+<function>XSetAccessControl</function>.
+<indexterm significance="preferred"><primary>XSetAccessControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetAccessControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode.
+You can pass
+<function>EnableAccess</function>
+or
+<function>DisableAccess</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetAccessControl</function>
+function either enables or disables the use of the access control list
+at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetAccessControl</function>
+can generate
+<function>BadAccess</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To enable access control, use
+<function>XEnableAccessControl</function>.
+<indexterm significance="preferred"><primary>XEnableAccessControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XEnableAccessControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEnableAccessControl</function>
+function enables the use of the access control list at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<function>XEnableAccessControl</function>
+can generate a
+<function>BadAccess </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To disable access control, use
+<function>XDisableAccessControl</function>.
+<indexterm significance="preferred"><primary>XDisableAccessControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDisableAccessControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisableAccessControl</function>
+function disables the use of the access control list at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<function>XDisableAccessControl</function>
+can generate a
+<function>BadAccess </function>
+error.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH10 b/libX11/specs/libX11/CH10 deleted file mode 100644 index 76502fb9e..000000000 --- a/libX11/specs/libX11/CH10 +++ /dev/null @@ -1,3886 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 10\fP\s-1 - -\s+1\fBEvents\fP\s-1 -.sp 2 -.nr H1 10 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 10: Events -.XE -A client application communicates with the X server through the connection you -establish with the -.PN XOpenDisplay -.IN "XOpenDisplay" -function. -A client application sends requests to the X server over this connection. -.IN "Requests" "" "@DEF@" -These requests are made by the Xlib functions that are -called in the client application. -Many Xlib functions cause the X server to generate events, -and the user's typing or moving the pointer can generate events asynchronously. -The X server returns events to the client on the same connection. -.LP -This chapter discusses the following topics associated with events: -.IP \(bu 5 -Event types -.IP \(bu 5 -Event structures -.IP \(bu 5 -Event masks -.IP \(bu 5 -Event processing -.LP -Functions for handling events are dealt with in the next chapter. -.NH 2 -Event Types -.XS -\*(SN Event Types -.XE -.LP -.IN "Event" "types" -An event is data generated asynchronously by the X server as a result of some -device activity or as side effects of a request sent by an Xlib function. -.IN "Event" -Device-related events propagate from the source window to ancestor windows -until some client application has selected that event type -or until the event is explicitly discarded. -The X server generally sends an event to a client application -only if the client has specifically asked to be informed of that event type, -typically by setting the event-mask attribute of the window. -The mask can also be set when you create a window -or by changing the window's -event-mask. -You can also mask out events that would propagate to ancestor windows -by manipulating the -do-not-propagate mask of the window's attributes. -However, -.PN MappingNotify -events are always sent to all clients. -.IN "Input Control" -.IN "Output Control" -.LP -An event type describes a specific event generated by the X server. -For each event type, -a corresponding constant name is defined in -.hN X11/X.h , -which is used when referring to an event type. -.IN "Event" "categories" -The following table lists the event category -and its associated event type or types. -The processing associated with these events is discussed in section 10.5. -.LP -.\".CP T 1 -.\"Event Categories and Event Types -.LP -.TS H -lw(2.25i) lw(3.5i). -_ -.sp 6p -.B -Event Category Event Type -.sp 6p -_ -.sp 6p -.TH -.R -T{ -Keyboard events -T} T{ -.PN KeyPress , -.PN KeyRelease -T} -.sp 6p -T{ -Pointer events -T} T{ -.PN ButtonPress , -.PN ButtonRelease , -.PN MotionNotify -T} -.sp 6p -T{ -Window crossing events -T} T{ -.PN EnterNotify , -.PN LeaveNotify -T} -.sp 6p -T{ -Input focus events -T} T{ -.PN FocusIn , -.PN FocusOut -T} -.sp 6p -T{ -Keymap state notification event -T} T{ -.PN KeymapNotify -T} -.sp 6p -T{ -Exposure events -T} T{ -.PN Expose , -.PN GraphicsExpose , -.PN NoExpose -T} -.sp 6p -T{ -Structure control events -T} T{ -.PN CirculateRequest , -.PN ConfigureRequest , -.PN MapRequest , -.PN ResizeRequest -T} -.sp 6p -T{ -Window state notification events -T} T{ -.PN CirculateNotify , -.PN ConfigureNotify , -.PN CreateNotify , -.PN DestroyNotify , -.PN GravityNotify , -.PN MapNotify , -.PN MappingNotify , -.PN ReparentNotify , -.PN UnmapNotify , -.br -.PN VisibilityNotify -T} -.sp 6p -T{ -Colormap state notification event -T} T{ -.PN ColormapNotify -T} -.sp 6p -T{ -Client communication events -T} T{ -.PN ClientMessage , -.PN PropertyNotify , -.PN SelectionClear , -.PN SelectionNotify , -.PN SelectionRequest -T} -.sp 6p -_ -.TE -.\".LP -.\"Table 8-1 lists the event types and the Xlib functions that could cause -.\"the X server to generate that event type. -.\"The event types are listed alphabetically. -.\"Note that the error event is not listed in this table. -.\"For a list of the constants associated with an error event, see the Handling -.\"Errors section in this chapter. -.\".LP -.\".so eventtable -.NH 2 -Event Structures -.XS -\*(SN Event Structures -.XE -.LP -For each event type, -a corresponding structure is declared in -.hN X11/Xlib.h . -All the event structures have the following common members: -.LP -.IN "XAnyEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; -} XAnyEvent; -.De -.LP -.eM -The type member is set to the event type constant name that uniquely identifies -it. -For example, when the X server reports a -.PN GraphicsExpose -event to a client application, it sends an -.PN XGraphicsExposeEvent -structure with the type member set to -.PN GraphicsExpose . -The display member is set to a pointer to the display the event was read on. -The send_event member is set to -.PN True -if the event came from a -.PN SendEvent -protocol request. -The serial member is set from the serial number reported in the protocol -but expanded from the 16-bit least-significant bits to a full 32-bit value. -The window member is set to the window that is most useful to toolkit -dispatchers. -.LP -The X server can send events at any time in the input stream. -Xlib stores any events received while waiting for a reply in an event queue -for later use. -Xlib also provides functions that allow you to check events -in the event queue (see section 11.3). -.LP -In addition to the individual structures declared for each event type, the -.PN XEvent -structure is a union of the individual structures declared for each event type. -Depending on the type, -you should access members of each event by using the -.PN XEvent -union. -.LP -.IN "XEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef union _XEvent { - int type; /* must not be changed */ - XAnyEvent xany; - XKeyEvent xkey; - XButtonEvent xbutton; - XMotionEvent xmotion; - XCrossingEvent xcrossing; - XFocusChangeEvent xfocus; - XExposeEvent xexpose; - XGraphicsExposeEvent xgraphicsexpose; - XNoExposeEvent xnoexpose; - XVisibilityEvent xvisibility; - XCreateWindowEvent xcreatewindow; - XDestroyWindowEvent xdestroywindow; - XUnmapEvent xunmap; - XMapEvent xmap; - XMapRequestEvent xmaprequest; - XReparentEvent xreparent; - XConfigureEvent xconfigure; - XGravityEvent xgravity; - XResizeRequestEvent xresizerequest; - XConfigureRequestEvent xconfigurerequest; - XCirculateEvent xcirculate; - XCirculateRequestEvent xcirculaterequest; - XPropertyEvent xproperty; - XSelectionClearEvent xselectionclear; - XSelectionRequestEvent xselectionrequest; - XSelectionEvent xselection; - XColormapEvent xcolormap; - XClientMessageEvent xclient; - XMappingEvent xmapping; - XErrorEvent xerror; - XKeymapEvent xkeymap; - long pad[24]; -} XEvent; -.De -.LP -.eM -An -.PN XEvent -structure's first entry always is the type member, -which is set to the event type. -The second member always is the serial number of the protocol request -that generated the event. -The third member always is send_event, -which is a -.PN Bool -that indicates if the event was sent by a different client. -The fourth member always is a display, -which is the display that the event was read from. -Except for keymap events, -the fifth member always is a window, -which has been carefully selected to be useful to toolkit dispatchers. -To avoid breaking toolkits, -the order of these first five entries is not to change. -Most events also contain a time member, -which is the time at which an event occurred. -In addition, a pointer to the generic event must be cast before it -is used to access any other information in the structure. -.NH 2 -Event Masks -.XS -\*(SN Event Masks -.XE -.LP -.IN "Event mask" "" "@DEF@" -Clients select event reporting of most events relative to a window. -To do this, pass an event mask to an Xlib event-handling -function that takes an event_mask argument. -The bits of the event mask are defined in -.hN X11/X.h . -Each bit in the event mask maps to an event mask name, -which describes the event or events you want the X server to -return to a client application. -.LP -Unless the client has specifically asked for them, -most events are not reported to clients when they are generated. -Unless the client suppresses them by setting graphics-exposures in the GC to -.PN False , -.PN GraphicsExpose -and -.PN NoExpose -are reported by default as a result of -.PN XCopyPlane -and -.PN XCopyArea . -.PN SelectionClear , -.PN SelectionRequest , -.PN SelectionNotify , -or -.PN ClientMessage -cannot be masked. -Selection-related events are only sent to clients cooperating -with selections (see section 4.5). -When the keyboard or pointer mapping is changed, -.PN MappingNotify -is always sent to clients. -.LP -.\"Table 8-2 -The following table -lists the event mask constants you can pass to -the event_mask argument and -the circumstances in which you would want to specify the -event mask: -.LP -.\" .CP T 2 -.\"Event Mask Definitions -.TS H -lw(2i) lw(3.5i). -_ -.sp 6p -.B -Event Mask Circumstances -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN NoEventMask -T} T{ -No events wanted -T} -T{ -.PN KeyPressMask -T} T{ -Keyboard down events wanted -T} -T{ -.PN KeyReleaseMask -T} T{ -Keyboard up events wanted -T} -T{ -.PN ButtonPressMask -T} T{ -Pointer button down events wanted -T} -T{ -.PN ButtonReleaseMask -T} T{ -Pointer button up events wanted -T} -T{ -.PN EnterWindowMask -T} T{ -Pointer window entry events wanted -T} -T{ -.PN LeaveWindowMask -T} T{ -Pointer window leave events wanted -T} -T{ -.PN PointerMotionMask -T} T{ -Pointer motion events wanted -T} -T{ -.PN PointerMotionHintMask -T} T{ -Pointer motion hints wanted -T} -T{ -.PN Button1MotionMask -T} T{ -Pointer motion while button 1 down -T} -T{ -.PN Button2MotionMask -T} T{ -Pointer motion while button 2 down -T} -T{ -.PN Button3MotionMask -T} T{ -Pointer motion while button 3 down -T} -T{ -.PN Button4MotionMask -T} T{ -Pointer motion while button 4 down -T} -T{ -.PN Button5MotionMask -T} T{ -Pointer motion while button 5 down -T} -T{ -.PN ButtonMotionMask -T} T{ -Pointer motion while any button down -T} -T{ -.PN KeymapStateMask -T} T{ -Keyboard state wanted at window entry and focus in -T} -T{ -.PN ExposureMask -T} T{ -Any exposure wanted -T} -T{ -.PN VisibilityChangeMask -T} T{ -Any change in visibility wanted -T} -T{ -.PN StructureNotifyMask -T} T{ -Any change in window structure wanted -T} -T{ -.PN ResizeRedirectMask -T} T{ -Redirect resize of this window -T} -T{ -.PN SubstructureNotifyMask -T} T{ -Substructure notification wanted -T} -T{ -.PN SubstructureRedirectMask -T} T{ -Redirect structure requests on children -T} -T{ -.PN FocusChangeMask -T} T{ -Any change in input focus wanted -T} -T{ -.PN PropertyChangeMask -T} T{ -Any change in property wanted -T} -T{ -.PN ColormapChangeMask -T} T{ -Any change in colormap wanted -T} -T{ -.PN OwnerGrabButtonMask -T} T{ -Automatic grabs should activate with owner_events set to -.PN True -T} -.sp 6p -_ -.TE -.LP -.NH 2 -Event Processing Overview -.XS -\*(SN Event Processing Overview -.XE -.LP -The event reported to a client application during event processing -depends on which event masks you provide as the event-mask attribute -for a window. -For some event masks, there is a one-to-one correspondence between -the event mask constant and the event type constant. -For example, if you pass the event mask -.PN ButtonPressMask , -the X server sends back only -.PN ButtonPress -events. -.IN "CurrentTime" -Most events contain a time member, -which is the time at which an event occurred. -.LP -In other cases, one event mask constant can map to several event type constants. -For example, if you pass the event mask -.PN SubstructureNotifyMask , -the X server can send back -.PN CirculateNotify , -.PN ConfigureNotify , -.PN CreateNotify , -.PN DestroyNotify , -.PN GravityNotify , -.PN MapNotify , -.PN ReparentNotify , -or -.PN UnmapNotify -events. -.LP -In another case, -two event masks can map to one event type. -For example, -if you pass either -.PN PointerMotionMask -or -.PN ButtonMotionMask , -the X server sends back -a -.PN MotionNotify -event. -.LP -The following table -lists the event mask, -its associated event type or types, -and the structure name associated with the event type. -Some of these structures actually are typedefs to a generic structure -that is shared between two event types. -Note that N.A. appears in columns for which the information is not applicable. -.LP -.ps 9 -.nr PS 9 -.TS H -lw(1.5i) lw(1i) lw(1.5i) lw(1.5i). -_ -.sp 6p -.B -Event Mask Event Type Structure Generic Structure -.sp 6p -_ -.sp 6p -.TH -.R -ButtonMotionMask MotionNotify XPointerMovedEvent XMotionEvent -Button1MotionMask -Button2MotionMask -Button3MotionMask -Button4MotionMask -Button5MotionMask -.sp 6p -ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent -.sp 6p -ButtonReleaseMask ButtonRelease XButtonReleasedEvent XButtonEvent -.sp 6p -ColormapChangeMask ColormapNotify XColormapEvent -.sp 6p -EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent -.sp 6p -LeaveWindowMask LeaveNotify XLeaveWindowEvent XCrossingEvent -.sp 6p -ExposureMask Expose XExposeEvent -GCGraphicsExposures in GC GraphicsExpose XGraphicsExposeEvent - NoExpose XNoExposeEvent -.sp 6p -FocusChangeMask FocusIn XFocusInEvent XFocusChangeEvent - FocusOut XFocusOutEvent XFocusChangeEvent -.sp 6p -KeymapStateMask KeymapNotify XKeymapEvent -.sp 6p -KeyPressMask KeyPress XKeyPressedEvent XKeyEvent -KeyReleaseMask KeyRelease XKeyReleasedEvent XKeyEvent -.sp 6p -OwnerGrabButtonMask N.A. N.A. -.sp 6p -PointerMotionMask MotionNotify XPointerMovedEvent XMotionEvent -PointerMotionHintMask N.A. N.A. -.sp 6p -PropertyChangeMask PropertyNotify XPropertyEvent -.sp 6p -ResizeRedirectMask ResizeRequest XResizeRequestEvent -.sp 6p -StructureNotifyMask CirculateNotify XCirculateEvent - ConfigureNotify XConfigureEvent - DestroyNotify XDestroyWindowEvent - GravityNotify XGravityEvent - MapNotify XMapEvent - ReparentNotify XReparentEvent - UnmapNotify XUnmapEvent -.sp 6p -SubstructureNotifyMask CirculateNotify XCirculateEvent - ConfigureNotify XConfigureEvent - CreateNotify XCreateWindowEvent - DestroyNotify XDestroyWindowEvent - GravityNotify XGravityEvent - MapNotify XMapEvent - ReparentNotify XReparentEvent - UnmapNotify XUnmapEvent -.sp 6p -SubstructureRedirectMask CirculateRequest XCirculateRequestEvent - ConfigureRequest XConfigureRequestEvent - MapRequest XMapRequestEvent -.sp 6p -N.A. ClientMessage XClientMessageEvent -.sp 6p -N.A. MappingNotify XMappingEvent -.sp 6p -N.A. SelectionClear XSelectionClearEvent -.sp 6p -N.A. SelectionNotify XSelectionEvent -.sp 6p -N.A. SelectionRequest XSelectionRequestEvent -.sp 6p -VisibilityChangeMask VisibilityNotify XVisibilityEvent -.sp 6p -_ -.TE -.ps 11 -.nr PS 11 -.LP -The sections that follow describe the processing that occurs -when you select the different event masks. -The sections are organized according to these processing categories: -.IP \(bu 5 -Keyboard and pointer events -.IP \(bu 5 -Window crossing events -.IP \(bu 5 -Input focus events -.IP \(bu 5 -Keymap state notification events -.IP \(bu 5 -Exposure events -.IP \(bu 5 -Window state notification events -.IP \(bu 5 -Structure control events -.IP \(bu 5 -Colormap state notification events -.IP \(bu 5 -Client communication events -.NH 2 -Keyboard and Pointer Events -.XS -\*(SN Keyboard and Pointer Events -.XE -.LP -This section discusses: -.IP \(bu 5 -Pointer button events -.IP \(bu 5 -Keyboard and pointer events -.NH 3 -Pointer Button Events -.XS -\*(SN Pointer Button Events -.XE -.LP -The following describes the event processing that occurs when a pointer button -press is processed with the pointer in some window w and -when no active pointer grab is in progress. -.LP -The X server searches the ancestors of w from the root down, -looking for a passive grab to activate. -If no matching passive grab on the button exists, -the X server automatically starts an active grab for the client receiving -the event and sets the last-pointer-grab time to the current server time. -The effect is essentially equivalent to an -.PN XGrabButton -with these client passed arguments: -.TS H -lw(1.5i) lw(3.5i). -_ -.sp 6p -.B -Argument Value -.sp 6p -_ -.sp 6p -.TH -.R -T{ -\fIw\fP -T} T{ -The event window -T} -T{ -\fIevent_mask\fP -T} T{ -The client's selected pointer events on the event window -T} -T{ -\fIpointer_mode\fP -T} T{ -.PN GrabModeAsync -T} -T{ -\fIkeyboard_mode\fP -T} T{ -.PN GrabModeAsync -T} -T{ -\fIowner_events\fP -T} T{ -.PN True , -if the client has selected -.PN OwnerGrabButtonMask -on the event window, -otherwise -.PN False -T} -T{ -\fIconfine_to\fP -T} T{ -.PN None -T} -T{ -\fIcursor\fP -T} T{ -.PN None -T} -.sp 6p -_ -.TE -.LP -The active grab is automatically terminated when -the logical state of the pointer has all buttons released. -Clients can modify the active grab by calling -.PN XUngrabPointer -and -.PN XChangeActivePointerGrab . -.NH 3 -Keyboard and Pointer Events -.XS -\*(SN Keyboard and Pointer Events -.XE -.LP -.IN "Events" "ButtonPress" -.IN "Events" "ButtonRelease" -.IN "Events" "KeyPress" -.IN "Events" "KeyRelease" -.IN "Events" "MotionNotify" -This section discusses the processing that occurs for the -keyboard events -.PN KeyPress -and -.PN KeyRelease -and the pointer events -.PN ButtonPress , -.PN ButtonRelease , -and -.PN MotionNotify . -For information about the keyboard event-handling utilities, -see chapter 11. -.LP -.IN "KeyPress" "" "@DEF@" -.IN "KeyRelease" "" "@DEF@" -The X server reports -.PN KeyPress -or -.PN KeyRelease -events to clients wanting information about keys that logically change state. -Note that these events are generated for all keys, -even those mapped to modifier bits. -.IN "ButtonPress" "" "@DEF@" -.IN "ButtonRelease" "" "@DEF@" -The X server reports -.PN ButtonPress -or -.PN ButtonRelease -events to clients wanting information about buttons that logically change state. -.LP -.IN "MotionNotify" "" "@DEF@" -The X server reports -.PN MotionNotify -events to clients wanting information about when the pointer logically moves. -The X server generates this event whenever the pointer is moved -and the pointer motion begins and ends in the window. -The granularity of -.PN MotionNotify -events is not guaranteed, -but a client that selects this event type is guaranteed -to receive at least one event when the pointer moves and then rests. -.LP -The generation of the logical changes lags the physical changes -if device event processing is frozen. -.LP -To receive -.PN KeyPress , -.PN KeyRelease , -.PN ButtonPress , -and -.PN ButtonRelease -events, set -.PN KeyPressMask , -.PN KeyReleaseMask , -.PN ButtonPressMask , -and -.PN ButtonReleaseMask -bits in the event-mask attribute of the window. -.LP -To receive -.PN MotionNotify -events, set one or more of the following event -masks bits in the event-mask attribute of the window. -.IP \(bu 5 -.PN Button1MotionMask \ \- -.PN Button5MotionMask -.IP -The client application receives -.PN MotionNotify -events only when one or more of the specified buttons is pressed. -.IP \(bu 5 -.PN ButtonMotionMask -.IP -The client application receives -.PN MotionNotify -events only when at least one button is pressed. -.IP \(bu 5 -.PN PointerMotionMask -.IP -The client application receives -.PN MotionNotify -events independent of the state of -the pointer buttons. -.IP \(bu 5 -.PN PointerMotionHintMask -.IP -If -.PN PointerMotionHintMask -is selected in combination with one or more of the above masks, -the X server is free to send only one -.PN MotionNotify -event (with the is_hint member of the -.PN XPointerMovedEvent -structure set to -.PN NotifyHint ) -to the client for the event window, -until either the key or button state changes, -the pointer leaves the event window, or the client calls -.PN XQueryPointer -or -.PN XGetMotionEvents . -The server still may send -.PN MotionNotify -events without is_hint set to -.PN NotifyHint . -.LP -The source of the event is the viewable window that the pointer is in. -The window used by the X server to report these events depends on -the window's position in the window hierarchy -and whether any intervening window prohibits the generation of these events. -Starting with the source window, -the X server searches up the window hierarchy until it locates the first -window specified by a client as having an interest in these events. -If one of the intervening windows has its do-not-propagate-mask -set to prohibit generation of the event type, -the events of those types will be suppressed. -Clients can modify the actual window used for reporting by performing -active grabs and, in the case of keyboard events, by using the focus window. -.LP -The structures for these event types contain: -.LP -.IN "XButtonEvent" "" "@DEF@" -.IN "XButtonPressedEvent" "" "@DEF@" -.IN "XButtonReleasedEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* ButtonPress or ButtonRelease */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* ``event'' window it is reported relative to */ - Window root; /* root window that the event occurred on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in event window */ - int x_root, y_root; /* coordinates relative to root */ - unsigned int state; /* key or button mask */ - unsigned int button; /* detail */ - Bool same_screen; /* same screen flag */ -} XButtonEvent; -typedef XButtonEvent XButtonPressedEvent; -typedef XButtonEvent XButtonReleasedEvent; -.De -.LP -.IN "XKeyEvent" "" "@DEF@" -.IN "XKeyPressedEvent" "" "@DEF@" -.IN "XKeyReleasedEvent" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* KeyPress or KeyRelease */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* ``event'' window it is reported relative to */ - Window root; /* root window that the event occurred on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in event window */ - int x_root, y_root; /* coordinates relative to root */ - unsigned int state; /* key or button mask */ - unsigned int keycode; /* detail */ - Bool same_screen; /* same screen flag */ -} XKeyEvent; -typedef XKeyEvent XKeyPressedEvent; -typedef XKeyEvent XKeyReleasedEvent; -.De -.LP -.IN "XMotionEvent" "" "@DEF@" -.IN "XPointerMovedEvent" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* MotionNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* ``event'' window reported relative to */ - Window root; /* root window that the event occurred on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in event window */ - int x_root, y_root; /* coordinates relative to root */ - unsigned int state; /* key or button mask */ - char is_hint; /* detail */ - Bool same_screen; /* same screen flag */ -} XMotionEvent; -typedef XMotionEvent XPointerMovedEvent; -.De -.LP -.eM -These structures have the following common members: -window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen. -The window member is set to the window on which the -event was generated and is referred to as the event window. -As long as the conditions previously discussed are met, -this is the window used by the X server to report the event. -The root member is set to the source window's root window. -The x_root and y_root members are set to the pointer's coordinates -relative to the root window's origin at the time of the event. -.LP -The same_screen member is set to indicate whether the event -window is on the same screen -as the root window and can be either -.PN True -or -.PN False . -If -.PN True , -the event and root windows are on the same screen. -If -.PN False , -the event and root windows are not on the same screen. -.LP -If the source window is an inferior of the event window, -the subwindow member of the structure is set to the child of the event window -that is the source window or the child of the event window that is -an ancestor of the source window. -Otherwise, the X server sets the subwindow member to -.PN None . -The time member is set to the time when the event was generated -and is expressed in milliseconds. -.LP -If the event window is on the same screen as the root window, -the x and y members -are set to the coordinates relative to the event window's origin. -Otherwise, these members are set to zero. -.LP -The state member is set to indicate the logical state of the pointer buttons -and modifier keys just prior to the event, -which is the bitwise inclusive OR of one or more of the -button or modifier key masks: -.PN Button1Mask , -.PN Button2Mask , -.PN Button3Mask , -.PN Button4Mask , -.PN Button5Mask , -.PN ShiftMask , -.PN LockMask , -.PN ControlMask , -.PN Mod1Mask , -.PN Mod2Mask , -.PN Mod3Mask , -.PN Mod4Mask , -and -.PN Mod5Mask . -.LP -Each of these structures also has a member that indicates the detail. -For the -.PN XKeyPressedEvent -and -.PN XKeyReleasedEvent -structures, this member is called a keycode. -It is set to a number that represents a physical key on the keyboard. -The keycode is an arbitrary representation for any key on the keyboard -(see sections 12.7 and 16.1). -.LP -For the -.PN XButtonPressedEvent -and -.PN XButtonReleasedEvent -structures, this member is called button. -It represents the pointer button that changed state and can be the -.PN Button1 , -.PN Button2 , -.PN Button3 , -.PN Button4 , -or -.PN Button5 -value. -For the -.PN XPointerMovedEvent -structure, this member is called is_hint. -It can be set to -.PN NotifyNormal -or -.PN NotifyHint . -.LP -Some of the symbols mentioned in this section have fixed values, as -follows: -.TS H -lw(2i) lw(3.5i). -_ -.sp 6p -.B -Symbol Value -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN Button1MotionMask -T} T{ -(1L<<8) -T} -T{ -.PN Button2MotionMask -T} T{ -(1L<<9) -T} -T{ -.PN Button3MotionMask -T} T{ -(1L<<10) -T} -T{ -.PN Button4MotionMask -T} T{ -(1L<<11) -T} -T{ -.PN Button5MotionMask -T} T{ -(1L<<12) -T} -T{ -.PN Button1Mask -T} T{ -(1<<8) -T} -T{ -.PN Button2Mask -T} T{ -(1<<9) -T} -T{ -.PN Button3Mask -T} T{ -(1<<10) -T} -T{ -.PN Button4Mask -T} T{ -(1<<11) -T} -T{ -.PN Button5Mask -T} T{ -(1<<12) -T} -T{ -.PN ShiftMask -T} T{ -(1<<0) -T} -T{ -.PN LockMask -T} T{ -(1<<1) -T} -T{ -.PN ControlMask -T} T{ -(1<<2) -T} -T{ -.PN Mod1Mask -T} T{ -(1<<3) -T} -T{ -.PN Mod2Mask -T} T{ -(1<<4) -T} -T{ -.PN Mod3Mask -T} T{ -(1<<5) -T} -T{ -.PN Mod4Mask -T} T{ -(1<<6) -T} -T{ -.PN Mod5Mask -T} T{ -(1<<7) -T} -T{ -.PN Button1 -T} T{ -1 -T} -T{ -.PN Button2 -T} T{ -2 -T} -T{ -.PN Button3 -T} T{ -3 -T} -T{ -.PN Button4 -T} T{ -4 -T} -T{ -.PN Button5 -T} T{ -5 -T} -.sp 6p -_ -.TE -.NH 2 -Window Entry/Exit Events -.XS -\*(SN Window Entry/Exit Events -.XE -.LP -.IN "Events" "EnterNotify" -.IN "Events" "LeaveNotify" -This section describes the processing that -occurs for the window crossing events -.PN EnterNotify -and -.PN LeaveNotify . -.IN "EnterNotify" "" "@DEF@" -.IN "LeaveNotify" "" "@DEF@" -If a pointer motion or a window hierarchy change causes the -pointer to be in a different window than before, the X server reports -.PN EnterNotify -or -.PN LeaveNotify -events to clients who have selected for these events. -All -.PN EnterNotify -and -.PN LeaveNotify -events caused by a hierarchy change are -generated after any hierarchy event -.Pn ( UnmapNotify , -.PN MapNotify , -.PN ConfigureNotify , -.PN GravityNotify , -.PN CirculateNotify ) -caused by that change; -however, the X protocol does not constrain the ordering of -.PN EnterNotify -and -.PN LeaveNotify -events with respect to -.PN FocusOut , -.PN VisibilityNotify , -and -.PN Expose -events. -.LP -This contrasts with -.PN MotionNotify -events, which are also generated when the pointer moves -but only when the pointer motion begins and ends in a single window. -An -.PN EnterNotify -or -.PN LeaveNotify -event also can be generated when some client application calls -.PN XGrabPointer -and -.PN XUngrabPointer . -.LP -To receive -.PN EnterNotify -or -.PN LeaveNotify -events, set the -.PN EnterWindowMask -or -.PN LeaveWindowMask -bits of the event-mask attribute of the window. -.LP -The structure for these event types contains: -.LP -.IN "XCrossingEvent" "" "@DEF@" -.IN "XEnterWindowEvent" "" "@DEF@" -.IN "XLeaveWindowEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* EnterNotify or LeaveNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* ``event'' window reported relative to */ - Window root; /* root window that the event occurred on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in event window */ - int x_root, y_root; /* coordinates relative to root */ - int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ - int detail; - /* - * NotifyAncestor, NotifyVirtual, NotifyInferior, - * NotifyNonlinear,NotifyNonlinearVirtual - */ - Bool same_screen; /* same screen flag */ - Bool focus; /* boolean focus */ - unsigned int state; /* key or button mask */ -} XCrossingEvent; -typedef XCrossingEvent XEnterWindowEvent; -typedef XCrossingEvent XLeaveWindowEvent; -.De -.LP -.eM -The window member is set to the window on which the -.PN EnterNotify -or -.PN LeaveNotify -event was generated and is referred to as the event window. -This is the window used by the X server to report the event, -and is relative to the root -window on which the event occurred. -The root member is set to the root window of the screen -on which the event occurred. -.LP -For a -.PN LeaveNotify -event, -if a child of the event window contains the initial position of the pointer, -the subwindow component is set to that child. -Otherwise, the X server sets the subwindow member to -.PN None . -For an -.PN EnterNotify -event, if a child of the event window contains the final pointer position, -the subwindow component is set to that child or -.PN None . -.LP -The time member is set to the time when the event was generated -and is expressed in milliseconds. -The x and y members are set to the coordinates of the pointer position in -the event window. -This position is always the pointer's final position, -not its initial position. -If the event window is on the same -screen as the root window, x and y are the pointer coordinates -relative to the event window's origin. -Otherwise, x and y are set to zero. -The x_root and y_root members are set to the pointer's coordinates relative to the -root window's origin at the time of the event. -.LP -The same_screen member is set to indicate whether the event window is on the same screen -as the root window and can be either -.PN True -or -.PN False . -If -.PN True , -the event and root windows are on the same screen. -If -.PN False , -the event and root windows are not on the same screen. -.LP -The focus member is set to indicate whether the event window is the focus window or an -inferior of the focus window. -The X server can set this member to either -.PN True -or -.PN False . -If -.PN True , -the event window is the focus window or an inferior of the focus window. -If -.PN False , -the event window is not the focus window or an inferior of the focus window. -.LP -The state member is set to indicate the state of the pointer buttons and -modifier keys just prior to the -event. -The X server can set this member to the bitwise inclusive OR of one -or more of the button or modifier key masks: -.PN Button1Mask , -.PN Button2Mask , -.PN Button3Mask , -.PN Button4Mask , -.PN Button5Mask , -.PN ShiftMask , -.PN LockMask , -.PN ControlMask , -.PN Mod1Mask , -.PN Mod2Mask , -.PN Mod3Mask , -.PN Mod4Mask , -.PN Mod5Mask . -.LP -The mode member is set to indicate whether the events are normal events, -pseudo-motion events -when a grab activates, or pseudo-motion events when a grab deactivates. -The X server can set this member to -.PN NotifyNormal , -.PN NotifyGrab , -or -.PN NotifyUngrab . -.LP -The detail member is set to indicate the notify detail and can be -.PN NotifyAncestor , -.PN NotifyVirtual , -.PN NotifyInferior , -.PN NotifyNonlinear , -or -.PN NotifyNonlinearVirtual . -.NH 3 -Normal Entry/Exit Events -.XS -\*(SN Normal Entry/Exit Events -.XE -.LP -.PN EnterNotify -and -.PN LeaveNotify -events are generated when the pointer moves from -one window to another window. -Normal events are identified by -.PN XEnterWindowEvent -or -.PN XLeaveWindowEvent -structures whose mode member is set to -.PN NotifyNormal . -.IP \(bu 5 -When the pointer moves from window A to window B and A is an inferior of B, -the X server does the following: -.RS -.IP \- 5 -It generates a -.PN LeaveNotify -event on window A, with the detail member of the -.PN XLeaveWindowEvent -structure set to -.PN NotifyAncestor . -.IP \- 5 -It generates a -.PN LeaveNotify -event on each window between window A and window B, exclusive, -with the detail member of each -.PN XLeaveWindowEvent -structure set to -.PN NotifyVirtual . -.IP \- 5 -It generates an -.PN EnterNotify -event on window B, with the detail member of the -.PN XEnterWindowEvent -structure set to -.PN NotifyInferior . -.RE -.IP \(bu 5 -When the pointer moves from window A to window B and B is an inferior of A, -the X server does the following: -.RS -.IP \- 5 -It generates a -.PN LeaveNotify -event on window A, -with the detail member of the -.PN XLeaveWindowEvent -structure set to -.PN NotifyInferior . -.IP \- 5 -It generates an -.PN EnterNotify -event on each window between window A and window B, exclusive, with the -detail member of each -.PN XEnterWindowEvent -structure set to -.PN NotifyVirtual . -.IP \- 5 -It generates an -.PN EnterNotify -event on window B, with the detail member of the -.PN XEnterWindowEvent -structure set to -.PN NotifyAncestor . -.RE -.IP \(bu 5 -When the pointer moves from window A to window B -and window C is their least common ancestor, -the X server does the following: -.RS -.IP \- 5 -It generates a -.PN LeaveNotify -event on window A, -with the detail member of the -.PN XLeaveWindowEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -It generates a -.PN LeaveNotify -event on each window between window A and window C, exclusive, -with the detail member of each -.PN XLeaveWindowEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates an -.PN EnterNotify -event on each window between window C and window B, exclusive, -with the detail member of each -.PN XEnterWindowEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates an -.PN EnterNotify -event on window B, with the detail member of the -.PN XEnterWindowEvent -structure set to -.PN NotifyNonlinear . -.RE -.IP \(bu 5 -When the pointer moves from window A to window B on different screens, -the X server does the following: -.RS -.IP \- 5 -It generates a -.PN LeaveNotify -event on window A, -with the detail member of the -.PN XLeaveWindowEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -If window A is not a root window, -it generates a -.PN LeaveNotify -event on each window above window A up to and including its root, -with the detail member of each -.PN XLeaveWindowEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -If window B is not a root window, -it generates an -.PN EnterNotify -event on each window from window B's root down to but not including -window B, with the detail member of each -.PN XEnterWindowEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates an -.PN EnterNotify -event on window B, with the detail member of the -.PN XEnterWindowEvent -structure set to -.PN NotifyNonlinear . -.RE -.\".SH 3 -.NH 3 -Grab and Ungrab Entry/Exit Events -.XS -\*(SN Grab and Ungrab Entry/Exit Events -.XE -.LP -Pseudo-motion mode -.PN EnterNotify -and -.PN LeaveNotify -events are generated when a pointer grab activates or deactivates. -Events in which the pointer grab activates -are identified by -.PN XEnterWindowEvent -or -.PN XLeaveWindowEvent -structures whose mode member is set to -.PN NotifyGrab . -Events in which the pointer grab deactivates -are identified by -.PN XEnterWindowEvent -or -.PN XLeaveWindowEvent -structures whose mode member is set to -.PN NotifyUngrab -(see -.PN XGrabPointer ). -.IP \(bu 5 -When a pointer grab activates after any initial warp into a confine_to -window and before generating any actual -.PN ButtonPress -event that activates the grab, -G is the grab_window for the grab, -and P is the window the pointer is in, -the X server does the following: -.RS -.IP \- 5 -It generates -.PN EnterNotify -and -.PN LeaveNotify -events (see section 10.6.1) -with the mode members of the -.PN XEnterWindowEvent -and -.PN XLeaveWindowEvent -structures set to -.PN NotifyGrab . -These events are generated -as if the pointer were to suddenly warp from -its current position in P to some position in G. -However, the pointer does not warp, and the X server uses the pointer position -as both the initial and final positions for the events. -.RE -.IP \(bu 5 -When a pointer grab deactivates after generating any actual -.PN ButtonRelease -event that deactivates the grab, -G is the grab_window for the grab, -and P is the window the pointer is in, -the X server does the following: -.RS -.IP \- 5 -It generates -.PN EnterNotify -and -.PN LeaveNotify -events (see section 10.6.1) -with the mode members of the -.PN XEnterWindowEvent -and -.PN XLeaveWindowEvent -structures set to -.PN NotifyUngrab . -These events are generated as if the pointer were to suddenly warp from -some position in G to its current position in P. -However, the pointer does not warp, and the X server uses the -current pointer position as both the -initial and final positions for the events. -.RE -.NH 2 -Input Focus Events -.XS -\*(SN Input Focus Events -.XE -.LP -.IN "Events" "FocusIn" -.IN "Events" "FocusOut" -This section describes the processing that occurs for the input focus events -.PN FocusIn -and -.PN FocusOut . -.IN "FocusIn" "" "@DEF@" -.IN "FocusOut" "" "@DEF@" -The X server can report -.PN FocusIn -or -.PN FocusOut -events to clients wanting information about when the input focus changes. -The keyboard is always attached to some window -(typically, the root window or a top-level window), -which is called the focus window. -The focus window and the position of the pointer determine the window that -receives keyboard input. -Clients may need to know when the input focus changes -to control highlighting of areas on the screen. -.LP -To receive -.PN FocusIn -or -.PN FocusOut -events, set the -.PN FocusChangeMask -bit in the event-mask attribute of the window. -.LP -The structure for these event types contains: -.LP -.IN "XFocusChangeEvent" "" "@DEF@" -.IN "XFocusInEvent" "" "@DEF@" -.IN "XFocusOutEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* FocusIn or FocusOut */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* window of event */ - int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ - int detail; - /* - * NotifyAncestor, NotifyVirtual, NotifyInferior, - * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer, - * NotifyPointerRoot, NotifyDetailNone - */ -} XFocusChangeEvent; -typedef XFocusChangeEvent XFocusInEvent; -typedef XFocusChangeEvent XFocusOutEvent; -.De -.LP -.eM -The window member is set to the window on which the -.PN FocusIn -or -.PN FocusOut -event was generated. -This is the window used by the X server to report the event. -The mode member is set to indicate whether the focus events -are normal focus events, -focus events while grabbed, -focus events -when a grab activates, or focus events when a grab deactivates. -The X server can set the mode member to -.PN NotifyNormal , -.PN NotifyWhileGrabbed , -.PN NotifyGrab , -or -.PN NotifyUngrab . -.LP -All -.PN FocusOut -events caused by a window unmap are generated after any -.PN UnmapNotify -event; however, the X protocol does not constrain the ordering of -.PN FocusOut -events with respect to -generated -.PN EnterNotify , -.PN LeaveNotify , -.PN VisibilityNotify , -and -.PN Expose -events. -.LP -Depending on the event mode, -the detail member is set to indicate the notify detail and can be -.PN NotifyAncestor , -.PN NotifyVirtual , -.PN NotifyInferior , -.PN NotifyNonlinear , -.PN NotifyNonlinearVirtual , -.PN NotifyPointer , -.PN NotifyPointerRoot , -or -.PN NotifyDetailNone . -.NH 3 -Normal Focus Events and Focus Events While Grabbed -.XS -\*(SN Normal Focus Events and Focus Events While Grabbed -.XE -.LP -Normal focus events are identified by -.PN XFocusInEvent -or -.PN XFocusOutEvent -structures whose mode member is set to -.PN NotifyNormal . -Focus events while grabbed are identified by -.PN XFocusInEvent -or -.PN XFocusOutEvent -structures whose mode member is set to -.PN NotifyWhileGrabbed . -The X server processes normal focus and focus events while grabbed according to -the following: -.IP \(bu 5 -When the focus moves from window A to window B, A is an inferior of B, -and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -It generates a -.PN FocusOut -event on window A, with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyAncestor . -.IP \- 5 -It generates a -.PN FocusOut -event on each window between window A and window B, exclusive, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on window B, with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyInferior . -.IP \- 5 -If window P is an inferior of window B -but window P is not window A or an inferior or ancestor of window A, -it generates a -.PN FocusIn -event on each window below window B, down to and including window P, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyPointer . -.RE -.IP \(bu 5 -When the focus moves from window A to window B, B is an inferior of A, -and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -If window P is an inferior of window A -but P is not an inferior of window B or an ancestor of B, -it generates a -.PN FocusOut -event on each window from window P up to but not including window A, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyPointer . -.IP \- 5 -It generates a -.PN FocusOut -event on window A, -with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyInferior . -.IP \- 5 -It generates a -.PN FocusIn -event on each window between window A and window B, exclusive, with the -detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on window B, with the detail member of the -.PN XFocusInEvent -structure set to -.PN NotifyAncestor . -.RE -.IP \(bu 5 -When the focus moves from window A to window B, -window C is their least common ancestor, -and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -If window P is an inferior of window A, -it generates a -.PN FocusOut -event on each window from window P up to but not including window A, -with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyPointer . -.IP \- 5 -It generates a -.PN FocusOut -event on window A, -with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -It generates a -.PN FocusOut -event on each window between window A and window C, exclusive, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on each window between C and B, exclusive, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on window B, with the detail member of the -.PN XFocusInEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -If window P is an inferior of window B, it generates a -.PN FocusIn -event on each window below window B down to and including window P, -with the detail member of the -.PN XFocusInEvent -structure set to -.PN NotifyPointer . -.RE -.IP \(bu 5 -When the focus moves from window A to window B on different screens -and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -If window P is an inferior of window A, it generates a -.PN FocusOut -event on each window from window P up to but not including window A, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyPointer . -.IP \- 5 -It generates a -.PN FocusOut -event on window A, -with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -If window A is not a root window, -it generates a -.PN FocusOut -event on each window above window A up to and including its root, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -If window B is not a root window, -it generates a -.PN FocusIn -event on each window from window B's root down to but not including -window B, with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on window B, with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -If window P is an inferior of window B, it generates a -.PN FocusIn -event on each window below window B down to and including window P, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyPointer . -.RE -.IP \(bu 5 -When the focus moves from window A to -.PN PointerRoot -(events sent to the window under the pointer) -or -.PN None -(discard), and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -If window P is an inferior of window A, it generates a -.PN FocusOut -event on each window from window P up to but not including window A, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyPointer . -.IP \- 5 -It generates a -.PN FocusOut -event on window A, with the detail member of the -.PN XFocusOutEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -If window A is not a root window, -it generates a -.PN FocusOut -event on each window above window A up to and including its root, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on the root window of all screens, with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyPointerRoot -(or -.PN NotifyDetailNone ). -.IP \- 5 -If the new focus is -.PN PointerRoot , -it generates a -.PN FocusIn -event on each window from window P's root down to and including window P, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyPointer . -.RE -.IP \(bu 5 -When the focus moves from -.PN PointerRoot -(events sent to the window under the pointer) -or -.PN None -to window A, and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -If the old focus is -.PN PointerRoot , -it generates a -.PN FocusOut -event on each window from window P up to and including window P's root, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyPointer . -.IP \- 5 -It generates a -.PN FocusOut -event on all root windows, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyPointerRoot -(or -.PN NotifyDetailNone ). -.IP \- 5 -If window A is not a root window, -it generates a -.PN FocusIn -event on each window from window A's root down to but not including window A, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyNonlinearVirtual . -.IP \- 5 -It generates a -.PN FocusIn -event on window A, -with the detail member of the -.PN XFocusInEvent -structure set to -.PN NotifyNonlinear . -.IP \- 5 -If window P is an inferior of window A, it generates a -.PN FocusIn -event on each window below window A down to and including window P, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyPointer . -.RE -.IP \(bu 5 -When the focus moves from -.PN PointerRoot -(events sent to the window under the pointer) -to -.PN None -(or vice versa), and the pointer is in window P, -the X server does the following: -.RS -.IP \- 5 -If the old focus is -.PN PointerRoot , -it generates a -.PN FocusOut -event on each window from window P up to and including window P's root, -with the detail member of each -.PN XFocusOutEvent -structure set to -.PN NotifyPointer . -.IP \- 5 -It generates a -.PN FocusOut -event on all root windows, -with the detail member of each -.PN XFocusOutEvent -structure set to either -.PN NotifyPointerRoot -or -.PN NotifyDetailNone . -.IP \- 5 -It generates a -.PN FocusIn -event on all root windows, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyDetailNone -or -.PN NotifyPointerRoot . -.IP \- 5 -If the new focus is -.PN PointerRoot , -it generates a -.PN FocusIn -event on each window from window P's root down to and including window P, -with the detail member of each -.PN XFocusInEvent -structure set to -.PN NotifyPointer . -.RE -.\".SH 3 -.NH 3 -Focus Events Generated by Grabs -.XS -\*(SN Focus Events Generated by Grabs -.XE -.LP -Focus events in which the keyboard grab activates -are identified by -.PN XFocusInEvent -or -.PN XFocusOutEvent -structures whose mode member is set to -.PN NotifyGrab . -Focus events in which the keyboard grab deactivates -are identified by -.PN XFocusInEvent -or -.PN XFocusOutEvent -structures whose mode member is set to -.PN NotifyUngrab -(see -.PN XGrabKeyboard ). -.IP \(bu 5 -When a keyboard grab activates before generating any actual -.PN KeyPress -event that activates the grab, -G is the grab_window, and F is the current focus, -the X server does the following: -.RS -.IP \- 5 -It generates -.PN FocusIn -and -.PN FocusOut -events, with the mode members of the -.PN XFocusInEvent -and -.PN XFocusOutEvent -structures set to -.PN NotifyGrab . -These events are generated -as if the focus were to change from -F to G. -.RE -.IP \(bu 5 -When a keyboard grab deactivates after generating any actual -.PN KeyRelease -event that deactivates the grab, -G is the grab_window, and F is the current focus, -the X server does the following: -.RS -.IP \- 5 -It generates -.PN FocusIn -and -.PN FocusOut -events, with the mode members of the -.PN XFocusInEvent -and -.PN XFocusOutEvent -structures set to -.PN NotifyUngrab . -These events are generated -as if the focus were to change from -G to F. -.RE -.NH 2 -Key Map State Notification Events -.XS -\*(SN Key Map State Notification Events -.XE -.LP -.IN "Events" "KeymapNotify" -.IN "KeymapNotify" "" "@DEF@" -The X server can report -.PN KeymapNotify -events to clients that want information about changes in their keyboard state. -.LP -To receive -.PN KeymapNotify -events, set the -.PN KeymapStateMask -bit in the event-mask attribute of the window. -The X server generates this event immediately after every -.PN EnterNotify -and -.PN FocusIn -event. -.LP -The structure for this event type contains: -.LP -.IN "XKeymapEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -/* generated on EnterWindow and FocusIn when KeymapState selected */ -typedef struct { - int type; /* KeymapNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - char key_vector[32]; -} XKeymapEvent; -.De -.LP -.eM -The window member is not used but is present to aid some toolkits. -The key_vector member is set to the bit vector of the keyboard. -Each bit set to 1 indicates that the corresponding key -is currently pressed. -The vector is represented as 32 bytes. -Byte N (from 0) contains the bits for keys 8N to 8N + 7 -with the least significant bit in the byte representing key 8N. -.NH 2 -Exposure Events -.XS -\*(SN Exposure Events -.XE -.LP -The X protocol does not guarantee to preserve the contents of window -regions when -the windows are obscured or reconfigured. -Some implementations may preserve the contents of windows. -Other implementations are free to destroy the contents of windows -when exposed. -X expects client applications to assume the responsibility for -restoring the contents of an exposed window region. -(An exposed window region describes a formerly obscured window whose -region becomes visible.) -Therefore, the X server sends -.PN Expose -events describing the window and the region of the window that has been exposed. -A naive client application usually redraws the entire window. -A more sophisticated client application redraws only the exposed region. -.NH 3 -Expose Events -.XS -\*(SN Expose Events -.XE -.LP -.IN "Events" "Expose" -.IN "Expose" "" "@DEF@" -The X server can report -.PN Expose -events to clients wanting information about when the contents of window regions -have been lost. -The circumstances in which the X server generates -.PN Expose -events are not as definite as those for other events. -However, the X server never generates -.PN Expose -events on windows whose class you specified as -.PN InputOnly . -The X server can generate -.PN Expose -events when no valid contents are available for regions of a window -and either the regions are visible, -the regions are viewable and the server is (perhaps newly) maintaining -backing store on the window, -or the window is not viewable but the server is (perhaps newly) honoring the -window's backing-store attribute of -.PN Always -or -.PN WhenMapped . -The regions decompose into an (arbitrary) set of rectangles, -and an -.PN Expose -event is generated for each rectangle. -For any given window, -the X server guarantees to report contiguously -all of the regions exposed by some action that causes -.PN Expose -events, such as raising a window. -.LP -To receive -.PN Expose -events, set the -.PN ExposureMask -bit in the event-mask attribute of the window. -.LP -The structure for this event type contains: -.LP -.IN "XExposeEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* Expose */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - int x, y; - int width, height; - int count; /* if nonzero, at least this many more */ -} XExposeEvent; -.De -.LP -.eM -The window member is set to the exposed (damaged) window. -The x and y members are set to the coordinates relative to the window's origin -and indicate the upper-left corner of the rectangle. -The width and height members are set to the size (extent) of the rectangle. -The count member is set to the number of -.PN Expose -events that are to follow. -If count is zero, no more -.PN Expose -events follow for this window. -However, if count is nonzero, at least that number of -.PN Expose -events (and possibly more) follow for this window. -Simple applications that do not want to optimize redisplay by distinguishing -between subareas of its window can just ignore all -.PN Expose -events with nonzero counts and perform full redisplays -on events with zero counts. -.NH 3 -GraphicsExpose and NoExpose Events -.XS -\*(SN GraphicsExpose and NoExpose Events -.XE -.LP -.IN "Events" "GraphicsExpose" -.IN "Events" "NoExpose" -.IN "GraphicsExpose" "" "@DEF@" -The X server can report -.PN GraphicsExpose -events to clients wanting information about when a destination region could not -be computed during certain graphics requests: -.PN XCopyArea -or -.PN XCopyPlane . -The X server generates this event whenever a destination region could not be -computed because of an obscured or out-of-bounds source region. -In addition, the X server guarantees to report contiguously all of the regions exposed by -some graphics request -(for example, copying an area of a drawable to a destination -drawable). -.LP -.IN "NoExpose" "" "@DEF@" -The X server generates a -.PN NoExpose -event whenever a graphics request that might -produce a -.PN GraphicsExpose -event does not produce any. -In other words, the client is really asking for a -.PN GraphicsExpose -event but instead receives a -.PN NoExpose -event. -.LP -To receive -.PN GraphicsExpose -or -.PN NoExpose -events, you must first set the graphics-exposure -attribute of the graphics context to -.PN True . -You also can set the graphics-expose attribute when creating a graphics -context using -.PN XCreateGC -or by calling -.PN XSetGraphicsExposures . -.LP -The structures for these event types contain: -.LP -.IN "XGraphicsExposeEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* GraphicsExpose */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Drawable drawable; - int x, y; - int width, height; - int count; /* if nonzero, at least this many more */ - int major_code; /* core is CopyArea or CopyPlane */ - int minor_code; /* not defined in the core */ -} XGraphicsExposeEvent; -.De -.LP -.IN "XNoExposeEvent" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* NoExpose */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Drawable drawable; - int major_code; /* core is CopyArea or CopyPlane */ - int minor_code; /* not defined in the core */ -} XNoExposeEvent; -.De -.LP -.eM -Both structures have these common members: drawable, major_code, and minor_code. -The drawable member is set to the drawable of the destination region on -which the graphics request was to be performed. -The major_code member is set to the graphics request initiated by the client -and can be either -.PN X_CopyArea -or -.PN X_CopyPlane . -If it is -.PN X_CopyArea , -a call to -.PN XCopyArea -initiated the request. -If it is -.PN X_CopyPlane , -a call to -.PN XCopyPlane -initiated the request. -These constants are defined in -.hN X11/Xproto.h . -The minor_code member, -like the major_code member, -indicates which graphics request was initiated by -the client. -However, the minor_code member is not defined by the core -X protocol and will be zero in these cases, -although it may be used by an extension. -.LP -The -.PN XGraphicsExposeEvent -structure has these additional members: x, y, width, height, and count. -The x and y members are set to the coordinates relative to the drawable's origin -and indicate the upper-left corner of the rectangle. -The width and height members are set to the size (extent) of the rectangle. -The count member is set to the number of -.PN GraphicsExpose -events to follow. -If count is zero, no more -.PN GraphicsExpose -events follow for this window. -However, if count is nonzero, at least that number of -.PN GraphicsExpose -events (and possibly more) are to follow for this window. -.NH 2 -Window State Change Events -.XS -\*(SN Window State Change Events -.XE -.LP -The following sections discuss: -.IP \(bu 5 -.PN CirculateNotify -events -.IP \(bu 5 -.PN ConfigureNotify -events -.IP \(bu 5 -.PN CreateNotify -events -.IP \(bu 5 -.PN DestroyNotify -events -.IP \(bu 5 -.PN GravityNotify -events -.IP \(bu 5 -.PN MapNotify -events -.IP \(bu 5 -.PN MappingNotify -events -.IP \(bu 5 -.PN ReparentNotify -events -.IP \(bu 5 -.PN UnmapNotify -events -.IP \(bu 5 -.PN VisibilityNotify -events -.\" .SH 3 -.NH 3 -CirculateNotify Events -.XS -\*(SN CirculateNotify Events -.XE -.LP -.IN "Events" "CirculateNotify" -.IN "CirculateNotify" "" "@DEF@" -The X server can report -.PN CirculateNotify -events to clients wanting information about when a window changes -its position in the stack. -The X server generates this event type whenever a window is actually restacked -as a result of a client application calling -.PN XCirculateSubwindows , -.PN XCirculateSubwindowsUp , -or -.PN XCirculateSubwindowsDown . -.LP -To receive -.PN CirculateNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window -or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the parent window -(in which case, circulating any child generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XCirculateEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* CirculateNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - int place; /* PlaceOnTop, PlaceOnBottom */ -} XCirculateEvent; -.De -.LP -.eM -The event member is set either to the restacked window or to its parent, -depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -The window member is set to the window that was restacked. -The place member is set to the window's position after the restack occurs and -is either -.PN PlaceOnTop -or -.PN PlaceOnBottom . -If it is -.PN PlaceOnTop , -the window is now on top of all siblings. -If it is -.PN PlaceOnBottom , -the window is now below all siblings. -.NH 3 -ConfigureNotify Events -.XS -\*(SN ConfigureNotify Events -.XE -.LP -.IN "Events" "ConfigureNotify" -.IN "ConfigureNotify" "" "@DEF@" -The X server can report -.PN ConfigureNotify -events to clients wanting information about actual changes to a window's -state, such as size, position, border, and stacking order. -The X server generates this event type whenever one of the following configure -window requests made by a client application actually completes: -.IP \(bu 5 -A window's size, position, border, and/or stacking order is reconfigured -by calling -.PN XConfigureWindow . -.IP \(bu 5 -The window's position in the stacking order is changed by calling -.PN XLowerWindow , -.PN XRaiseWindow , -or -.PN XRestackWindows . -.IP \(bu 5 -A window is moved by calling -.PN XMoveWindow . -.IP \(bu 5 -A window's size is changed by calling -.PN XResizeWindow . -.IP \(bu 5 -A window's size and location is changed by calling -.PN XMoveResizeWindow . -.IP \(bu 5 -A window is mapped and its position in the stacking order is changed -by calling -.PN XMapRaised . -.IP \(bu 5 -A window's border width is changed by calling -.PN XSetWindowBorderWidth . -.LP -To receive -.PN ConfigureNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the parent window -(in which case, configuring any child generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XConfigureEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* ConfigureNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - int x, y; - int width, height; - int border_width; - Window above; - Bool override_redirect; -} XConfigureEvent; -.De -.LP -.eM -The event member is set either to the reconfigured window or to its parent, -depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -The window member is set to the window whose size, position, -border, and/or stacking -order was changed. -.LP -The x and y members are set to the coordinates relative to the parent window's -origin and indicate the position of the upper-left outside corner of the window. -The width and height members are set to the inside size of the window, -not including -the border. -The border_width member is set to the width of the window's border, in pixels. -.LP -The above member is set to the sibling window and is used -for stacking operations. -If the X server sets this member to -.PN None , -the window whose state was changed is on the bottom of the stack -with respect to sibling windows. -However, if this member is set to a sibling window, -the window whose state was changed is placed on top of this sibling window. -.LP -The override_redirect member is set to the override-redirect attribute of the -window. -Window manager clients normally should ignore this window if the -override_redirect member -is -.PN True . -.NH 3 -CreateNotify Events -.XS -\*(SN CreateNotify Events -.XE -.LP -.IN "Events" "CreateNotify" -.IN "CreateNotify" "" "@DEF@" -The X server can report -.PN CreateNotify -events to clients wanting information about creation of windows. -The X server generates this event whenever a client -application creates a window by calling -.PN XCreateWindow -or -.PN XCreateSimpleWindow . -.LP -To receive -.PN CreateNotify -events, set the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the window. -Creating any children then generates an event. -.LP -The structure for the event type contains: -.LP -.IN "XCreateWindowEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* CreateNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window parent; /* parent of the window */ - Window window; /* window id of window created */ - int x, y; /* window location */ - int width, height; /* size of window */ - int border_width; /* border width */ - Bool override_redirect; /* creation should be overridden */ -} XCreateWindowEvent; -.De -.LP -.eM -The parent member is set to the created window's parent. -The window member specifies the created window. -The x and y members are set to the created window's coordinates relative -to the parent window's origin and indicate the position of the upper-left -outside corner of the created window. -The width and height members are set to the inside size of the created window -(not including the border) and are always nonzero. -The border_width member is set to the width of the created window's border, in pixels. -The override_redirect member is set to the override-redirect attribute of the -window. -Window manager clients normally should ignore this window -if the override_redirect member is -.PN True . -.NH 3 -DestroyNotify Events -.XS -\*(SN DestroyNotify Events -.XE -.LP -.IN "Events" "DestroyNotify" -.IN "DestroyNotify" "" "@DEF@" -The X server can report -.PN DestroyNotify -events to clients wanting information about which windows are destroyed. -The X server generates this event whenever a client application destroys a -window by calling -.PN XDestroyWindow -or -.PN XDestroySubwindows . -.LP -The ordering of the -.PN DestroyNotify -events is such that for any given window, -.PN DestroyNotify -is generated on all inferiors of the window -before being generated on the window itself. -The X protocol does not constrain the ordering among -siblings and across subhierarchies. -.LP -To receive -.PN DestroyNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the parent window -(in which case, destroying any child generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XDestroyWindowEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* DestroyNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; -} XDestroyWindowEvent; -.De -.LP -.eM -The event member is set either to the destroyed window or to its parent, -depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -The window member is set to the window that is destroyed. -.NH 3 -GravityNotify Events -.XS -\*(SN GravityNotify Events -.XE -.LP -.IN "Events" "GravityNotify" -.IN "GravityNotify" "" "@DEF@" -The X server can report -.PN GravityNotify -events to clients wanting information about when a window is moved because of a -change in the size of its parent. -The X server generates this event whenever a client -application actually moves a child window as a result of resizing its parent by calling -.PN XConfigureWindow , -.PN XMoveResizeWindow , -or -.PN XResizeWindow . -.LP -To receive -.PN GravityNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the parent window -(in which case, any child that is moved because its parent has been resized -generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XGravityEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* GravityNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - int x, y; -} XGravityEvent; -.De -.LP -.eM -The event member is set either to the window that was moved or to its parent, -depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -The window member is set to the child window that was moved. -The x and y members are set to the coordinates relative to the -new parent window's origin -and indicate the position of the upper-left outside corner of the -window. -.NH 3 -MapNotify Events -.XS -\*(SN MapNotify Events -.XE -.LP -.IN "Events" "MapNotify" -.IN "MapNotify" "" "@DEF@" -The X server can report -.PN MapNotify -events to clients wanting information about which windows are mapped. -The X server generates this event type whenever a client application changes the -window's state from unmapped to mapped by calling -.PN XMapWindow , -.PN XMapRaised , -.PN XMapSubwindows , -.PN XReparentWindow , -or as a result of save-set processing. -.LP -To receive -.PN MapNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the parent window -(in which case, mapping any child generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XMapEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* MapNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - Bool override_redirect; /* boolean, is override set... */ -} XMapEvent; -.De -.LP -.eM -The event member is set either to the window that was mapped or to its parent, -depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -The window member is set to the window that was mapped. -The override_redirect member is set to the override-redirect attribute -of the window. -Window manager clients normally should ignore this window -if the override-redirect attribute is -.PN True , -because these events usually are generated from pop-ups, -which override structure control. -.NH 3 -MappingNotify Events -.XS -\*(SN MappingNotify Events -.XE -.LP -.IN "Events" "MappingNotify" -.IN "MappingNotify" "" "@DEF@" -The X server reports -.PN MappingNotify -events to all clients. -There is no mechanism to express disinterest in this event. -The X server generates this event type whenever a client application -successfully calls: -.IP \(bu 5 -.PN XSetModifierMapping -to indicate which KeyCodes are to be used as modifiers -.IP \(bu 5 -.PN XChangeKeyboardMapping -to change the keyboard mapping -.IP \(bu 5 -.PN XSetPointerMapping -to set the pointer mapping -.LP -The structure for this event type contains: -.LP -.IN "XMappingEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* MappingNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* unused */ - int request; /* one of MappingModifier, MappingKeyboard, - MappingPointer */ - int first_keycode; /* first keycode */ - int count; /* defines range of change w. first_keycode*/ -} XMappingEvent; -.De -.LP -.eM -The request member is set to indicate the kind of mapping change that occurred -and can be -.PN MappingModifier , -.PN MappingKeyboard , -or -.PN MappingPointer . -If it is -.PN MappingModifier , -the modifier mapping was changed. -If it is -.PN MappingKeyboard , -the keyboard mapping was changed. -If it is -.PN MappingPointer , -the pointer button mapping was changed. -The first_keycode and count members are set only -if the request member was set to -.PN MappingKeyboard . -The number in first_keycode represents the first number in the range -of the altered mapping, -and count represents the number of keycodes altered. -.LP -To update the client application's knowledge of the keyboard, -you should call -.PN XRefreshKeyboardMapping . -.NH 3 -ReparentNotify Events -.XS -\*(SN ReparentNotify Events -.XE -.LP -.IN "Events" "ReparentNotify" -.IN "ReparentNotify" "" "@DEF@" -The X server can report -.PN ReparentNotify -events to clients wanting information about changing a window's parent. -The X server generates this event whenever a client -application calls -.PN XReparentWindow -and the window is actually reparented. -.LP -To receive -.PN ReparentNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of either the old or the new parent window -(in which case, reparenting any child generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XReparentEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* ReparentNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - Window parent; - int x, y; - Bool override_redirect; -} XReparentEvent; -.De -.LP -.eM -The event member is set either to the reparented window -or to the old or the new parent, depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -The window member is set to the window that was reparented. -The parent member is set to the new parent window. -The x and y members are set to the reparented window's coordinates relative -to the new parent window's -origin and define the upper-left outer corner of the reparented window. -The override_redirect member is set to the override-redirect attribute of the -window specified by the window member. -Window manager clients normally should ignore this window -if the override_redirect member is -.PN True . -.NH 3 -UnmapNotify Events -.XS -\*(SN UnmapNotify Events -.XE -.LP -.IN "Events" "UnmapNotify" -.IN "UnmapNotify" "" "@DEF@" -The X server can report -.PN UnmapNotify -events to clients wanting information about which windows are unmapped. -The X server generates this event type whenever a client application changes the -window's state from mapped to unmapped. -.LP -To receive -.PN UnmapNotify -events, set the -.PN StructureNotifyMask -bit in the event-mask attribute of the window or the -.PN SubstructureNotifyMask -bit in the event-mask attribute of the parent window -(in which case, unmapping any child window generates an event). -.LP -The structure for this event type contains: -.LP -.IN "XUnmapEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* UnmapNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - Bool from_configure; -} XUnmapEvent; -.De -.LP -.eM -The event member is set either to the unmapped window or to its parent, -depending on whether -.PN StructureNotify -or -.PN SubstructureNotify -was selected. -This is the window used by the X server to report the event. -The window member is set to the window that was unmapped. -The from_configure member is set to -.PN True -if the event was generated as a result of a resizing of the window's parent when -the window itself had a win_gravity of -.PN UnmapGravity . -.NH 3 -VisibilityNotify Events -.XS -\*(SN VisibilityNotify Events -.XE -.LP -.IN "Events" "VisibilityNotify" -.IN "VisibilityNotify" "" "@DEF@" -The X server can report -.PN VisibilityNotify -events to clients wanting any change in the visibility of the specified window. -A region of a window is visible if someone looking at the screen can -actually see it. -The X server generates this event whenever the visibility changes state. -However, this event is never generated for windows whose class is -.PN InputOnly . -.LP -All -.PN VisibilityNotify -events caused by a hierarchy change are generated -after any hierarchy event -.Pn ( UnmapNotify , -.PN MapNotify , -.PN ConfigureNotify , -.PN GravityNotify , -.PN CirculateNotify ) -caused by that change. Any -.PN VisibilityNotify -event on a given window is generated before any -.PN Expose -events on that window, but it is not required that all -.PN VisibilityNotify -events on all windows be generated before all -.PN Expose -events on all windows. -The X protocol does not constrain the ordering of -.PN VisibilityNotify -events with -respect to -.PN FocusOut , -.PN EnterNotify , -and -.PN LeaveNotify -events. -.LP -To receive -.PN VisibilityNotify -events, set the -.PN VisibilityChangeMask -bit in the event-mask attribute of the window. -.LP -The structure for this event type contains: -.LP -.IN "XVisibilityEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* VisibilityNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - int state; -} XVisibilityEvent; -.De -.LP -.eM -The window member is set to the window whose visibility state changes. -The state member is set to the state of the window's visibility and can be -.PN VisibilityUnobscured , -.PN VisibilityPartiallyObscured , -or -.PN VisibilityFullyObscured . -The X server ignores all of a window's subwindows -when determining the visibility state of the window and processes -.PN VisibilityNotify -events according to the following: -.IP \(bu 5 -When the window changes state from partially obscured, fully obscured, -or not viewable to viewable and completely unobscured, -the X server generates the event with the state member of the -.PN XVisibilityEvent -structure set to -.PN VisibilityUnobscured . -.IP \(bu 5 -When the window changes state from viewable and completely unobscured or -not viewable to viewable and partially obscured, -the X server generates the event with the state member of the -.PN XVisibilityEvent -structure set to -.PN VisibilityPartiallyObscured . -.IP \(bu 5 -When the window changes state from viewable and completely unobscured, -viewable and partially obscured, or not viewable to viewable and -fully obscured, -the X server generates the event with the state member of the -.PN XVisibilityEvent -structure set to -.PN VisibilityFullyObscured . -.NH 2 -Structure Control Events -.XS -\*(SN Structure Control Events -.XE -.LP -This section discusses: -.IP \(bu 5 -.PN CirculateRequest -events -.IP \(bu 5 -.PN ConfigureRequest -events -.IP \(bu 5 -.PN MapRequest -events -.IP \(bu 5 -.PN ResizeRequest -events -.NH 3 -CirculateRequest Events -.XS -\*(SN CirculateRequest Events -.XE -.LP -.IN "Events" "CirculateRequest" -.IN "CirculateRequest" "" "@DEF@" -The X server can report -.PN CirculateRequest -events to clients wanting information about -when another client initiates a circulate window request -on a specified window. -The X server generates this event type whenever a client initiates a circulate -window request on a window and a subwindow actually needs to be restacked. -The client initiates a circulate window request on the window by calling -.PN XCirculateSubwindows , -.PN XCirculateSubwindowsUp , -or -.PN XCirculateSubwindowsDown . -.LP -To receive -.PN CirculateRequest -events, set the -.PN SubstructureRedirectMask -in the event-mask attribute of the window. -Then, in the future, -the circulate window request for the specified window is not executed, -and thus, any subwindow's position in the stack is not changed. -For example, suppose a client application calls -.PN XCirculateSubwindowsUp -to raise a subwindow to the top of the stack. -If you had selected -.PN SubstructureRedirectMask -on the window, the X server reports to you a -.PN CirculateRequest -event and does not raise the subwindow to the top of the stack. -.LP -The structure for this event type contains: -.LP -.IN "XCirculateRequestEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* CirculateRequest */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window parent; - Window window; - int place; /* PlaceOnTop, PlaceOnBottom */ -} XCirculateRequestEvent; -.De -.LP -.eM -The parent member is set to the parent window. -The window member is set to the subwindow to be restacked. -The place member is set to what the new position in the stacking order should be -and is either -.PN PlaceOnTop -or -.PN PlaceOnBottom . -If it is -.PN PlaceOnTop , -the subwindow should be on top of all siblings. -If it is -.PN PlaceOnBottom , -the subwindow should be below all siblings. -.NH 3 -ConfigureRequest Events -.XS -\*(SN ConfigureRequest Events -.XE -.LP -.IN "Events" "ConfigureRequest" -.IN "ConfigureRequest" "" "@DEF@" -The X server can report -.PN ConfigureRequest -events to clients wanting information about when a different client initiates -a configure window request on any child of a specified window. -The configure window request attempts to -reconfigure a window's size, position, border, and stacking order. -The X server generates this event whenever a different client initiates -a configure window request on a window by calling -.PN XConfigureWindow , -.PN XLowerWindow , -.PN XRaiseWindow , -.PN XMapRaised , -.PN XMoveResizeWindow , -.PN XMoveWindow , -.PN XResizeWindow , -.PN XRestackWindows , -or -.PN XSetWindowBorderWidth . -.LP -To receive -.PN ConfigureRequest -events, set the -.PN SubstructureRedirectMask -bit in the event-mask attribute of the window. -.PN ConfigureRequest -events are generated when a -.PN ConfigureWindow -protocol request is issued on a child window by another client. -For example, suppose a client application calls -.PN XLowerWindow -to lower a window. -If you had selected -.PN SubstructureRedirectMask -on the parent window and if the override-redirect attribute -of the window is set to -.PN False , -the X server reports a -.PN ConfigureRequest -event to you and does not lower the specified window. -.LP -The structure for this event type contains: -.LP -.IN "XConfigureRequestEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* ConfigureRequest */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window parent; - Window window; - int x, y; - int width, height; - int border_width; - Window above; - int detail; /* Above, Below, TopIf, BottomIf, Opposite */ - unsigned long value_mask; -} XConfigureRequestEvent; -.De -.LP -.eM -The parent member is set to the parent window. -The window member is set to the window whose size, position, border width, -and/or stacking order is to be reconfigured. -The value_mask member indicates which components were specified in the -.PN ConfigureWindow -protocol request. -The corresponding values are reported as given in the request. -The remaining values are filled in from the current geometry of the window, -except in the case of above (sibling) and detail (stack-mode), -which are reported as -.PN None -and -.PN Above , -respectively, if they are not given in the request. -.NH 3 -MapRequest Events -.XS -\*(SN MapRequest Events -.XE -.LP -.IN "Events" "MapRequest" -.IN "MapRequest" "" "@DEF@" -The X server can report -.PN MapRequest -events to clients wanting information about a different client's desire -to map windows. -A window is considered mapped when a map window request completes. -The X server generates this event whenever a different client initiates -a map window request on an unmapped window whose override_redirect member -is set to -.PN False . -Clients initiate map window requests by calling -.PN XMapWindow , -.PN XMapRaised , -or -.PN XMapSubwindows . -.LP -To receive -.PN MapRequest -events, set the -.PN SubstructureRedirectMask -bit in the event-mask attribute of the window. -This means another client's attempts to map a child window by calling one of -the map window request functions is intercepted, and you are sent a -.PN MapRequest -instead. -For example, suppose a client application calls -.PN XMapWindow -to map a window. -If you (usually a window manager) had selected -.PN SubstructureRedirectMask -on the parent window and if the override-redirect attribute -of the window is set to -.PN False , -the X server reports a -.PN MapRequest -event to you -and does not map the specified window. -Thus, this event gives your window manager client the ability -to control the placement of subwindows. -.LP -The structure for this event type contains: -.LP -.IN "XMapRequestEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* MapRequest */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window parent; - Window window; -} XMapRequestEvent; -.De -.LP -.eM -The parent member is set to the parent window. -The window member is set to the window to be mapped. -.NH 3 -ResizeRequest Events -.XS -\*(SN ResizeRequest Events -.XE -.LP -.IN "Events" "ResizeRequest" -.IN "ResizeRequest" "" "@DEF@" -The X server can report -.PN ResizeRequest -events to clients wanting information about another client's attempts to change the -size of a window. -The X server generates this event whenever some other client attempts to change -the size of the specified window by calling -.PN XConfigureWindow , -.PN XResizeWindow , -or -.PN XMoveResizeWindow . -.LP -To receive -.PN ResizeRequest -events, set the -.PN ResizeRedirect -bit in the event-mask attribute of the window. -Any attempts to change the size by other clients are then redirected. -.LP -The structure for this event type contains: -.LP -.IN "XResizeRequestEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* ResizeRequest */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - int width, height; -} XResizeRequestEvent; -.De -.LP -.eM -The window member is set to the window whose size another -client attempted to change. -The width and height members are set to the inside size of the window, -excluding the border. -.NH 2 -Colormap State Change Events -.XS -\*(SN Colormap State Change Events -.XE -.LP -.IN "Events" "ColormapNotify" -.IN "ColormapNotify" "" "@DEF@" -The X server can report -.PN ColormapNotify -events to clients wanting information about when the colormap changes -and when a colormap is installed or uninstalled. -The X server generates this event type whenever a client application: -.IP \(bu 5 -Changes the colormap member of the -.PN XSetWindowAttributes -structure by -calling -.PN XChangeWindowAttributes , -.PN XFreeColormap , -or -.PN XSetWindowColormap -.IP \(bu 5 -Installs or uninstalls the colormap by calling -.PN XInstallColormap -or -.PN XUninstallColormap -.LP -To receive -.PN ColormapNotify -events, set the -.PN ColormapChangeMask -bit in the event-mask attribute of the window. -.LP -The structure for this event type contains: -.LP -.IN "XColormapEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* ColormapNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - Colormap colormap; /* colormap or None */ - Bool new; - int state; /* ColormapInstalled, ColormapUninstalled */ -} XColormapEvent; -.De -.LP -.eM -The window member is set to the window whose associated -colormap is changed, installed, or uninstalled. -For a colormap that is changed, installed, or uninstalled, -the colormap member is set to the colormap associated with the window. -For a colormap that is changed by a call to -.PN XFreeColormap , -the colormap member is set to -.PN None . -The new member is set to indicate whether the colormap -for the specified window was changed or installed or uninstalled -and can be -.PN True -or -.PN False . -If it is -.PN True , -the colormap was changed. -If it is -.PN False , -the colormap was installed or uninstalled. -The state member is always set to indicate whether the colormap is installed or -uninstalled and can be -.PN ColormapInstalled -or -.PN ColormapUninstalled . -.NH 2 -Client Communication Events -.XS -\*(SN Client Communication Events -.XE -.LP -This section discusses: -.IP \(bu 5 -.PN ClientMessage -events -.IP \(bu 5 -.PN PropertyNotify -events -.IP \(bu 5 -.PN SelectionClear -events -.IP \(bu 5 -.PN SelectionNotify -events -.IP \(bu 5 -.PN SelectionRequest -events -.NH 3 -ClientMessage Events -.XS -\*(SN ClientMessage Events -.XE -.LP -.IN "Events" "ClientMessage" -.IN "ClientMessage" "" "@DEF@" -The X server generates -.PN ClientMessage -events only when a client calls the function -.PN XSendEvent . -.LP -The structure for this event type contains: -.LP -.IN "XClientMessageEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 1i 3i -.ta .5i 1i 3i -typedef struct { - int type; /* ClientMessage */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - Atom message_type; - int format; - union { - char b[20]; - short s[10]; - long l[5]; - } data; -} XClientMessageEvent; -.De -.LP -.eM -The message_type member is set to an atom that indicates how the data -should be interpreted by the receiving client. -The format member is set to 8, 16, or 32 and specifies whether the data -should be viewed as a list of bytes, shorts, or longs. -The data member is a union that contains the members b, s, and l. -The b, s, and l members represent data of twenty 8-bit values, -ten 16-bit values, and five 32-bit values. -Particular message types might not make use of all these values. -The X server places no interpretation on the values in the window, -message_type, or data members. -.NH 3 -PropertyNotify Events -.XS -\*(SN PropertyNotify Events -.XE -.LP -.IN "Events" "PropertyNotify" -.IN "PropertyNotify" "" "@DEF@" -The X server can report -.PN PropertyNotify -events to clients wanting information about property changes -for a specified window. -.LP -To receive -.PN PropertyNotify -events, set the -.PN PropertyChangeMask -bit in the event-mask attribute of the window. -.LP -The structure for this event type contains: -.LP -.IN "XPropertyEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* PropertyNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - Atom atom; - Time time; - int state; /* PropertyNewValue or PropertyDelete */ -} XPropertyEvent; -.De -.LP -.eM -The window member is set to the window whose associated -property was changed. -The atom member is set to the property's atom and indicates which -property was changed or desired. -The time member is set to the server time when the property was changed. -The state member is set to indicate whether the property was changed -to a new value or deleted and can be -.PN PropertyNewValue -or -.PN PropertyDelete . -The state member is set to -.PN PropertyNewValue -when a property of the window is changed using -.PN XChangeProperty -or -.PN XRotateWindowProperties -(even when adding zero-length data using -.PN XChangeProperty ) -and when replacing all or part of a property with identical data using -.PN XChangeProperty -or -.PN XRotateWindowProperties . -The state member is set to -.PN PropertyDelete -when a property of the window is deleted using -.PN XDeleteProperty -or, if the delete argument is -.PN True , -.PN XGetWindowProperty . -.NH 3 -SelectionClear Events -.XS -\*(SN SelectionClear Events -.XE -.LP -.IN "Events" "SelectionClear" -.IN "SelectionClear" "" "@DEF@" -The X server reports -.PN SelectionClear -events to the client losing ownership of a selection. -The X server generates this event type when another client -asserts ownership of the selection by calling -.PN XSetSelectionOwner . -.LP -The structure for this event type contains: -.LP -.IN "XSelectionClearEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* SelectionClear */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; - Atom selection; - Time time; -} XSelectionClearEvent; -.De -.LP -.eM -The selection member is set to the selection atom. -The time member is set to the last change time recorded for the -selection. -The window member is the window that was specified by the current owner -(the owner losing the selection) in its -.PN XSetSelectionOwner -call. -.NH 3 -SelectionRequest Events -.XS -\*(SN SelectionRequest Events -.XE -.LP -.IN "Events" "SelectionRequest" -.IN "SelectionRequest" "" "@DEF@" -The X server reports -.PN SelectionRequest -events to the owner of a selection. -The X server generates this event whenever a client -requests a selection conversion by calling -.PN XConvertSelection -for the owned selection. -.LP -The structure for this event type contains: -.LP -.IN "XSelectionRequestEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* SelectionRequest */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window owner; - Window requestor; - Atom selection; - Atom target; - Atom property; - Time time; -} XSelectionRequestEvent; -.De -.LP -.eM -The owner member is set to the window -that was specified by the current owner in its -.PN XSetSelectionOwner -call. -The requestor member is set to the window requesting the selection. -The selection member is set to the atom that names the selection. -For example, PRIMARY is used to indicate the primary selection. -The target member is set to the atom that indicates the type -the selection is desired in. -The property member can be a property name or -.PN None . -The time member is set to the timestamp or -.PN CurrentTime -value from the -.PN ConvertSelection -request. -.LP -The owner should convert the selection based on the specified target type -and send a -.PN SelectionNotify -event back to the requestor. -A complete specification for using selections is given in the X Consortium -standard \fIInter-Client Communication Conventions Manual\fP. -.NH 3 -SelectionNotify Events -.XS -\*(SN SelectionNotify Events -.XE -.LP -.IN "Events" "SelectionNotify" -.IN "SelectionNotify" "" "@DEF@" -This event is generated by the X server in response to a -.PN ConvertSelection -protocol request when there is no owner for the selection. -When there is an owner, it should be generated by the owner -of the selection by using -.PN XSendEvent . -The owner of a selection should send this event to a requestor when a selection -has been converted and stored as a property -or when a selection conversion could -not be performed (which is indicated by setting the property member to -.PN None ). -.LP -If -.PN None -is specified as the property in the -.PN ConvertSelection -protocol request, the owner should choose a property name, -store the result as that property on the requestor window, -and then send a -.PN SelectionNotify -giving that actual property name. -.LP -The structure for this event type contains: -.LP -.IN "XSelectionEvent" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int type; /* SelectionNotify */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came from a SendEvent request */ - Display *display; /* Display the event was read from */ - Window requestor; - Atom selection; - Atom target; - Atom property; /* atom or None */ - Time time; -} XSelectionEvent; -.De -.LP -.eM -The requestor member is set to the window associated with -the requestor of the selection. -The selection member is set to the atom that indicates the selection. -For example, PRIMARY is used for the primary selection. -The target member is set to the atom that indicates the converted type. -For example, PIXMAP is used for a pixmap. -The property member is set to the atom that indicates which -property the result was stored on. -If the conversion failed, -the property member is set to -.PN None . -The time member is set to the time the conversion took place and -can be a timestamp or -.PN CurrentTime . -.bp diff --git a/libX11/specs/libX11/CH10.xml b/libX11/specs/libX11/CH10.xml new file mode 100644 index 000000000..68a5f98f4 --- /dev/null +++ b/libX11/specs/libX11/CH10.xml @@ -0,0 +1,4725 @@ +<chapter id="events">
+<title>Events</title>
+
+<para>
+A client application communicates with the X server through the connection you establish with
+the XOpenDisplay function. A client application sends requests to the X server over this con-
+nection. These requests are made by the Xlib functions that are called in the client application.
+Many Xlib functions cause the X server to generate events, and the user’s typing or moving the
+pointer can generate events asynchronously. The X server returns events to the client on the same
+connection.
+</para>
+<para>
+This chapter discusses the following topics associated with events:
+</para>
+
+<itemizedlist>
+ <listitem><para>Event types</para></listitem>
+ <listitem><para>Event structures</para></listitem>
+ <listitem><para>Event masks</para></listitem>
+ <listitem><para>Event processing</para></listitem>
+</itemizedlist>
+
+<para>
+Functions for handling events are dealt with in the next chapter.
+</para>
+
+<sect1 id="Event_Types">
+<title>Event Types</title>
+<!-- .XS -->
+<!-- (SN Event Types -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Event</primary><secondary>types</secondary></indexterm>
+An event is data generated asynchronously by the X server as a result of some
+device activity or as side effects of a request sent by an Xlib function.
+<indexterm><primary>Event</primary></indexterm>
+Device-related events propagate from the source window to ancestor windows
+until some client application has selected that event type
+or until the event is explicitly discarded.
+The X server generally sends an event to a client application
+only if the client has specifically asked to be informed of that event type,
+typically by setting the event-mask attribute of the window.
+The mask can also be set when you create a window
+or by changing the window's
+event-mask.
+You can also mask out events that would propagate to ancestor windows
+by manipulating the
+do-not-propagate mask of the window's attributes.
+However,
+<function>MappingNotify</function>
+events are always sent to all clients.
+<indexterm><primary>Input Control</primary></indexterm>
+<indexterm><primary>Output Control</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+An event type describes a specific event generated by the X server.
+For each event type,
+a corresponding constant name is defined in
+<!-- .hN X11/X.h , -->
+which is used when referring to an event type.
+<indexterm><primary>Event</primary><secondary>categories</secondary></indexterm>
+The following table lists the event category
+and its associated event type or types.
+The processing associated with these events is discussed in section 10.5.
+</para>
+<para>
+<!-- .LP -->
+<!-- .\".CP T 1 -->
+<!-- .\"Event Categories and Event Types -->
+</para>
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Event Category</entry>
+ <entry>Event Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Keyboard events</entry>
+ <entry><function>KeyPress</function>,
+ <function>KeyRelease</function></entry>
+ </row>
+ <row>
+ <entry>Pointer events</entry>
+ <entry><function>ButtonPress</function>,
+ <function>ButtonRelease</function>,
+ <function>MotionNotify</function></entry>
+ </row>
+ <row>
+ <entry>Window crossing events</entry>
+ <entry><function>EnterNotify</function>,
+ <function>LeaveNotify</function></entry>
+ </row>
+ <row>
+ <entry>Input focus events</entry>
+ <entry><function>FocusIn</function>,
+ <function>FocusOut</function></entry>
+ </row>
+ <row>
+ <entry>Keymap state notification event</entry>
+ <entry><function>KeymapNotify</function></entry>
+ </row>
+ <row>
+ <entry>Exposure events</entry>
+ <entry><function>Expose</function>,
+ <function>GraphicsExpose</function>,
+ <function>NoExpose</function></entry>
+ </row>
+ <row>
+ <entry>Structure control events</entry>
+ <entry><function>CirculateRequest</function>,
+ <function>ConfigureRequest</function>,
+ <function>MapRequest</function>,
+ <function>ResizeRequest</function></entry>
+ </row>
+ <row>
+ <entry>Window state notification events</entry>
+ <entry>
+ <function>CirculateNotify</function>,
+ <function>ConfigureNotify</function>,
+ <function>CreateNotify</function>,
+ <function>DestroyNotify</function>,
+ <function>GravityNotify</function>,
+ <function>MapNotify</function>,
+ <function>MappingNotify</function>,
+ <function>ReparentNotify</function>,
+ <function>UnmapNotify</function>,
+ <function>VisibilityNotify</function></entry>
+ </row>
+ <row>
+ <entry>Colormap state notification event</entry>
+ <entry><function>ColormapNotify</function></entry>
+ </row>
+ <row>
+ <entry>Client communication events</entry>
+ <entry><function>ClientMessage</function>,
+ <function>PropertyNotify</function>,
+ <function>SelectionClear</function>,
+ <function>SelectionNotify</function>,
+ <function>SelectionRequest</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .\".LP -->
+<!-- .\"Table 8-1 lists the event types and the Xlib functions that could cause -->
+<!-- .\"the X server to generate that event type. -->
+<!-- .\"The event types are listed alphabetically. -->
+<!-- .\"Note that the error event is not listed in this table. -->
+<!-- .\"For a list of the constants associated with an error event, see the Handling -->
+<!-- .\"Errors section in this chapter. -->
+<!-- .\".LP -->
+<!-- .\".so eventtable -->
+</para>
+</sect1>
+<sect1 id="Event_Structures">
+<title>Event Structures</title>
+<!-- .XS -->
+<!-- (SN Event Structures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+For each event type,
+a corresponding structure is declared in
+<!-- .hN X11/Xlib.h . -->
+All the event structures have the following common members:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type;
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+} XAnyEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The type member is set to the event type constant name that uniquely identifies
+it.
+For example, when the X server reports a
+<function>GraphicsExpose</function>
+event to a client application, it sends an
+<function>XGraphicsExposeEvent</function>
+structure with the type member set to
+<function>GraphicsExpose</function>.
+The display member is set to a pointer to the display the event was read on.
+The send_event member is set to
+<function>True</function>
+if the event came from a
+<function>SendEvent</function>
+protocol request.
+The serial member is set from the serial number reported in the protocol
+but expanded from the 16-bit least-significant bits to a full 32-bit value.
+The window member is set to the window that is most useful to toolkit
+dispatchers.
+</para>
+<para>
+<!-- .LP -->
+The X server can send events at any time in the input stream.
+Xlib stores any events received while waiting for a reply in an event queue
+for later use.
+Xlib also provides functions that allow you to check events
+in the event queue (see section 11.3).
+</para>
+<para>
+<!-- .LP -->
+In addition to the individual structures declared for each event type, the
+<function>XEvent</function>
+structure is a union of the individual structures declared for each event type.
+Depending on the type,
+you should access members of each event by using the
+<function>XEvent</function>
+union.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XEvent</primary></indexterm>
+<!-- .sM -->
+</para>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef union _XEvent {
+ int type; /* must not be changed */
+ XAnyEvent xany;
+ XKeyEvent xkey;
+ XButtonEvent xbutton;
+ XMotionEvent xmotion;
+ XCrossingEvent xcrossing;
+ XFocusChangeEvent xfocus;
+ XExposeEvent xexpose;
+ XGraphicsExposeEvent xgraphicsexpose;
+ XNoExposeEvent xnoexpose;
+ XVisibilityEvent xvisibility;
+ XCreateWindowEvent xcreatewindow;
+ XDestroyWindowEvent xdestroywindow;
+ XUnmapEvent xunmap;
+ XMapEvent xmap;
+ XMapRequestEvent xmaprequest;
+ XReparentEvent xreparent;
+ XConfigureEvent xconfigure;
+ XGravityEvent xgravity;
+ XResizeRequestEvent xresizerequest;
+ XConfigureRequestEvent xconfigurerequest;
+ XCirculateEvent xcirculate;
+ XCirculateRequestEvent xcirculaterequest;
+ XPropertyEvent xproperty;
+ XSelectionClearEvent xselectionclear;
+ XSelectionRequestEvent xselectionrequest;
+ XSelectionEvent xselection;
+ XColormapEvent xcolormap;
+ XClientMessageEvent xclient;
+ XMappingEvent xmapping;
+ XErrorEvent xerror;
+ XKeymapEvent xkeymap;
+ long pad[24];
+} XEvent;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+An
+<function>XEvent</function>
+structure's first entry always is the type member,
+which is set to the event type.
+The second member always is the serial number of the protocol request
+that generated the event.
+The third member always is send_event,
+which is a
+<function>Bool</function>
+that indicates if the event was sent by a different client.
+The fourth member always is a display,
+which is the display that the event was read from.
+Except for keymap events,
+the fifth member always is a window,
+which has been carefully selected to be useful to toolkit dispatchers.
+To avoid breaking toolkits,
+the order of these first five entries is not to change.
+Most events also contain a time member,
+which is the time at which an event occurred.
+In addition, a pointer to the generic event must be cast before it
+is used to access any other information in the structure.
+</para>
+</sect1>
+<sect1 id="Event_Masks">
+<title>Event Masks</title>
+<!-- .XS -->
+<!-- (SN Event Masks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Event mask</primary></indexterm>
+Clients select event reporting of most events relative to a window.
+To do this, pass an event mask to an Xlib event-handling
+function that takes an event_mask argument.
+The bits of the event mask are defined in
+<!-- .hN X11/X.h . -->
+Each bit in the event mask maps to an event mask name,
+which describes the event or events you want the X server to
+return to a client application.
+</para>
+<para>
+<!-- .LP -->
+Unless the client has specifically asked for them,
+most events are not reported to clients when they are generated.
+Unless the client suppresses them by setting graphics-exposures in the GC to
+<function>False</function>,
+<function>GraphicsExpose </function>
+and
+<function>NoExpose </function>
+are reported by default as a result of
+<function>XCopyPlane</function>
+and
+<function>XCopyArea</function>.
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+or
+<function>ClientMessage</function>
+cannot be masked.
+Selection-related events are only sent to clients cooperating
+with selections (see section 4.5).
+When the keyboard or pointer mapping is changed,
+<function>MappingNotify</function>
+is always sent to clients.
+</para>
+<para>
+<!-- .LP -->
+<!-- .\"Table 8-2 -->
+The following table
+lists the event mask constants you can pass to
+the event_mask argument and
+the circumstances in which you would want to specify the
+event mask:
+</para>
+<!-- .LP -->
+<!-- .\" .CP T 2 -->
+<!-- .\"Event Mask Definitions -->
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Event Mask</entry>
+ <entry>Circumstances</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>NoEventMask</function></entry>
+ <entry>No events wanted</entry>
+ </row>
+ <row>
+ <entry><function>KeyPressMask</function></entry>
+ <entry>Keyboard down events wanted</entry>
+ </row>
+ <row>
+ <entry><function>KeyReleaseMask</function></entry>
+ <entry>Keyboard up events wanted</entry>
+ </row>
+ <row>
+ <entry><function>ButtonPressMask</function></entry>
+ <entry>Pointer button down events wanted</entry>
+ </row>
+ <row>
+ <entry><function>ButtonReleaseMask</function></entry>
+ <entry>Pointer button up events wanted</entry>
+ </row>
+ <row>
+ <entry><function>EnterWindowMask</function></entry>
+ <entry>Pointer window entry events wanted</entry>
+ </row>
+ <row>
+ <entry><function>LeaveWindowMask</function></entry>
+ <entry>Pointer window leave events wanted</entry>
+ </row>
+ <row>
+ <entry><function>PointerMotionMask</function></entry>
+ <entry>Pointer motion events wanted</entry>
+ </row>
+ <row>
+ <entry><function>PointerMotionHintMask</function></entry>
+ <entry>Pointer motion hints wanted</entry>
+ </row>
+ <row>
+ <entry><function>Button1MotionMask</function></entry>
+ <entry>Pointer motion while button 1 down</entry>
+ </row>
+ <row>
+ <entry><function>Button2MotionMask</function></entry>
+ <entry>Pointer motion while button 2 down</entry>
+ </row>
+ <row>
+ <entry><function>Button3MotionMask</function></entry>
+ <entry>Pointer motion while button 3 down</entry>
+ </row>
+ <row>
+ <entry><function>Button4MotionMask</function></entry>
+ <entry>Pointer motion while button 4 down</entry>
+ </row>
+ <row>
+ <entry><function>Button5MotionMask</function></entry>
+ <entry>Pointer motion while button 5 down</entry>
+ </row>
+ <row>
+ <entry><function>ButtonMotionMask</function></entry>
+ <entry>Pointer motion while any button down</entry>
+ </row>
+ <row>
+ <entry><function>KeymapStateMask</function></entry>
+ <entry>Keyboard state wanted at window entry and focus in</entry>
+ </row>
+ <row>
+ <entry><function>ExposureMask</function></entry>
+ <entry>Any exposure wanted</entry>
+ </row>
+ <row>
+ <entry><function>VisibilityChangeMask</function></entry>
+ <entry>Any change in visibility wanted</entry>
+ </row>
+ <row>
+ <entry><function>StructureNotifyMask</function></entry>
+ <entry>Any change in window structure wanted</entry>
+ </row>
+ <row>
+ <entry><function>ResizeRedirectMask</function></entry>
+ <entry>Redirect resize of this window</entry>
+ </row>
+ <row>
+ <entry><function>SubstructureNotifyMask</function></entry>
+ <entry>Substructure notification wanted</entry>
+ </row>
+ <row>
+ <entry><function>SubstructureRedirectMask</function></entry>
+ <entry>Redirect structure requests on children</entry>
+ </row>
+ <row>
+ <entry><function>FocusChangeMask</function></entry>
+ <entry>Any change in input focus wanted</entry>
+ </row>
+ <row>
+ <entry><function>PropertyChangeMask</function></entry>
+ <entry>Any change in property wanted</entry>
+ </row>
+ <row>
+ <entry><function>ColormapChangeMask</function></entry>
+ <entry>Any change in colormap wanted</entry>
+ </row>
+ <row>
+ <entry><function>OwnerGrabButtonMask</function></entry>
+ <entry>Automatic grabs should activate with owner_events set to True</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+</para>
+</sect1>
+<sect1 id="Event_Processing_Overview">
+<title>Event Processing Overview</title>
+<!-- .XS -->
+<!-- (SN Event Processing Overview -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The event reported to a client application during event processing
+depends on which event masks you provide as the event-mask attribute
+for a window.
+For some event masks, there is a one-to-one correspondence between
+the event mask constant and the event type constant.
+For example, if you pass the event mask
+<function>ButtonPressMask</function>,
+the X server sends back only
+<function>ButtonPress</function>
+events.
+<indexterm><primary>CurrentTime</primary></indexterm>
+Most events contain a time member,
+which is the time at which an event occurred.
+</para>
+<para>
+<!-- .LP -->
+In other cases, one event mask constant can map to several event type constants.
+For example, if you pass the event mask
+<function>SubstructureNotifyMask</function>,
+the X server can send back
+<function>CirculateNotify</function>,
+<function>ConfigureNotify</function>,
+<function>CreateNotify</function>,
+<function>DestroyNotify</function>,
+<function>GravityNotify</function>,
+<function>MapNotify</function>,
+<function>ReparentNotify</function>,
+or
+<function>UnmapNotify</function>
+events.
+</para>
+<para>
+<!-- .LP -->
+In another case,
+two event masks can map to one event type.
+For example,
+if you pass either
+<function>PointerMotionMask </function>
+or
+<function>ButtonMotionMask</function>,
+the X server sends back
+a
+<function>MotionNotify</function>
+event.
+</para>
+<para>
+<!-- .LP -->
+The following table
+lists the event mask,
+its associated event type or types,
+and the structure name associated with the event type.
+Some of these structures actually are typedefs to a generic structure
+that is shared between two event types.
+Note that N.A. appears in columns for which the information is not applicable.
+</para>
+<!-- .LP -->
+<!-- .ps 9 -->
+<!-- .nr PS 9 -->
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Event Mask</entry>
+ <entry>Event Type</entry>
+ <entry>Structure</entry>
+ <entry>Generic Structure</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ButtonMotionMask</entry>
+ <entry>MotionNotify</entry>
+ <entry>XPointerMovedEvent</entry>
+ <entry>XMotionEvent</entry>
+ </row>
+ <row>
+ <entry>Button1MotionMask</entry>
+ </row>
+ <row>
+ <entry>Button2MotionMask</entry>
+ </row>
+ <row>
+ <entry>Button3MotionMask</entry>
+ </row>
+ <row>
+ <entry>Button4MotionMask</entry>
+ </row>
+ <row>
+ <entry>Button5MotionMask</entry>
+ </row>
+ <row>
+ <entry>ButtonPressMask</entry>
+ <entry>ButtonPress</entry>
+ <entry>XButtonPressedEvent</entry>
+ <entry>XButtonEvent</entry>
+ </row>
+ <row>
+ <entry>ButtonReleaseMask</entry>
+ <entry>ButtonRelease</entry>
+ <entry>XButtonReleasedEvent</entry>
+ <entry>XButtonEvent</entry>
+ </row>
+ <row>
+ <entry>ColormapChangeMask</entry>
+ <entry>ColormapNotify</entry>
+ <entry>XColormapEvent</entry>
+ </row>
+ <row>
+ <entry>EnterWindowMask</entry>
+ <entry>EnterNotify</entry>
+ <entry>XEnterWindowEvent</entry>
+ <entry>XCrossingEvent</entry>
+ </row>
+ <row>
+ <entry>LeaveWindowMask</entry>
+ <entry>LeaveNotify</entry>
+ <entry>XLeaveWindowEvent</entry>
+ <entry>XCrossingEvent</entry>
+ </row>
+ <row>
+ <entry>ExposureMask</entry>
+ <entry>Expose</entry>
+ <entry>XExposeEvent </entry>
+ </row>
+ <row>
+ <entry>GCGraphicsExposures in GC</entry>
+ <entry>GraphicsExpose</entry>
+ <entry>XGraphicsExposeEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>NoExpose</entry>
+ <entry>XNoExposeEvent</entry>
+ </row>
+ <row>
+ <entry>FocusChangeMask</entry>
+ <entry>FocusIn</entry>
+ <entry>XFocusInEvent</entry>
+ <entry>XFocusChangeEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>FocusOut</entry>
+ <entry>XFocusOutEvent</entry>
+ <entry>XFocusChangeEvent</entry>
+ </row>
+ <row>
+ <entry>KeymapStateMask</entry>
+ <entry>KeymapNotify</entry>
+ <entry>XKeymapEvent</entry>
+ </row>
+ <row>
+ <entry>KeyPressMask</entry>
+ <entry>KeyPress</entry>
+ <entry>XKeyPressedEvent</entry>
+ <entry>XKeyEvent</entry>
+ </row>
+ <row>
+ <entry>KeyReleaseMask</entry>
+ <entry>KeyRelease</entry>
+ <entry>XKeyReleasedEvent</entry>
+ <entry>XKeyEvent</entry>
+ </row>
+ <row>
+ <entry>OwnerGrabButtonMask</entry>
+ <entry>N.A.</entry>
+ <entry>N.A.</entry>
+ </row>
+ <row>
+ <entry>PointerMotionMask</entry>
+ <entry>MotionNotify</entry>
+ <entry>XPointerMovedEvent</entry>
+ <entry>XMotionEvent</entry>
+ </row>
+ <row>
+ <entry>PointerMotionHintMask</entry>
+ <entry>N.A.</entry>
+ <entry>N.A.</entry>
+ </row>
+ <row>
+ <entry>PropertyChangeMask</entry>
+ <entry>PropertyNotify</entry>
+ <entry>XPropertyEvent</entry>
+ </row>
+ <row>
+ <entry>ResizeRedirectMask</entry>
+ <entry>ResizeRequest</entry>
+ <entry>XResizeRequestEvent</entry>
+ </row>
+ <row>
+ <entry>StructureNotifyMask</entry>
+ <entry>CirculateNotify</entry>
+ <entry>XCirculateEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>ConfigureNotify</entry>
+ <entry>XConfigureEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>DestroyNotify</entry>
+ <entry>XDestroyWindowEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>GravityNotify</entry>
+ <entry>XGravityEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>MapNotify</entry>
+ <entry>XMapEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>ReparentNotify</entry>
+ <entry>XReparentEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>UnmapNotify</entry>
+ <entry>XUnmapEvent</entry>
+ </row>
+ <row>
+ <entry>SubstructureNotifyMask</entry>
+ <entry>CirculateNotify</entry>
+ <entry>XCirculateEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>ConfigureNotify</entry>
+ <entry>XConfigureEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>CreateNotify</entry>
+ <entry>XCreateWindowEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>DestroyNotify</entry>
+ <entry>XDestroyWindowEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>GravityNotify</entry>
+ <entry>XGravityEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>MapNotify</entry>
+ <entry>XMapEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>ReparentNotify</entry>
+ <entry>XReparentEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>UnmapNotify</entry>
+ <entry>XUnmapEvent</entry>
+ </row>
+ <row>
+ <entry>SubstructureRedirectMask</entry>
+ <entry>CirculateRequest</entry>
+ <entry>XCirculateRequestEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>ConfigureRequest</entry>
+ <entry>XConfigureRequestEvent</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>MapRequest</entry>
+ <entry>XMapRequestEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>ClientMessage</entry>
+ <entry>XClientMessageEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>MappingNotify</entry>
+ <entry>XMappingEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>SelectionClear</entry>
+ <entry>XSelectionClearEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>SelectionNotify</entry>
+ <entry>XSelectionEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>SelectionRequest</entry>
+ <entry>XSelectionRequestEvent</entry>
+ </row>
+ <row>
+ <entry>VisibilityChangeMask</entry>
+ <entry>VisibilityNotify</entry>
+ <entry>XVisibilityEvent</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+The sections that follow describe the processing that occurs
+when you select the different event masks.
+The sections are organized according to these processing categories:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Keyboard and pointer events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Window crossing events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input focus events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keymap state notification events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Exposure events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Window state notification events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Structure control events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Colormap state notification events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Client communication events
+ </para>
+ </listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="Keyboard_and_Pointer_Events">
+<title>Keyboard and Pointer Events</title>
+<!-- .XS -->
+<!-- (SN Keyboard and Pointer Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Pointer button events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keyboard and pointer events
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Pointer_Button_Events">
+<title>Pointer Button Events</title>
+<!-- .XS -->
+<!-- (SN Pointer Button Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following describes the event processing that occurs when a pointer button
+press is processed with the pointer in some window w and
+when no active pointer grab is in progress.
+</para>
+<para>
+<!-- .LP -->
+The X server searches the ancestors of w from the root down,
+looking for a passive grab to activate.
+If no matching passive grab on the button exists,
+the X server automatically starts an active grab for the client receiving
+the event and sets the last-pointer-grab time to the current server time.
+The effect is essentially equivalent to an
+<function>XGrabButton</function>
+with these client passed arguments:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><emphasis remap='I'>w</emphasis></entry>
+ <entry>The event window </entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>event_mask</emphasis></entry>
+ <entry>The client's selected pointer events on the event window</entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>pointer_mode</emphasis></entry>
+ <entry><function>GrabModeAsync</function></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>keyboard_mode</emphasis></entry>
+ <entry><function>GrabModeAsync </function></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>owner_events</emphasis></entry>
+ <entry><function>True</function>,
+ if the client has selected
+ <function>OwnerGrabButtonMask</function>
+ on the event window,
+ otherwise
+ <function>False </function></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>confine_to</emphasis></entry>
+ <entry><function>None </function></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>cursor</emphasis></entry>
+ <entry><function>None </function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+The active grab is automatically terminated when
+the logical state of the pointer has all buttons released.
+Clients can modify the active grab by calling
+<function>XUngrabPointer</function>
+and
+<function>XChangeActivePointerGrab</function>.
+</para>
+</sect2>
+
+<sect2 id="Keyboard_and_Pointer_Events_b">
+<title>Keyboard and Pointer Events</title>
+<!-- .XS -->
+<!-- (SN Keyboard and Pointer Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm>
+This section discusses the processing that occurs for the
+keyboard events
+<function>KeyPress</function>
+and
+<function>KeyRelease </function>
+and the pointer events
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+and
+<function>MotionNotify</function>.
+For information about the keyboard event-handling utilities,
+see chapter 11.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>KeyPress</primary></indexterm>
+<indexterm significance="preferred"><primary>KeyRelease</primary></indexterm>
+The X server reports
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+events to clients wanting information about keys that logically change state.
+Note that these events are generated for all keys,
+even those mapped to modifier bits.
+<indexterm significance="preferred"><primary>ButtonPress</primary></indexterm>
+<indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm>
+The X server reports
+<function>ButtonPress</function>
+or
+<function>ButtonRelease</function>
+events to clients wanting information about buttons that logically change state.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>MotionNotify</primary></indexterm>
+The X server reports
+<function>MotionNotify</function>
+events to clients wanting information about when the pointer logically moves.
+The X server generates this event whenever the pointer is moved
+and the pointer motion begins and ends in the window.
+The granularity of
+<function>MotionNotify</function>
+events is not guaranteed,
+but a client that selects this event type is guaranteed
+to receive at least one event when the pointer moves and then rests.
+</para>
+<para>
+<!-- .LP -->
+The generation of the logical changes lags the physical changes
+if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+and
+<function>ButtonRelease </function>
+events, set
+<function>KeyPressMask</function>,
+<function>KeyReleaseMask</function>,
+<function>ButtonPressMask</function>,
+and
+<function>ButtonReleaseMask </function>
+bits in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>MotionNotify</function>
+events, set one or more of the following event
+masks bits in the event-mask attribute of the window.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>Button1MotionMask \ \-</function>
+<function>Button5MotionMask</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client application receives
+<function>MotionNotify</function>
+events only when one or more of the specified buttons is pressed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>ButtonMotionMask</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client application receives
+<function>MotionNotify</function>
+events only when at least one button is pressed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>PointerMotionMask</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client application receives
+<function>MotionNotify</function>
+events independent of the state of
+the pointer buttons.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>PointerMotionHintMask</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If
+<function>PointerMotionHintMask</function>
+is selected in combination with one or more of the above masks,
+the X server is free to send only one
+<function>MotionNotify</function>
+event (with the is_hint member of the
+<function>XPointerMovedEvent</function>
+structure set to
+<function>NotifyHint</function>)
+to the client for the event window,
+until either the key or button state changes,
+the pointer leaves the event window, or the client calls
+<function>XQueryPointer</function>
+or
+<function>XGetMotionEvents</function>.
+The server still may send
+<function>MotionNotify</function>
+events without is_hint set to
+<function>NotifyHint</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The source of the event is the viewable window that the pointer is in.
+The window used by the X server to report these events depends on
+the window's position in the window hierarchy
+and whether any intervening window prohibits the generation of these events.
+Starting with the source window,
+the X server searches up the window hierarchy until it locates the first
+window specified by a client as having an interest in these events.
+If one of the intervening windows has its do-not-propagate-mask
+set to prohibit generation of the event type,
+the events of those types will be suppressed.
+Clients can modify the actual window used for reporting by performing
+active grabs and, in the case of keyboard events, by using the focus window.
+</para>
+<para>
+<!-- .LP -->
+The structures for these event types contain:
+</para>
+<literallayout class="monospaced">
+typedef struct {
+ int type; /* ButtonPress or ButtonRelease */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window it is reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ unsigned int state; /* key or button mask */
+ unsigned int button; /* detail */
+ Bool same_screen; /* same screen flag */
+} XButtonEvent;
+typedef XButtonEvent XButtonPressedEvent;
+typedef XButtonEvent XButtonReleasedEvent;
+</literallayout>
+
+<literallayout class="monospaced">
+typedef struct {
+ int type; /* KeyPress or KeyRelease */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window it is reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ unsigned int state; /* key or button mask */
+ unsigned int keycode; /* detail */
+ Bool same_screen; /* same screen flag */
+} XKeyEvent;
+typedef XKeyEvent XKeyPressedEvent;
+typedef XKeyEvent XKeyReleasedEvent;
+</literallayout>
+
+<literallayout class="monospaced">
+typedef struct {
+ int type; /* MotionNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ unsigned int state; /* key or button mask */
+ char is_hint; /* detail */
+ Bool same_screen; /* same screen flag */
+} XMotionEvent;
+typedef XMotionEvent XPointerMovedEvent;
+</literallayout>
+
+<para>
+These structures have the following common members:
+window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
+The window member is set to the window on which the
+event was generated and is referred to as the event window.
+As long as the conditions previously discussed are met,
+this is the window used by the X server to report the event.
+The root member is set to the source window's root window.
+The x_root and y_root members are set to the pointer's coordinates
+relative to the root window's origin at the time of the event.
+</para>
+
+<para>
+<!-- .LP -->
+The same_screen member is set to indicate whether the event
+window is on the same screen
+as the root window and can be either
+<function>True </function>
+or
+<function>False</function>.
+If
+<function>True</function>,
+the event and root windows are on the same screen.
+If
+<function>False</function>,
+the event and root windows are not on the same screen.
+</para>
+<para>
+<!-- .LP -->
+If the source window is an inferior of the event window,
+the subwindow member of the structure is set to the child of the event window
+that is the source window or the child of the event window that is
+an ancestor of the source window.
+Otherwise, the X server sets the subwindow member to
+<function>None</function>.
+The time member is set to the time when the event was generated
+and is expressed in milliseconds.
+</para>
+<para>
+<!-- .LP -->
+If the event window is on the same screen as the root window,
+the x and y members
+are set to the coordinates relative to the event window's origin.
+Otherwise, these members are set to zero.
+</para>
+<para>
+<!-- .LP -->
+The state member is set to indicate the logical state of the pointer buttons
+and modifier keys just prior to the event,
+which is the bitwise inclusive OR of one or more of the
+button or modifier key masks:
+<function>Button1Mask</function>,
+<function>Button2Mask</function>,
+<function>Button3Mask</function>,
+<function>Button4Mask</function>,
+<function>Button5Mask</function>,
+<function>ShiftMask</function>,
+<function>LockMask</function>,
+<function>ControlMask</function>,
+<function>Mod1Mask</function>,
+<function>Mod2Mask</function>,
+<function>Mod3Mask</function>,
+<function>Mod4Mask</function>,
+and
+<function>Mod5Mask</function>.
+</para>
+<para>
+<!-- .LP -->
+Each of these structures also has a member that indicates the detail.
+For the
+<function>XKeyPressedEvent</function>
+and
+<function>XKeyReleasedEvent</function>
+structures, this member is called a keycode.
+It is set to a number that represents a physical key on the keyboard.
+The keycode is an arbitrary representation for any key on the keyboard
+(see sections 12.7 and 16.1).
+</para>
+<para>
+<!-- .LP -->
+For the
+<function>XButtonPressedEvent</function>
+and
+<function>XButtonReleasedEvent</function>
+structures, this member is called button.
+It represents the pointer button that changed state and can be the
+<function>Button1</function>,
+<function>Button2</function>,
+<function>Button3</function>,
+<function>Button4</function>,
+or
+<function>Button5 </function>
+value.
+For the
+<function>XPointerMovedEvent</function>
+structure, this member is called is_hint.
+It can be set to
+<function>NotifyNormal</function>
+or
+<function>NotifyHint</function>.
+</para>
+<para>
+<!-- .LP -->
+Some of the symbols mentioned in this section have fixed values, as
+follows:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Symbol</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>Button1MotionMask</function></entry>
+ <entry>(1L<<8)</entry>
+ </row>
+ <row>
+ <entry><function>Button2MotionMask</function></entry>
+ <entry>(1L<<9)</entry>
+ </row>
+ <row>
+ <entry><function>Button3MotionMask</function></entry>
+ <entry>(1L<<10)</entry>
+ </row>
+ <row>
+ <entry><function>Button4MotionMask</function></entry>
+ <entry>(1L<<11)</entry>
+ </row>
+ <row>
+ <entry><function>Button5MotionMask</function></entry>
+ <entry>(1L<<12)</entry>
+ </row>
+ <row>
+ <entry><function>Button1Mask</function></entry>
+ <entry>(1<<8)</entry>
+ </row>
+ <row>
+ <entry><function>Button2Mask</function></entry>
+ <entry>(1<<9)</entry>
+ </row>
+ <row>
+ <entry><function>Button3Mask</function></entry>
+ <entry>(1<<10)</entry>
+ </row>
+ <row>
+ <entry><function>Button4Mask</function></entry>
+ <entry>(1<<11)</entry>
+ </row>
+ <row>
+ <entry><function>Button5Mask</function></entry>
+ <entry>(1<<12)</entry>
+ </row>
+ <row>
+ <entry><function>ShiftMask</function></entry>
+ <entry>(1<<0)</entry>
+ </row>
+ <row>
+ <entry><function>LockMask</function></entry>
+ <entry>(1<<1)</entry>
+ </row>
+ <row>
+ <entry><function>ControlMask</function></entry>
+ <entry>(1<<2)</entry>
+ </row>
+ <row>
+ <entry><function>Mod1Mask</function></entry>
+ <entry>(1<<3)</entry>
+ </row>
+ <row>
+ <entry><function>Mod2Mask</function></entry>
+ <entry>(1<<4)</entry>
+ </row>
+ <row>
+ <entry><function>Mod3Mask</function></entry>
+ <entry>(1<<5)</entry>
+ </row>
+ <row>
+ <entry><function>Mod4Mask</function></entry>
+ <entry>(1<<6)</entry>
+ </row>
+ <row>
+ <entry><function>Mod5Mask</function></entry>
+ <entry>(1<<7)</entry>
+ </row>
+ <row>
+ <entry><function>Button1</function></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry><function>Button2</function></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry><function>Button3</function></entry>
+ <entry>3</entry>
+ </row>
+ <row>
+ <entry><function>Button4</function></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry><function>Button5</function></entry>
+ <entry>5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect2>
+</sect1>
+<sect1 id="Window_Entry_Exit_Events">
+<title>Window Entry/Exit Events</title>
+<!-- .XS -->
+<!-- (SN Window Entry/Exit Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm>
+This section describes the processing that
+occurs for the window crossing events
+<function>EnterNotify</function>
+and
+<function>LeaveNotify</function>.
+<indexterm significance="preferred"><primary>EnterNotify</primary></indexterm>
+<indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm>
+If a pointer motion or a window hierarchy change causes the
+pointer to be in a different window than before, the X server reports
+<function>EnterNotify</function>
+or
+<function>LeaveNotify</function>
+events to clients who have selected for these events.
+All
+<function>EnterNotify</function>
+and
+<function>LeaveNotify</function>
+events caused by a hierarchy change are
+generated after any hierarchy event
+(<function>UnmapNotify</function>,
+<function>MapNotify</function>,
+<function>ConfigureNotify</function>,
+<function>GravityNotify</function>,
+<function>CirculateNotify</function>)
+caused by that change;
+however, the X protocol does not constrain the ordering of
+<function>EnterNotify </function>
+and
+<function>LeaveNotify </function>
+events with respect to
+<function>FocusOut</function>,
+<function>VisibilityNotify</function>,
+and
+<function>Expose </function>
+events.
+</para>
+<para>
+<!-- .LP -->
+This contrasts with
+<function>MotionNotify</function>
+events, which are also generated when the pointer moves
+but only when the pointer motion begins and ends in a single window.
+An
+<function>EnterNotify</function>
+or
+<function>LeaveNotify</function>
+event also can be generated when some client application calls
+<function>XGrabPointer</function>
+and
+<function>XUngrabPointer</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>EnterNotify</function>
+or
+<function>LeaveNotify</function>
+events, set the
+<function>EnterWindowMask</function>
+or
+<function>LeaveWindowMask</function>
+bits of the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for these event types contains:
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* EnterNotify or LeaveNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
+ int detail;
+ /*
+ * NotifyAncestor, NotifyVirtual, NotifyInferior,
+ * NotifyNonlinear,NotifyNonlinearVirtual
+ */
+ Bool same_screen; /* same screen flag */
+ Bool focus; /* boolean focus */
+ unsigned int state; /* key or button mask */
+} XCrossingEvent;
+typedef XCrossingEvent XEnterWindowEvent;
+typedef XCrossingEvent XLeaveWindowEvent;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window on which the
+<function>EnterNotify</function>
+or
+<function>LeaveNotify</function>
+event was generated and is referred to as the event window.
+This is the window used by the X server to report the event,
+and is relative to the root
+window on which the event occurred.
+The root member is set to the root window of the screen
+on which the event occurred.
+</para>
+<para>
+<!-- .LP -->
+For a
+<function>LeaveNotify </function>
+event,
+if a child of the event window contains the initial position of the pointer,
+the subwindow component is set to that child.
+Otherwise, the X server sets the subwindow member to
+<function>None</function>.
+For an
+<function>EnterNotify </function>
+event, if a child of the event window contains the final pointer position,
+the subwindow component is set to that child or
+<function>None</function>.
+</para>
+<para>
+<!-- .LP -->
+The time member is set to the time when the event was generated
+and is expressed in milliseconds.
+The x and y members are set to the coordinates of the pointer position in
+the event window.
+This position is always the pointer's final position,
+not its initial position.
+If the event window is on the same
+screen as the root window, x and y are the pointer coordinates
+relative to the event window's origin.
+Otherwise, x and y are set to zero.
+The x_root and y_root members are set to the pointer's coordinates relative to the
+root window's origin at the time of the event.
+</para>
+<para>
+<!-- .LP -->
+The same_screen member is set to indicate whether the event window is on the same screen
+as the root window and can be either
+<function>True </function>
+or
+<function>False</function>.
+If
+<function>True</function>,
+the event and root windows are on the same screen.
+If
+<function>False</function>,
+the event and root windows are not on the same screen.
+</para>
+<para>
+<!-- .LP -->
+The focus member is set to indicate whether the event window is the focus window or an
+inferior of the focus window.
+The X server can set this member to either
+<function>True </function>
+or
+<function>False</function>.
+If
+<function>True</function>,
+the event window is the focus window or an inferior of the focus window.
+If
+<function>False</function>,
+the event window is not the focus window or an inferior of the focus window.
+</para>
+<para>
+<!-- .LP -->
+The state member is set to indicate the state of the pointer buttons and
+modifier keys just prior to the
+event.
+The X server can set this member to the bitwise inclusive OR of one
+or more of the button or modifier key masks:
+<function>Button1Mask</function>,
+<function>Button2Mask</function>,
+<function>Button3Mask</function>,
+<function>Button4Mask</function>,
+<function>Button5Mask</function>,
+<function>ShiftMask</function>,
+<function>LockMask</function>,
+<function>ControlMask</function>,
+<function>Mod1Mask</function>,
+<function>Mod2Mask</function>,
+<function>Mod3Mask</function>,
+<function>Mod4Mask</function>,
+<function>Mod5Mask</function>.
+</para>
+<para>
+<!-- .LP -->
+The mode member is set to indicate whether the events are normal events,
+pseudo-motion events
+when a grab activates, or pseudo-motion events when a grab deactivates.
+The X server can set this member to
+<function>NotifyNormal</function>,
+<function>NotifyGrab</function>,
+or
+<function>NotifyUngrab</function>.
+</para>
+<para>
+<!-- .LP -->
+The detail member is set to indicate the notify detail and can be
+<function>NotifyAncestor</function>,
+<function>NotifyVirtual</function>,
+<function>NotifyInferior</function>,
+<function>NotifyNonlinear</function>,
+or
+<function>NotifyNonlinearVirtual</function>.
+</para>
+<sect2 id="Normal_Entry_Exit_Events">
+<title>Normal Entry/Exit Events</title>
+<!-- .XS -->
+<!-- (SN Normal Entry/Exit Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<function>EnterNotify</function>
+and
+<function>LeaveNotify</function>
+events are generated when the pointer moves from
+one window to another window.
+Normal events are identified by
+<function>XEnterWindowEvent</function>
+or
+<function>XLeaveWindowEvent</function>
+structures whose mode member is set to
+<function>NotifyNormal</function>.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B and A is an inferior of B,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>LeaveNotify</function>
+event on window A, with the detail member of the
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyAncestor</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>LeaveNotify</function>
+event on each window between window A and window B, exclusive,
+with the detail member of each
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<function>EnterNotify</function>
+event on window B, with the detail member of the
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyInferior</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B and B is an inferior of A,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>LeaveNotify</function>
+event on window A,
+with the detail member of the
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyInferior</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<function>EnterNotify</function>
+event on each window between window A and window B, exclusive, with the
+detail member of each
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<function>EnterNotify</function>
+event on window B, with the detail member of the
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyAncestor</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B
+and window C is their least common ancestor,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>LeaveNotify</function>
+event on window A,
+with the detail member of the
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>LeaveNotify</function>
+event on each window between window A and window C, exclusive,
+with the detail member of each
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<function>EnterNotify</function>
+event on each window between window C and window B, exclusive,
+with the detail member of each
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<function>EnterNotify</function>
+event on window B, with the detail member of the
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B on different screens,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>LeaveNotify</function>
+event on window A,
+with the detail member of the
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<function>LeaveNotify</function>
+event on each window above window A up to and including its root,
+with the detail member of each
+<function>XLeaveWindowEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window B is not a root window,
+it generates an
+<function>EnterNotify</function>
+event on each window from window B's root down to but not including
+window B, with the detail member of each
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<function>EnterNotify</function>
+event on window B, with the detail member of the
+<function>XEnterWindowEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+<!-- .RE -->
+<!-- .\".SH 3 -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Grab_and_Ungrab_Entry_Exit_Events">
+<title>Grab and Ungrab Entry/Exit Events</title>
+<!-- .XS -->
+<!-- (SN Grab and Ungrab Entry/Exit Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Pseudo-motion mode
+<function>EnterNotify</function>
+and
+<function>LeaveNotify</function>
+events are generated when a pointer grab activates or deactivates.
+Events in which the pointer grab activates
+are identified by
+<function>XEnterWindowEvent</function>
+or
+<function>XLeaveWindowEvent</function>
+structures whose mode member is set to
+<function>NotifyGrab</function>.
+Events in which the pointer grab deactivates
+are identified by
+<function>XEnterWindowEvent</function>
+or
+<function>XLeaveWindowEvent</function>
+structures whose mode member is set to
+<function>NotifyUngrab</function>
+(see
+<function>XGrabPointer</function>).
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When a pointer grab activates after any initial warp into a confine_to
+window and before generating any actual
+<function>ButtonPress</function>
+event that activates the grab,
+G is the grab_window for the grab,
+and P is the window the pointer is in,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<function>EnterNotify</function>
+and
+<function>LeaveNotify</function>
+events (see section 10.6.1)
+with the mode members of the
+<function>XEnterWindowEvent</function>
+and
+<function>XLeaveWindowEvent</function>
+structures set to
+<function>NotifyGrab</function>.
+These events are generated
+as if the pointer were to suddenly warp from
+its current position in P to some position in G.
+However, the pointer does not warp, and the X server uses the pointer position
+as both the initial and final positions for the events.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a pointer grab deactivates after generating any actual
+<function>ButtonRelease</function>
+event that deactivates the grab,
+G is the grab_window for the grab,
+and P is the window the pointer is in,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<function>EnterNotify</function>
+and
+<function>LeaveNotify</function>
+events (see section 10.6.1)
+with the mode members of the
+<function>XEnterWindowEvent</function>
+and
+<function>XLeaveWindowEvent</function>
+structures set to
+<function>NotifyUngrab</function>.
+These events are generated as if the pointer were to suddenly warp from
+some position in G to its current position in P.
+However, the pointer does not warp, and the X server uses the
+current pointer position as both the
+initial and final positions for the events.
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+<sect1 id="Input_Focus_Events">
+<title>Input Focus Events</title>
+<!-- .XS -->
+<!-- (SN Input Focus Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm>
+This section describes the processing that occurs for the input focus events
+<function>FocusIn</function>
+and
+<function>FocusOut</function>.
+<indexterm significance="preferred"><primary>FocusIn</primary></indexterm>
+<indexterm significance="preferred"><primary>FocusOut</primary></indexterm>
+The X server can report
+<function>FocusIn</function>
+or
+<function>FocusOut</function>
+events to clients wanting information about when the input focus changes.
+The keyboard is always attached to some window
+(typically, the root window or a top-level window),
+which is called the focus window.
+The focus window and the position of the pointer determine the window that
+receives keyboard input.
+Clients may need to know when the input focus changes
+to control highlighting of areas on the screen.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>FocusIn</function>
+or
+<function>FocusOut</function>
+events, set the
+<function>FocusChangeMask</function>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for these event types contains:
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* FocusIn or FocusOut */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* window of event */
+ int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
+ int detail;
+ /*
+ * NotifyAncestor, NotifyVirtual, NotifyInferior,
+ * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
+ * NotifyPointerRoot, NotifyDetailNone
+ */
+} XFocusChangeEvent;
+typedef XFocusChangeEvent XFocusInEvent;
+typedef XFocusChangeEvent XFocusOutEvent;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window on which the
+<function>FocusIn</function>
+or
+<function>FocusOut</function>
+event was generated.
+This is the window used by the X server to report the event.
+The mode member is set to indicate whether the focus events
+are normal focus events,
+focus events while grabbed,
+focus events
+when a grab activates, or focus events when a grab deactivates.
+The X server can set the mode member to
+<function>NotifyNormal</function>,
+<function>NotifyWhileGrabbed</function>,
+<function>NotifyGrab</function>,
+or
+<function>NotifyUngrab</function>.
+</para>
+<para>
+<!-- .LP -->
+All
+<function>FocusOut</function>
+events caused by a window unmap are generated after any
+<function>UnmapNotify</function>
+event; however, the X protocol does not constrain the ordering of
+<function>FocusOut</function>
+events with respect to
+generated
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+<function>VisibilityNotify</function>,
+and
+<function>Expose</function>
+events.
+</para>
+<para>
+<!-- .LP -->
+Depending on the event mode,
+the detail member is set to indicate the notify detail and can be
+<function>NotifyAncestor</function>,
+<function>NotifyVirtual</function>,
+<function>NotifyInferior</function>,
+<function>NotifyNonlinear</function>,
+<function>NotifyNonlinearVirtual</function>,
+<function>NotifyPointer</function>,
+<function>NotifyPointerRoot</function>,
+or
+<function>NotifyDetailNone</function>.
+</para>
+<sect2 id="Normal_Focus_Events_and_Focus_Events_While_Grabbed_">
+<title>Normal Focus Events and Focus Events While Grabbed </title>
+<!-- .XS -->
+<!-- (SN Normal Focus Events and Focus Events While Grabbed -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Normal focus events are identified by
+<function>XFocusInEvent</function>
+or
+<function>XFocusOutEvent</function>
+structures whose mode member is set to
+<function>NotifyNormal</function>.
+Focus events while grabbed are identified by
+<function>XFocusInEvent</function>
+or
+<function>XFocusOutEvent</function>
+structures whose mode member is set to
+<function>NotifyWhileGrabbed</function>.
+The X server processes normal focus and focus events while grabbed according to
+the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When the focus moves from window A to window B, A is an inferior of B,
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on window A, with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyAncestor</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on each window between window A and window B, exclusive,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on window B, with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyInferior</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window B
+but window P is not window A or an inferior or ancestor of window A,
+it generates a
+<function>FocusIn</function>
+event on each window below window B, down to and including window P,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to window B, B is an inferior of A,
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A
+but P is not an inferior of window B or an ancestor of B,
+it generates a
+<function>FocusOut</function>
+event on each window from window P up to but not including window A,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on window A,
+with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyInferior</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on each window between window A and window B, exclusive, with the
+detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on window B, with the detail member of the
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyAncestor</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to window B,
+window C is their least common ancestor,
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A,
+it generates a
+<function>FocusOut</function>
+event on each window from window P up to but not including window A,
+with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on window A,
+with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on each window between window A and window C, exclusive,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on each window between C and B, exclusive,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on window B, with the detail member of the
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window B, it generates a
+<function>FocusIn</function>
+event on each window below window B down to and including window P,
+with the detail member of the
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to window B on different screens
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A, it generates a
+<function>FocusOut</function>
+event on each window from window P up to but not including window A,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on window A,
+with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<function>FocusOut</function>
+event on each window above window A up to and including its root,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window B is not a root window,
+it generates a
+<function>FocusIn</function>
+event on each window from window B's root down to but not including
+window B, with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on window B, with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window B, it generates a
+<function>FocusIn</function>
+event on each window below window B down to and including window P,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to
+<function>PointerRoot</function>
+(events sent to the window under the pointer)
+or
+<function>None </function>
+(discard), and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A, it generates a
+<function>FocusOut</function>
+event on each window from window P up to but not including window A,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on window A, with the detail member of the
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<function>FocusOut</function>
+event on each window above window A up to and including its root,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on the root window of all screens, with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointerRoot</function>
+(or
+<function>NotifyDetailNone</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the new focus is
+<function>PointerRoot</function>,
+it generates a
+<function>FocusIn</function>
+event on each window from window P's root down to and including window P,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from
+<function>PointerRoot</function>
+(events sent to the window under the pointer)
+or
+<function>None </function>
+to window A, and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the old focus is
+<function>PointerRoot</function>,
+it generates a
+<function>FocusOut</function>
+event on each window from window P up to and including window P's root,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on all root windows,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointerRoot</function>
+(or
+<function>NotifyDetailNone</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<function>FocusIn</function>
+event on each window from window A's root down to but not including window A,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyNonlinearVirtual</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on window A,
+with the detail member of the
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyNonlinear</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A, it generates a
+<function>FocusIn</function>
+event on each window below window A down to and including window P,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from
+<function>PointerRoot</function>
+(events sent to the window under the pointer)
+to
+<function>None</function>
+(or vice versa), and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the old focus is
+<function>PointerRoot</function>,
+it generates a
+<function>FocusOut</function>
+event on each window from window P up to and including window P's root,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusOut</function>
+event on all root windows,
+with the detail member of each
+<function>XFocusOutEvent</function>
+structure set to either
+<function>NotifyPointerRoot</function>
+or
+<function>NotifyDetailNone</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<function>FocusIn</function>
+event on all root windows,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyDetailNone </function>
+or
+<function>NotifyPointerRoot</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the new focus is
+<function>PointerRoot</function>,
+it generates a
+<function>FocusIn</function>
+event on each window from window P's root down to and including window P,
+with the detail member of each
+<function>XFocusInEvent</function>
+structure set to
+<function>NotifyPointer</function>.
+<!-- .RE -->
+<!-- .\".SH 3 -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Focus_Events_Generated_by_Grabs">
+<title>Focus Events Generated by Grabs</title>
+<!-- .XS -->
+<!-- (SN Focus Events Generated by Grabs -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Focus events in which the keyboard grab activates
+are identified by
+<function>XFocusInEvent</function>
+or
+<function>XFocusOutEvent</function>
+structures whose mode member is set to
+<function>NotifyGrab</function>.
+Focus events in which the keyboard grab deactivates
+are identified by
+<function>XFocusInEvent</function>
+or
+<function>XFocusOutEvent</function>
+structures whose mode member is set to
+<function>NotifyUngrab </function>
+(see
+<function>XGrabKeyboard</function>).
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When a keyboard grab activates before generating any actual
+<function>KeyPress</function>
+event that activates the grab,
+G is the grab_window, and F is the current focus,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events, with the mode members of the
+<function>XFocusInEvent</function>
+and
+<function>XFocusOutEvent</function>
+structures set to
+<function>NotifyGrab</function>.
+These events are generated
+as if the focus were to change from
+F to G.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a keyboard grab deactivates after generating any actual
+<function>KeyRelease</function>
+event that deactivates the grab,
+G is the grab_window, and F is the current focus,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events, with the mode members of the
+<function>XFocusInEvent</function>
+and
+<function>XFocusOutEvent</function>
+structures set to
+<function>NotifyUngrab</function>.
+These events are generated
+as if the focus were to change from
+G to F.
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+<sect1 id="Key_Map_State_Notification_Events">
+<title>Key Map State Notification Events</title>
+<!-- .XS -->
+<!-- (SN Key Map State Notification Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm>
+The X server can report
+<function>KeymapNotify</function>
+events to clients that want information about changes in their keyboard state.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>KeymapNotify</function>
+events, set the
+<function>KeymapStateMask</function>
+bit in the event-mask attribute of the window.
+The X server generates this event immediately after every
+<function>EnterNotify</function>
+and
+<function>FocusIn</function>
+event.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* generated on EnterWindow and FocusIn when KeymapState selected */
+typedef struct {
+ int type; /* KeymapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ char key_vector[32];
+} XKeymapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is not used but is present to aid some toolkits.
+The key_vector member is set to the bit vector of the keyboard.
+Each bit set to 1 indicates that the corresponding key
+is currently pressed.
+The vector is represented as 32 bytes.
+Byte N (from 0) contains the bits for keys 8N to 8N + 7
+with the least significant bit in the byte representing key 8N.
+</para>
+</sect1>
+<sect1 id="Exposure_Events">
+<title>Exposure Events</title>
+<!-- .XS -->
+<!-- (SN Exposure Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The X protocol does not guarantee to preserve the contents of window
+regions when
+the windows are obscured or reconfigured.
+Some implementations may preserve the contents of windows.
+Other implementations are free to destroy the contents of windows
+when exposed.
+X expects client applications to assume the responsibility for
+restoring the contents of an exposed window region.
+(An exposed window region describes a formerly obscured window whose
+region becomes visible.)
+Therefore, the X server sends
+<function>Expose </function>
+events describing the window and the region of the window that has been exposed.
+A naive client application usually redraws the entire window.
+A more sophisticated client application redraws only the exposed region.
+</para>
+<sect2 id="Expose_Events">
+<title>Expose Events</title>
+<!-- .XS -->
+<!-- (SN Expose Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm>
+<indexterm significance="preferred"><primary>Expose</primary></indexterm>
+The X server can report
+<function>Expose</function>
+events to clients wanting information about when the contents of window regions
+have been lost.
+The circumstances in which the X server generates
+<function>Expose</function>
+events are not as definite as those for other events.
+However, the X server never generates
+<function>Expose</function>
+events on windows whose class you specified as
+<function>InputOnly</function>.
+The X server can generate
+<function>Expose</function>
+events when no valid contents are available for regions of a window
+and either the regions are visible,
+the regions are viewable and the server is (perhaps newly) maintaining
+backing store on the window,
+or the window is not viewable but the server is (perhaps newly) honoring the
+window's backing-store attribute of
+<function>Always</function>
+or
+<function>WhenMapped</function>.
+The regions decompose into an (arbitrary) set of rectangles,
+and an
+<function>Expose</function>
+event is generated for each rectangle.
+For any given window,
+the X server guarantees to report contiguously
+all of the regions exposed by some action that causes
+<function>Expose </function>
+events, such as raising a window.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>Expose</function>
+events, set the
+<function>ExposureMask</function>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* Expose */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ int x, y;
+ int width, height;
+ int count; /* if nonzero, at least this many more */
+} XExposeEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the exposed (damaged) window.
+The x and y members are set to the coordinates relative to the window's origin
+and indicate the upper-left corner of the rectangle.
+The width and height members are set to the size (extent) of the rectangle.
+The count member is set to the number of
+<function>Expose</function>
+events that are to follow.
+If count is zero, no more
+<function>Expose</function>
+events follow for this window.
+However, if count is nonzero, at least that number of
+<function>Expose </function>
+events (and possibly more) follow for this window.
+Simple applications that do not want to optimize redisplay by distinguishing
+between subareas of its window can just ignore all
+<function>Expose</function>
+events with nonzero counts and perform full redisplays
+on events with zero counts.
+</para>
+</sect2>
+<sect2 id="GraphicsExpose_and_NoExpose_Events">
+<title>GraphicsExpose and NoExpose Events</title>
+<!-- .XS -->
+<!-- (SN GraphicsExpose and NoExpose Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm>
+<indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm>
+The X server can report
+<function>GraphicsExpose</function>
+events to clients wanting information about when a destination region could not
+be computed during certain graphics requests:
+<function>XCopyArea</function>
+or
+<function>XCopyPlane</function>.
+The X server generates this event whenever a destination region could not be
+computed because of an obscured or out-of-bounds source region.
+In addition, the X server guarantees to report contiguously all of the regions exposed by
+some graphics request
+(for example, copying an area of a drawable to a destination
+drawable).
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>NoExpose</primary></indexterm>
+The X server generates a
+<function>NoExpose</function>
+event whenever a graphics request that might
+produce a
+<function>GraphicsExpose</function>
+event does not produce any.
+In other words, the client is really asking for a
+<function>GraphicsExpose</function>
+event but instead receives a
+<function>NoExpose</function>
+event.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>GraphicsExpose</function>
+or
+<function>NoExpose</function>
+events, you must first set the graphics-exposure
+attribute of the graphics context to
+<function>True</function>.
+You also can set the graphics-expose attribute when creating a graphics
+context using
+<function>XCreateGC </function>
+or by calling
+<function>XSetGraphicsExposures</function>.
+</para>
+<para>
+<!-- .LP -->
+The structures for these event types contain:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* GraphicsExpose */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Drawable drawable;
+ int x, y;
+ int width, height;
+ int count; /* if nonzero, at least this many more */
+ int major_code; /* core is CopyArea or CopyPlane */
+ int minor_code; /* not defined in the core */
+} XGraphicsExposeEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* NoExpose */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Drawable drawable;
+ int major_code; /* core is CopyArea or CopyPlane */
+ int minor_code; /* not defined in the core */
+} XNoExposeEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both structures have these common members: drawable, major_code, and minor_code.
+The drawable member is set to the drawable of the destination region on
+which the graphics request was to be performed.
+The major_code member is set to the graphics request initiated by the client
+and can be either
+<function>X_CopyArea</function>
+or
+<function>X_CopyPlane</function>.
+If it is
+<function>X_CopyArea</function>,
+a call to
+<function>XCopyArea</function>
+initiated the request.
+If it is
+<function>X_CopyPlane</function>,
+a call to
+<function>XCopyPlane</function>
+initiated the request.
+These constants are defined in
+<!-- .hN X11/Xproto.h . -->
+The minor_code member,
+like the major_code member,
+indicates which graphics request was initiated by
+the client.
+However, the minor_code member is not defined by the core
+X protocol and will be zero in these cases,
+although it may be used by an extension.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XGraphicsExposeEvent</function>
+structure has these additional members: x, y, width, height, and count.
+The x and y members are set to the coordinates relative to the drawable's origin
+and indicate the upper-left corner of the rectangle.
+The width and height members are set to the size (extent) of the rectangle.
+The count member is set to the number of
+<function>GraphicsExpose</function>
+events to follow.
+If count is zero, no more
+<function>GraphicsExpose</function>
+events follow for this window.
+However, if count is nonzero, at least that number of
+<function>GraphicsExpose</function>
+events (and possibly more) are to follow for this window.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Window_State_Change_Events_">
+<title>Window State Change Events </title>
+<!-- .XS -->
+<!-- (SN Window State Change Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following sections discuss:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>CirculateNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>ConfigureNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>CreateNotify </function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>DestroyNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>GravityNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>MapNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>MappingNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>ReparentNotify </function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>UnmapNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>VisibilityNotify</function>
+events
+<!-- .\" .SH 3 -->
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="CirculateNotify_Events">
+<title>CirculateNotify Events</title>
+<!-- .XS -->
+<!-- (SN CirculateNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm>
+The X server can report
+<function>CirculateNotify</function>
+events to clients wanting information about when a window changes
+its position in the stack.
+The X server generates this event type whenever a window is actually restacked
+as a result of a client application calling
+<function>XCirculateSubwindows</function>,
+<function>XCirculateSubwindowsUp</function>,
+or
+<function>XCirculateSubwindowsDown</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>CirculateNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window
+or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the parent window
+(in which case, circulating any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* CirculateNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ int place; /* PlaceOnTop, PlaceOnBottom */
+} XCirculateEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the restacked window or to its parent,
+depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+The window member is set to the window that was restacked.
+The place member is set to the window's position after the restack occurs and
+is either
+<function>PlaceOnTop</function>
+or
+<function>PlaceOnBottom</function>.
+If it is
+<function>PlaceOnTop</function>,
+the window is now on top of all siblings.
+If it is
+<function>PlaceOnBottom</function>,
+the window is now below all siblings.
+</para>
+</sect2>
+<sect2 id="ConfigureNotify_Events">
+<title>ConfigureNotify Events</title>
+<!-- .XS -->
+<!-- (SN ConfigureNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm>
+The X server can report
+<function>ConfigureNotify</function>
+events to clients wanting information about actual changes to a window's
+state, such as size, position, border, and stacking order.
+The X server generates this event type whenever one of the following configure
+window requests made by a client application actually completes:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A window's size, position, border, and/or stacking order is reconfigured
+by calling
+<function>XConfigureWindow</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The window's position in the stacking order is changed by calling
+<function>XLowerWindow</function>,
+<function>XRaiseWindow</function>,
+or
+<function>XRestackWindows</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window is moved by calling
+<function>XMoveWindow</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window's size is changed by calling
+<function>XResizeWindow</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window's size and location is changed by calling
+<function>XMoveResizeWindow</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window is mapped and its position in the stacking order is changed
+by calling
+<function>XMapRaised</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window's border width is changed by calling
+<function>XSetWindowBorderWidth</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To receive
+<function>ConfigureNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the parent window
+(in which case, configuring any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ConfigureNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ int x, y;
+ int width, height;
+ int border_width;
+ Window above;
+ Bool override_redirect;
+} XConfigureEvent;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the reconfigured window or to its parent,
+depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+The window member is set to the window whose size, position,
+border, and/or stacking
+order was changed.
+</para>
+<para>
+<!-- .LP -->
+The x and y members are set to the coordinates relative to the parent window's
+origin and indicate the position of the upper-left outside corner of the window.
+The width and height members are set to the inside size of the window,
+not including
+the border.
+The border_width member is set to the width of the window's border, in pixels.
+</para>
+<para>
+<!-- .LP -->
+The above member is set to the sibling window and is used
+for stacking operations.
+If the X server sets this member to
+<function>None</function>,
+the window whose state was changed is on the bottom of the stack
+with respect to sibling windows.
+However, if this member is set to a sibling window,
+the window whose state was changed is placed on top of this sibling window.
+</para>
+<para>
+<!-- .LP -->
+The override_redirect member is set to the override-redirect attribute of the
+window.
+Window manager clients normally should ignore this window if the
+override_redirect member
+is
+<function>True</function>.
+</para>
+</sect2>
+<sect2 id="CreateNotify_Events">
+<title>CreateNotify Events</title>
+<!-- .XS -->
+<!-- (SN CreateNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>CreateNotify</primary></indexterm>
+The X server can report
+<function>CreateNotify</function>
+events to clients wanting information about creation of windows.
+The X server generates this event whenever a client
+application creates a window by calling
+<function>XCreateWindow</function>
+or
+<function>XCreateSimpleWindow</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>CreateNotify</function>
+events, set the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the window.
+Creating any children then generates an event.
+</para>
+<para>
+<!-- .LP -->
+The structure for the event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* CreateNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent; /* parent of the window */
+ Window window; /* window id of window created */
+ int x, y; /* window location */
+ int width, height; /* size of window */
+ int border_width; /* border width */
+ Bool override_redirect; /* creation should be overridden */
+} XCreateWindowEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the created window's parent.
+The window member specifies the created window.
+The x and y members are set to the created window's coordinates relative
+to the parent window's origin and indicate the position of the upper-left
+outside corner of the created window.
+The width and height members are set to the inside size of the created window
+(not including the border) and are always nonzero.
+The border_width member is set to the width of the created window's border, in pixels.
+The override_redirect member is set to the override-redirect attribute of the
+window.
+Window manager clients normally should ignore this window
+if the override_redirect member is
+<function>True</function>.
+</para>
+</sect2>
+<sect2 id="DestroyNotify_Events">
+<title>DestroyNotify Events</title>
+<!-- .XS -->
+<!-- (SN DestroyNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm>
+The X server can report
+<function>DestroyNotify</function>
+events to clients wanting information about which windows are destroyed.
+The X server generates this event whenever a client application destroys a
+window by calling
+<function>XDestroyWindow</function>
+or
+<function>XDestroySubwindows</function>.
+</para>
+<para>
+<!-- .LP -->
+The ordering of the
+<function>DestroyNotify </function>
+events is such that for any given window,
+<function>DestroyNotify</function>
+is generated on all inferiors of the window
+before being generated on the window itself.
+The X protocol does not constrain the ordering among
+siblings and across subhierarchies.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>DestroyNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the parent window
+(in which case, destroying any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* DestroyNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+} XDestroyWindowEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the destroyed window or to its parent,
+depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+The window member is set to the window that is destroyed.
+</para>
+</sect2>
+<sect2 id="GravityNotify_Events">
+<title>GravityNotify Events</title>
+<!-- .XS -->
+<!-- (SN GravityNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>GravityNotify</primary></indexterm>
+The X server can report
+<function>GravityNotify</function>
+events to clients wanting information about when a window is moved because of a
+change in the size of its parent.
+The X server generates this event whenever a client
+application actually moves a child window as a result of resizing its parent by calling
+<function>XConfigureWindow</function>,
+<function>XMoveResizeWindow</function>,
+or
+<function>XResizeWindow</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>GravityNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the parent window
+(in which case, any child that is moved because its parent has been resized
+generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* GravityNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ int x, y;
+} XGravityEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the window that was moved or to its parent,
+depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+The window member is set to the child window that was moved.
+The x and y members are set to the coordinates relative to the
+new parent window's origin
+and indicate the position of the upper-left outside corner of the
+window.
+</para>
+</sect2>
+<sect2 id="MapNotify_Events">
+<title>MapNotify Events</title>
+<!-- .XS -->
+<!-- (SN MapNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>MapNotify</primary></indexterm>
+The X server can report
+<function>MapNotify</function>
+events to clients wanting information about which windows are mapped.
+The X server generates this event type whenever a client application changes the
+window's state from unmapped to mapped by calling
+<function>XMapWindow</function>,
+<function>XMapRaised</function>,
+<function>XMapSubwindows</function>,
+<function>XReparentWindow</function>,
+or as a result of save-set processing.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>MapNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the parent window
+(in which case, mapping any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XMapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* MapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ Bool override_redirect; /* boolean, is override set... */
+} XMapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the window that was mapped or to its parent,
+depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+The window member is set to the window that was mapped.
+The override_redirect member is set to the override-redirect attribute
+of the window.
+Window manager clients normally should ignore this window
+if the override-redirect attribute is
+<function>True</function>,
+because these events usually are generated from pop-ups,
+which override structure control.
+</para>
+</sect2>
+<sect2 id="MappingNotify_Events">
+<title>MappingNotify Events</title>
+<!-- .XS -->
+<!-- (SN MappingNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>MappingNotify</primary></indexterm>
+The X server reports
+<function>MappingNotify</function>
+events to all clients.
+There is no mechanism to express disinterest in this event.
+The X server generates this event type whenever a client application
+successfully calls:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XSetModifierMapping</function>
+to indicate which KeyCodes are to be used as modifiers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XChangeKeyboardMapping</function>
+to change the keyboard mapping
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XSetPointerMapping</function>
+to set the pointer mapping
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* MappingNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* unused */
+ int request; /* one of MappingModifier, MappingKeyboard,
+ MappingPointer */
+ int first_keycode; /* first keycode */
+ int count; /* defines range of change w. first_keycode*/
+} XMappingEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The request member is set to indicate the kind of mapping change that occurred
+and can be
+<function>MappingModifier</function>,
+<function>MappingKeyboard</function>,
+or
+<function>MappingPointer</function>.
+If it is
+<function>MappingModifier</function>,
+the modifier mapping was changed.
+If it is
+<function>MappingKeyboard</function>,
+the keyboard mapping was changed.
+If it is
+<function>MappingPointer</function>,
+the pointer button mapping was changed.
+The first_keycode and count members are set only
+if the request member was set to
+<function>MappingKeyboard</function>.
+The number in first_keycode represents the first number in the range
+of the altered mapping,
+and count represents the number of keycodes altered.
+</para>
+<para>
+<!-- .LP -->
+To update the client application's knowledge of the keyboard,
+you should call
+<function>XRefreshKeyboardMapping</function>.
+</para>
+</sect2>
+<sect2 id="ReparentNotify_Events">
+<title>ReparentNotify Events</title>
+<!-- .XS -->
+<!-- (SN ReparentNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm>
+The X server can report
+<function>ReparentNotify</function>
+events to clients wanting information about changing a window's parent.
+The X server generates this event whenever a client
+application calls
+<function>XReparentWindow </function>
+and the window is actually reparented.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>ReparentNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of either the old or the new parent window
+(in which case, reparenting any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ReparentNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ Window parent;
+ int x, y;
+ Bool override_redirect;
+} XReparentEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the reparented window
+or to the old or the new parent, depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+The window member is set to the window that was reparented.
+The parent member is set to the new parent window.
+The x and y members are set to the reparented window's coordinates relative
+to the new parent window's
+origin and define the upper-left outer corner of the reparented window.
+The override_redirect member is set to the override-redirect attribute of the
+window specified by the window member.
+Window manager clients normally should ignore this window
+if the override_redirect member is
+<function>True</function>.
+</para>
+</sect2>
+<sect2 id="UnmapNotify_Events">
+<title>UnmapNotify Events</title>
+<!-- .XS -->
+<!-- (SN UnmapNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm>
+The X server can report
+<function>UnmapNotify</function>
+events to clients wanting information about which windows are unmapped.
+The X server generates this event type whenever a client application changes the
+window's state from mapped to unmapped.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>UnmapNotify</function>
+events, set the
+<function>StructureNotifyMask</function>
+bit in the event-mask attribute of the window or the
+<function>SubstructureNotifyMask</function>
+bit in the event-mask attribute of the parent window
+(in which case, unmapping any child window generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* UnmapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ Bool from_configure;
+} XUnmapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the unmapped window or to its parent,
+depending on whether
+<function>StructureNotify</function>
+or
+<function>SubstructureNotify</function>
+was selected.
+This is the window used by the X server to report the event.
+The window member is set to the window that was unmapped.
+The from_configure member is set to
+<function>True </function>
+if the event was generated as a result of a resizing of the window's parent when
+the window itself had a win_gravity of
+<function>UnmapGravity</function>.
+</para>
+</sect2>
+<sect2 id="VisibilityNotify_Events">
+<title>VisibilityNotify Events</title>
+<!-- .XS -->
+<!-- (SN VisibilityNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm>
+The X server can report
+<function>VisibilityNotify</function>
+events to clients wanting any change in the visibility of the specified window.
+A region of a window is visible if someone looking at the screen can
+actually see it.
+The X server generates this event whenever the visibility changes state.
+However, this event is never generated for windows whose class is
+<function>InputOnly</function>.
+</para>
+<para>
+<!-- .LP -->
+All
+<function>VisibilityNotify</function>
+events caused by a hierarchy change are generated
+after any hierarchy event
+(<function>UnmapNotify</function>,
+<function>MapNotify</function>,
+<function>ConfigureNotify</function>,
+<function>GravityNotify</function>,
+<function>CirculateNotify</function>)
+caused by that change. Any
+<function>VisibilityNotify</function>
+event on a given window is generated before any
+<function>Expose </function>
+events on that window, but it is not required that all
+<function>VisibilityNotify</function>
+events on all windows be generated before all
+<function>Expose</function>
+events on all windows.
+The X protocol does not constrain the ordering of
+<function>VisibilityNotify</function>
+events with
+respect to
+<function>FocusOut</function>,
+<function>EnterNotify</function>,
+and
+<function>LeaveNotify</function>
+events.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>VisibilityNotify</function>
+events, set the
+<function>VisibilityChangeMask</function>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* VisibilityNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ int state;
+} XVisibilityEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose visibility state changes.
+The state member is set to the state of the window's visibility and can be
+<function>VisibilityUnobscured</function>,
+<function>VisibilityPartiallyObscured</function>,
+or
+<function>VisibilityFullyObscured</function>.
+The X server ignores all of a window's subwindows
+when determining the visibility state of the window and processes
+<function>VisibilityNotify</function>
+events according to the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When the window changes state from partially obscured, fully obscured,
+or not viewable to viewable and completely unobscured,
+the X server generates the event with the state member of the
+<function>XVisibilityEvent</function>
+structure set to
+<function>VisibilityUnobscured</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the window changes state from viewable and completely unobscured or
+not viewable to viewable and partially obscured,
+the X server generates the event with the state member of the
+<function>XVisibilityEvent</function>
+structure set to
+<function>VisibilityPartiallyObscured</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the window changes state from viewable and completely unobscured,
+viewable and partially obscured, or not viewable to viewable and
+fully obscured,
+the X server generates the event with the state member of the
+<function>XVisibilityEvent</function>
+structure set to
+<function>VisibilityFullyObscured</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+<sect1 id="Structure_Control_Events">
+<title>Structure Control Events</title>
+<!-- .XS -->
+<!-- (SN Structure Control Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>CirculateRequest</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>ConfigureRequest</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>MapRequest </function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>ResizeRequest </function>
+events
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="CirculateRequest_Events">
+<title>CirculateRequest Events</title>
+<!-- .XS -->
+<!-- (SN CirculateRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm>
+The X server can report
+<function>CirculateRequest</function>
+events to clients wanting information about
+when another client initiates a circulate window request
+on a specified window.
+The X server generates this event type whenever a client initiates a circulate
+window request on a window and a subwindow actually needs to be restacked.
+The client initiates a circulate window request on the window by calling
+<function>XCirculateSubwindows</function>,
+<function>XCirculateSubwindowsUp</function>,
+or
+<function>XCirculateSubwindowsDown</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>CirculateRequest</function>
+events, set the
+<function>SubstructureRedirectMask</function>
+in the event-mask attribute of the window.
+Then, in the future,
+the circulate window request for the specified window is not executed,
+and thus, any subwindow's position in the stack is not changed.
+For example, suppose a client application calls
+<function>XCirculateSubwindowsUp</function>
+to raise a subwindow to the top of the stack.
+If you had selected
+<function>SubstructureRedirectMask</function>
+on the window, the X server reports to you a
+<function>CirculateRequest</function>
+event and does not raise the subwindow to the top of the stack.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* CirculateRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent;
+ Window window;
+ int place; /* PlaceOnTop, PlaceOnBottom */
+} XCirculateRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the parent window.
+The window member is set to the subwindow to be restacked.
+The place member is set to what the new position in the stacking order should be
+and is either
+<function>PlaceOnTop</function>
+or
+<function>PlaceOnBottom</function>.
+If it is
+<function>PlaceOnTop</function>,
+the subwindow should be on top of all siblings.
+If it is
+<function>PlaceOnBottom</function>,
+the subwindow should be below all siblings.
+</para>
+</sect2>
+<sect2 id="ConfigureRequest_Events">
+<title>ConfigureRequest Events</title>
+<!-- .XS -->
+<!-- (SN ConfigureRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm>
+The X server can report
+<function>ConfigureRequest</function>
+events to clients wanting information about when a different client initiates
+a configure window request on any child of a specified window.
+The configure window request attempts to
+reconfigure a window's size, position, border, and stacking order.
+The X server generates this event whenever a different client initiates
+a configure window request on a window by calling
+<function>XConfigureWindow</function>,
+<function>XLowerWindow</function>,
+<function>XRaiseWindow</function>,
+<function>XMapRaised</function>,
+<function>XMoveResizeWindow</function>,
+<function>XMoveWindow</function>,
+<function>XResizeWindow</function>,
+<function>XRestackWindows</function>,
+or
+<function>XSetWindowBorderWidth</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>ConfigureRequest</function>
+events, set the
+<function>SubstructureRedirectMask</function>
+bit in the event-mask attribute of the window.
+<function>ConfigureRequest</function>
+events are generated when a
+<function>ConfigureWindow</function>
+protocol request is issued on a child window by another client.
+For example, suppose a client application calls
+<function>XLowerWindow</function>
+to lower a window.
+If you had selected
+<function>SubstructureRedirectMask </function>
+on the parent window and if the override-redirect attribute
+of the window is set to
+<function>False</function>,
+the X server reports a
+<function>ConfigureRequest</function>
+event to you and does not lower the specified window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ConfigureRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent;
+ Window window;
+ int x, y;
+ int width, height;
+ int border_width;
+ Window above;
+ int detail; /* Above, Below, TopIf, BottomIf, Opposite */
+ unsigned long value_mask;
+} XConfigureRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the parent window.
+The window member is set to the window whose size, position, border width,
+and/or stacking order is to be reconfigured.
+The value_mask member indicates which components were specified in the
+<function>ConfigureWindow </function>
+protocol request.
+The corresponding values are reported as given in the request.
+The remaining values are filled in from the current geometry of the window,
+except in the case of above (sibling) and detail (stack-mode),
+which are reported as
+<function>None</function>
+and
+<function>Above</function>,
+respectively, if they are not given in the request.
+</para>
+</sect2>
+<sect2 id="MapRequest_Events">
+<title>MapRequest Events</title>
+<!-- .XS -->
+<!-- (SN MapRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>MapRequest</primary></indexterm>
+The X server can report
+<function>MapRequest</function>
+events to clients wanting information about a different client's desire
+to map windows.
+A window is considered mapped when a map window request completes.
+The X server generates this event whenever a different client initiates
+a map window request on an unmapped window whose override_redirect member
+is set to
+<function>False</function>.
+Clients initiate map window requests by calling
+<function>XMapWindow</function>,
+<function>XMapRaised</function>,
+or
+<function>XMapSubwindows</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>MapRequest</function>
+events, set the
+<function>SubstructureRedirectMask</function>
+bit in the event-mask attribute of the window.
+This means another client's attempts to map a child window by calling one of
+the map window request functions is intercepted, and you are sent a
+<function>MapRequest</function>
+instead.
+For example, suppose a client application calls
+<function>XMapWindow</function>
+to map a window.
+If you (usually a window manager) had selected
+<function>SubstructureRedirectMask </function>
+on the parent window and if the override-redirect attribute
+of the window is set to
+<function>False</function>,
+the X server reports a
+<function>MapRequest</function>
+event to you
+and does not map the specified window.
+Thus, this event gives your window manager client the ability
+to control the placement of subwindows.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* MapRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent;
+ Window window;
+} XMapRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the parent window.
+The window member is set to the window to be mapped.
+</para>
+</sect2>
+<sect2 id="ResizeRequest_Events">
+<title>ResizeRequest Events</title>
+<!-- .XS -->
+<!-- (SN ResizeRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm>
+The X server can report
+<function>ResizeRequest</function>
+events to clients wanting information about another client's attempts to change the
+size of a window.
+The X server generates this event whenever some other client attempts to change
+the size of the specified window by calling
+<function>XConfigureWindow</function>,
+<function>XResizeWindow</function>,
+or
+<function>XMoveResizeWindow</function>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>ResizeRequest</function>
+events, set the
+<function>ResizeRedirect</function>
+bit in the event-mask attribute of the window.
+Any attempts to change the size by other clients are then redirected.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ResizeRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ int width, height;
+} XResizeRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose size another
+client attempted to change.
+The width and height members are set to the inside size of the window,
+excluding the border.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Colormap_State_Change_Events">
+<title>Colormap State Change Events</title>
+<!-- .XS -->
+<!-- (SN Colormap State Change Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm>
+The X server can report
+<function>ColormapNotify</function>
+events to clients wanting information about when the colormap changes
+and when a colormap is installed or uninstalled.
+The X server generates this event type whenever a client application:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Changes the colormap member of the
+<function>XSetWindowAttributes</function>
+structure by
+calling
+<function>XChangeWindowAttributes</function>,
+<function>XFreeColormap</function>,
+or
+<function>XSetWindowColormap </function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Installs or uninstalls the colormap by calling
+<function>XInstallColormap</function>
+or
+<function>XUninstallColormap </function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To receive
+<function>ColormapNotify </function>
+events, set the
+<function>ColormapChangeMask</function>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ColormapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Colormap colormap; /* colormap or None */
+ Bool new;
+ int state; /* ColormapInstalled, ColormapUninstalled */
+} XColormapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose associated
+colormap is changed, installed, or uninstalled.
+For a colormap that is changed, installed, or uninstalled,
+the colormap member is set to the colormap associated with the window.
+For a colormap that is changed by a call to
+<function>XFreeColormap</function>,
+the colormap member is set to
+<function>None</function>.
+The new member is set to indicate whether the colormap
+for the specified window was changed or installed or uninstalled
+and can be
+<function>True</function>
+or
+<function>False</function>.
+If it is
+<function>True</function>,
+the colormap was changed.
+If it is
+<function>False</function>,
+the colormap was installed or uninstalled.
+The state member is always set to indicate whether the colormap is installed or
+uninstalled and can be
+<function>ColormapInstalled</function>
+or
+<function>ColormapUninstalled</function>.
+</para>
+</sect1>
+<sect1 id="Client_Communication_Events">
+<title>Client Communication Events</title>
+<!-- .XS -->
+<!-- (SN Client Communication Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>ClientMessage </function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>PropertyNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>SelectionClear</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>SelectionNotify</function>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>SelectionRequest</function>
+events
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="ClientMessage_Events">
+<title>ClientMessage Events</title>
+<!-- .XS -->
+<!-- (SN ClientMessage Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm>
+<indexterm significance="preferred"><primary>ClientMessage</primary></indexterm>
+The X server generates
+<function>ClientMessage</function>
+events only when a client calls the function
+<function>XSendEvent</function>.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef struct {
+ int type; /* ClientMessage */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Atom message_type;
+ int format;
+ union {
+ char b[20];
+ short s[10];
+ long l[5];
+ } data;
+} XClientMessageEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The message_type member is set to an atom that indicates how the data
+should be interpreted by the receiving client.
+The format member is set to 8, 16, or 32 and specifies whether the data
+should be viewed as a list of bytes, shorts, or longs.
+The data member is a union that contains the members b, s, and l.
+The b, s, and l members represent data of twenty 8-bit values,
+ten 16-bit values, and five 32-bit values.
+Particular message types might not make use of all these values.
+The X server places no interpretation on the values in the window,
+message_type, or data members.
+</para>
+</sect2>
+<sect2 id="PropertyNotify_Events">
+<title>PropertyNotify Events</title>
+<!-- .XS -->
+<!-- (SN PropertyNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm>
+The X server can report
+<function>PropertyNotify</function>
+events to clients wanting information about property changes
+for a specified window.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<function>PropertyNotify</function>
+events, set the
+<function>PropertyChangeMask</function>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* PropertyNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Atom atom;
+ Time time;
+ int state; /* PropertyNewValue or PropertyDelete */
+} XPropertyEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose associated
+property was changed.
+The atom member is set to the property's atom and indicates which
+property was changed or desired.
+The time member is set to the server time when the property was changed.
+The state member is set to indicate whether the property was changed
+to a new value or deleted and can be
+<function>PropertyNewValue</function>
+or
+<function>PropertyDelete</function>.
+The state member is set to
+<function>PropertyNewValue</function>
+when a property of the window is changed using
+<function>XChangeProperty</function>
+or
+<function>XRotateWindowProperties</function>
+(even when adding zero-length data using
+<function>XChangeProperty</function>)
+and when replacing all or part of a property with identical data using
+<function>XChangeProperty</function>
+or
+<function>XRotateWindowProperties</function>.
+The state member is set to
+<function>PropertyDelete</function>
+when a property of the window is deleted using
+<function>XDeleteProperty</function>
+or, if the delete argument is
+<function>True</function>,
+<function>XGetWindowProperty</function>.
+</para>
+</sect2>
+<sect2 id="SelectionClear_Events">
+<title>SelectionClear Events</title>
+<!-- .XS -->
+<!-- (SN SelectionClear Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm>
+<indexterm significance="preferred"><primary>SelectionClear</primary></indexterm>
+The X server reports
+<function>SelectionClear</function>
+events to the client losing ownership of a selection.
+The X server generates this event type when another client
+asserts ownership of the selection by calling
+<function>XSetSelectionOwner</function>.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* SelectionClear */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Atom selection;
+ Time time;
+} XSelectionClearEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The selection member is set to the selection atom.
+The time member is set to the last change time recorded for the
+selection.
+The window member is the window that was specified by the current owner
+(the owner losing the selection) in its
+<function>XSetSelectionOwner</function>
+call.
+</para>
+</sect2>
+<sect2 id="SelectionRequest_Events">
+<title>SelectionRequest Events</title>
+<!-- .XS -->
+<!-- (SN SelectionRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm>
+The X server reports
+<function>SelectionRequest</function>
+events to the owner of a selection.
+The X server generates this event whenever a client
+requests a selection conversion by calling
+<function>XConvertSelection </function>
+for the owned selection.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* SelectionRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window owner;
+ Window requestor;
+ Atom selection;
+ Atom target;
+ Atom property;
+ Time time;
+} XSelectionRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The owner member is set to the window
+that was specified by the current owner in its
+<function>XSetSelectionOwner</function>
+call.
+The requestor member is set to the window requesting the selection.
+The selection member is set to the atom that names the selection.
+For example, PRIMARY is used to indicate the primary selection.
+The target member is set to the atom that indicates the type
+the selection is desired in.
+The property member can be a property name or
+<function>None</function>.
+The time member is set to the timestamp or
+<function>CurrentTime </function>
+value from the
+<function>ConvertSelection</function>
+request.
+</para>
+<para>
+<!-- .LP -->
+The owner should convert the selection based on the specified target type
+and send a
+<function>SelectionNotify</function>
+event back to the requestor.
+A complete specification for using selections is given in the X Consortium
+standard <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+</para>
+</sect2>
+<sect2 id="SelectionNotify_Events">
+<title>SelectionNotify Events</title>
+<!-- .XS -->
+<!-- (SN SelectionNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm>
+This event is generated by the X server in response to a
+<function>ConvertSelection </function>
+protocol request when there is no owner for the selection.
+When there is an owner, it should be generated by the owner
+of the selection by using
+<function>XSendEvent</function>.
+The owner of a selection should send this event to a requestor when a selection
+has been converted and stored as a property
+or when a selection conversion could
+not be performed (which is indicated by setting the property member to
+<function>None</function>).
+</para>
+<para>
+<!-- .LP -->
+If
+<function>None</function>
+is specified as the property in the
+<function>ConvertSelection</function>
+protocol request, the owner should choose a property name,
+store the result as that property on the requestor window,
+and then send a
+<function>SelectionNotify</function>
+giving that actual property name.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* SelectionNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window requestor;
+ Atom selection;
+ Atom target;
+ Atom property; /* atom or None */
+ Time time;
+} XSelectionEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The requestor member is set to the window associated with
+the requestor of the selection.
+The selection member is set to the atom that indicates the selection.
+For example, PRIMARY is used for the primary selection.
+The target member is set to the atom that indicates the converted type.
+For example, PIXMAP is used for a pixmap.
+The property member is set to the atom that indicates which
+property the result was stored on.
+If the conversion failed,
+the property member is set to
+<function>None</function>.
+The time member is set to the time the conversion took place and
+can be a timestamp or
+<function>CurrentTime</function>.
+<!-- .bp -->
+
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH11 b/libX11/specs/libX11/CH11 deleted file mode 100644 index 09d845d35..000000000 --- a/libX11/specs/libX11/CH11 +++ /dev/null @@ -1,1664 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 11\fP\s-1 - -\s+1\fBEvent Handling Functions\fP\s-1 -.sp 2 -.nr H1 11 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 11: Event Handling Functions -.XE -This chapter discusses the Xlib functions you can use to: -.IP \(bu 5 -Select events -.IP \(bu 5 -Handle the output buffer and the event queue -.IP \(bu 5 -Select events from the event queue -.IP \(bu 5 -Send and get events -.IP \(bu 5 -Handle protocol errors -.NT Note -Some toolkits use their own event-handling functions -and do not allow you to interchange these event-handling functions -with those in Xlib. -For further information, -see the documentation supplied with the toolkit. -.NE -.LP -Most applications simply are event loops: -they wait for an event, decide what to do with it, -execute some amount of code that results in changes to the display, -and then wait for the next event. -.NH 2 -Selecting Events -.XS -\*(SN Selecting Events -.XE -.LP -There are two ways to select the events you want reported to your client -application. -One way is to set the event_mask member of the -.PN XSetWindowAttributes -structure when you call -.PN XCreateWindow -and -.PN XChangeWindowAttributes . -Another way is to use -.PN XSelectInput . -.IN "XSelectInput" "" "@DEF@" -.sM -.FD 0 -XSelectInput\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - long \fIevent_mask\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose events you are interested in -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.LP -.eM -The -.PN XSelectInput -function requests that the X server report the events associated with the -specified event mask. -Initially, X will not report any of these events. -Events are reported relative to a window. -If a window is not interested in a device event, it usually propagates to -the closest ancestor that is interested, -unless the do_not_propagate mask prohibits it. -.IN "Event" "propagation" -.LP -Setting the event-mask attribute of a window overrides any previous call -for the same window but not for other clients. -Multiple clients can select for the same events on the same window -with the following restrictions: -.IP \(bu 5 -Multiple clients can select events on the same window because their event masks -are disjoint. -When the X server generates an event, it reports it -to all interested clients. -.IP \(bu 5 -Only one client at a time can select -.PN CirculateRequest , -.PN ConfigureRequest , -or -.PN MapRequest -events, which are associated with -the event mask -.PN SubstructureRedirectMask . -.IP \(bu 5 -Only one client at a time can select -a -.PN ResizeRequest -event, which is associated with -the event mask -.PN ResizeRedirectMask . -.IP \(bu 5 -Only one client at a time can select a -.PN ButtonPress -event, which is associated with -the event mask -.PN ButtonPressMask . -.LP -The server reports the event to all interested clients. -.LP -.PN XSelectInput -can generate a -.PN BadWindow -error. -.NH 2 -Handling the Output Buffer -.XS -\*(SN Handling the Output Buffer -.XE -.LP -The output buffer is an area used by Xlib to store requests. -The functions described in this section flush the output buffer -if the function would block or not return an event. -That is, all requests residing in the output buffer that -have not yet been sent are transmitted to the X server. -These functions differ in the additional tasks they might perform. -.LP -.sp -To flush the output buffer, use -.PN XFlush . -.IN "XFlush" "" "@DEF@" -.sM -.FD 0 -XFlush\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XFlush -function -flushes the output buffer. -Most client applications need not use this function because the output -buffer is automatically flushed as needed by calls to -.PN XPending , -.PN XNextEvent , -and -.PN XWindowEvent . -.IN "XPending" -.IN "XNextEvent" -.IN "XWindowEvent" -Events generated by the server may be enqueued into the library's event queue. -.LP -.sp -To flush the output buffer and then wait until all requests have been processed, -use -.PN XSync . -.IN "XSync" "" "@DEF@" -.sM -.FD 0 -XSync\^(\^\fIdisplay\fP, \fIdiscard\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Bool \fIdiscard\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdiscard\fP 1i -Specifies a Boolean value that indicates whether -.PN XSync -discards all events on the event queue. -.LP -.eM -The -.PN XSync -function -flushes the output buffer and then waits until all requests have been received -and processed by the X server. -Any errors generated must be handled by the error handler. -For each protocol error received by Xlib, -.PN XSync -calls the client application's error handling routine (see section 11.8.2). -Any events generated by the server are enqueued into the library's -event queue. -.LP -Finally, if you passed -.PN False , -.PN XSync -does not discard the events in the queue. -If you passed -.PN True , -.PN XSync -discards all events in the queue, -including those events that were on the queue before -.PN XSync -was called. -Client applications seldom need to call -.PN XSync . -.NH 2 -Event Queue Management -.XS -\*(SN Event Queue Management -.XE -.LP -Xlib maintains an event queue. -However, the operating system also may be buffering data -in its network connection that is not yet read into the event queue. -.LP -.sp -To check the number of events in the event queue, use -.PN XEventsQueued . -.IN "XEventsQueued" "" "@DEF@" -.sM -.FD 0 -int XEventsQueued\^(\^\fIdisplay\fP, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImode\fP 1i -Specifies the mode. -You can pass -.PN QueuedAlready , -.PN QueuedAfterFlush , -or -.PN QueuedAfterReading . -.LP -.eM -If mode is -.PN QueuedAlready , -.PN XEventsQueued -returns the number of events -already in the event queue (and never performs a system call). -If mode is -.PN QueuedAfterFlush , -.PN XEventsQueued -returns the number of events already in the queue if the number is nonzero. -If there are no events in the queue, -.PN XEventsQueued -flushes the output buffer, -attempts to read more events out of the application's connection, -and returns the number read. -If mode is -.PN QueuedAfterReading , -.PN XEventsQueued -returns the number of events already in the queue if the number is nonzero. -If there are no events in the queue, -.PN XEventsQueued -attempts to read more events out of the application's connection -without flushing the output buffer and returns the number read. -.LP -.PN XEventsQueued -always returns immediately without I/O if there are events already in the -queue. -.PN XEventsQueued -with mode -.PN QueuedAfterFlush -is identical in behavior to -.PN XPending . -.PN XEventsQueued -with mode -.PN QueuedAlready -is identical to the -.PN XQLength -function. -.LP -.sp -To return the number of events that are pending, use -.PN XPending . -.IN "XPending" "" "@DEF@" -.sM -.FD 0 -int XPending\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XPending -function returns the number of events that have been received from the -X server but have not been removed from the event queue. -.PN XPending -is identical to -.PN XEventsQueued -with the mode -.PN QueuedAfterFlush -specified. -.NH 2 -Manipulating the Event Queue -.XS -\*(SN Manipulating the Event Queue -.XE -.LP -Xlib provides functions that let you manipulate the event queue. -This section discusses how to: -.IP \(bu 5 -Obtain events, in order, and remove them from the queue -.IP \(bu 5 -Peek at events in the queue without removing them -.IP \(bu 5 -Obtain events that match the event mask or the arbitrary -predicate procedures that you provide -.NH 3 -Returning the Next Event -.XS -\*(SN Returning the Next Event -.XE -.LP -To get the next event and remove it from the queue, use -.PN XNextEvent . -.IN "XNextEvent" "" "@DEF@" -.sM -.FD 0 -XNextEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns the next event in the queue. -.LP -.eM -The -.PN XNextEvent -function copies the first event from the event queue into the specified -.PN XEvent -structure and then removes it from the queue. -If the event queue is empty, -.PN XNextEvent -flushes the output buffer and blocks until an event is received. -.LP -.sp -To peek at the event queue, use -.PN XPeekEvent . -.IN "XPeekEvent" "" "@DEF@" -.sM -.FD 0 -XPeekEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns a copy of the matched event's associated structure. -.LP -.eM -The -.PN XPeekEvent -function returns the first event from the event queue, -but it does not remove the event from the queue. -If the queue is empty, -.PN XPeekEvent -flushes the output buffer and blocks until an event is received. -It then copies the event into the client-supplied -.PN XEvent -structure without removing it from the event queue. -.NH 3 -Selecting Events Using a Predicate Procedure -.XS -\*(SN Selecting Events Using a Predicate Procedure -.XE -.LP -Each of the functions discussed in this section requires you to -pass a predicate procedure that determines if an event matches -what you want. -Your predicate procedure must decide if the event is useful -without calling any Xlib functions. -If the predicate directly or indirectly causes the state of the event queue -to change, the result is not defined. -If Xlib has been initialized for threads, the predicate is called with -the display locked and the result of a call by the predicate to any -Xlib function that locks the display is not defined unless the caller -has first called -.PN XLockDisplay . -.LP -The predicate procedure and its associated arguments are: -.sM -.FD 0 -Bool (\^*\fIpredicate\fP\^)\^(\^\fIdisplay\fP, \fIevent\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent\fP\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent\fP 1i -Specifies the -.PN XEvent -structure. -.IP \fIarg\fP 1i -Specifies the argument passed in from the -.PN XIfEvent , -.PN XCheckIfEvent , -or -.PN XPeekIfEvent -function. -.LP -.eM -The predicate procedure is called once for each -event in the queue until it finds a match. -After finding a match, the predicate procedure must return -.PN True . -If it did not find a match, it must return -.PN False . -.LP -.sp -To check the event queue for a matching event -and, if found, remove the event from the queue, use -.PN XIfEvent . -.IN "XIfEvent" "" "@DEF@" -.sM -.FD 0 -XIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.br - Bool (\^*\fIpredicate\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.IP \fIpredicate\fP 1i -Specifies the procedure that is to be called to determine -if the next event in the queue matches what you want. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the predicate procedure. -.LP -.eM -The -.PN XIfEvent -function completes only when the specified predicate -procedure returns -.PN True -for an event, -which indicates an event in the queue matches. -.PN XIfEvent -flushes the output buffer if it blocks waiting for additional events. -.PN XIfEvent -removes the matching event from the queue -and copies the structure into the client-supplied -.PN XEvent -structure. -.LP -.sp -To check the event queue for a matching event without blocking, use -.PN XCheckIfEvent . -.IN "XCheckIfEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.br - Bool (\^*\fIpredicate\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns a copy of the matched event's associated structure. -.IP \fIpredicate\fP 1i -Specifies the procedure that is to be called to determine -if the next event in the queue matches what you want. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the predicate procedure. -.LP -.eM -When the predicate procedure finds a match, -.PN XCheckIfEvent -copies the matched event into the client-supplied -.PN XEvent -structure and returns -.PN True . -(This event is removed from the queue.) -If the predicate procedure finds no match, -.PN XCheckIfEvent -returns -.PN False , -and the output buffer will have been flushed. -All earlier events stored in the queue are not discarded. -.LP -.sp -To check the event queue for a matching event -without removing the event from the queue, use -.PN XPeekIfEvent . -.IN "XPeekIfEvent" "" "@DEF@" -.sM -.FD 0 -XPeekIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.br - Bool (\^*\fIpredicate\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns a copy of the matched event's associated structure. -.IP \fIpredicate\fP 1i -Specifies the procedure that is to be called to determine -if the next event in the queue matches what you want. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the predicate procedure. -.LP -.eM -The -.PN XPeekIfEvent -function returns only when the specified predicate -procedure returns -.PN True -for an event. -After the predicate procedure finds a match, -.PN XPeekIfEvent -copies the matched event into the client-supplied -.PN XEvent -structure without removing the event from the queue. -.PN XPeekIfEvent -flushes the output buffer if it blocks waiting for additional events. -.NH 3 -Selecting Events Using a Window or Event Mask -.XS -\*(SN Selecting Events Using a Window or Event Mask -.XE -.LP -The functions discussed in this section let you select events by window -or event types, allowing you to process events out of order. -.LP -.sp -To remove the next event that matches both a window and an event mask, use -.PN XWindowEvent . -.IN "XWindowEvent" "" "@DEF@" -.sM -.FD 0 -XWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose events you are interested in -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XWindowEvent -function searches the event queue for an event that matches both the specified -window and event mask. -When it finds a match, -.PN XWindowEvent -removes that event from the queue and copies it into the specified -.PN XEvent -structure. -The other events stored in the queue are not discarded. -If a matching event is not in the queue, -.PN XWindowEvent -flushes the output buffer and blocks until one is received. -.LP -.sp -To remove the next event that matches both a window and an event mask (if any), -use -.PN XCheckWindowEvent . -.IN "XCheckWindowEvent" -This function is similar to -.PN XWindowEvent -except that it never blocks and it returns a -.PN Bool -indicating if the event was returned. -.IN "XCheckWindowEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose events you are interested in -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckWindowEvent -function searches the event queue and then the events available -on the server connection for the first event that matches the specified window -and event mask. -If it finds a match, -.PN XCheckWindowEvent -removes that event, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events stored in the queue are not discarded. -If the event you requested is not available, -.PN XCheckWindowEvent -returns -.PN False , -and the output buffer will have been flushed. -.LP -.sp -To remove the next event that matches an event mask, use -.PN XMaskEvent . -.IN "XMaskEvent" "" "@DEF@" -.sM -.FD 0 -XMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XMaskEvent -function searches the event queue for the events associated with the -specified mask. -When it finds a match, -.PN XMaskEvent -removes that event and copies it into the specified -.PN XEvent -structure. -The other events stored in the queue are not discarded. -If the event you requested is not in the queue, -.PN XMaskEvent -flushes the output buffer and blocks until one is received. -.LP -.sp -To return and remove the next event that matches an event mask (if any), use -.PN XCheckMaskEvent . -This function is similar to -.PN XMaskEvent -except that it never blocks and it returns a -.PN Bool -indicating if the event was returned. -.IN "XCheckMaskEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckMaskEvent -function searches the event queue and then any events available on the -server connection for the first event that matches the specified mask. -If it finds a match, -.PN XCheckMaskEvent -removes that event, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events stored in the queue are not discarded. -If the event you requested is not available, -.PN XCheckMaskEvent -returns -.PN False , -and the output buffer will have been flushed. -.LP -.sp -To return and remove the next event in the queue that matches an event type, use -.PN XCheckTypedEvent . -.IN "XCheckTypedEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckTypedEvent\^(\^\fIdisplay\fP, \fIevent_type\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIevent_type\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_type\fP 1i -Specifies the event type to be compared. - -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckTypedEvent -function searches the event queue and then any events available -on the server connection for the first event that matches the specified type. -If it finds a match, -.PN XCheckTypedEvent -removes that event, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events in the queue are not discarded. -If the event is not available, -.PN XCheckTypedEvent -returns -.PN False , -and the output buffer will have been flushed. -.LP -.sp -To return and remove the next event in the queue that matches an event type -and a window, use -.PN XCheckTypedWindowEvent . -.IN "XCheckTypedWindowEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckTypedWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_type\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIevent_type\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIevent_type\fP 1i -Specifies the event type to be compared. - -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckTypedWindowEvent -function searches the event queue and then any events available -on the server connection for the first event that matches the specified -type and window. -If it finds a match, -.PN XCheckTypedWindowEvent -removes the event from the queue, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events in the queue are not discarded. -If the event is not available, -.PN XCheckTypedWindowEvent -returns -.PN False , -and the output buffer will have been flushed. -.NH 2 -Putting an Event Back into the Queue -.XS -\*(SN Putting an Event Back into the Queue -.XE -.LP -To push an event back into the event queue, use -.PN XPutBackEvent . -.IN "XPutBackEvent" "" "@DEF@" -.sM -.FD 0 -XPutBackEvent\^(\^\fIdisplay\fP, \fIevent\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent\fP 1i -Specifies the event. -.LP -.eM -The -.PN XPutBackEvent -function pushes an event back onto the head of the display's event queue -by copying the event into the queue. -This can be useful if you read an event and then decide that you -would rather deal with it later. -There is no limit to the number of times in succession that you can call -.PN XPutBackEvent . -.NH 2 -Sending Events to Other Applications -.XS -\*(SN Sending Events to Other Applications -.XE -.LP -To send an event to a specified window, use -.PN XSendEvent . -.IN "XSendEvent" -This function is often used in selection processing. -For example, the owner of a selection should use -.PN XSendEvent -to send a -.PN SelectionNotify -event to a requestor when a selection has been converted -and stored as a property. -.IN "XSendEvent" "" "@DEF@" -.sM -.FD 0 -Status XSendEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIpropagate\fP\^, \fIevent_mask\fP\^, \fIevent_send\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Bool \fIpropagate\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_send\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window the event is to be sent to, or -.PN PointerWindow , -or -.PN InputFocus . -.IP \fIpropagate\fP 1i -Specifies a Boolean value. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_send\fP 1i -Specifies the event that is to be sent. -.LP -.eM -The -.PN XSendEvent -function identifies the destination window, -determines which clients should receive the specified events, -and ignores any active grabs. -This function requires you to pass an event mask. -For a discussion of the valid event mask names, -see section 10.3. -This function uses the w argument to identify the destination window as follows: -.IP \(bu 5 -If w is -.PN PointerWindow , -the destination window is the window that contains the pointer. -.IP \(bu 5 -If w is -.PN InputFocus -and if the focus window contains the pointer, -the destination window is the window that contains the pointer; -otherwise, the destination window is the focus window. -.LP -To determine which clients should receive the specified events, -.PN XSendEvent -uses the propagate argument as follows: -.IP \(bu 5 -If event_mask is the empty set, -the event is sent to the client that created the destination window. -If that client no longer exists, -no event is sent. -.IP \(bu 5 -If propagate is -.PN False , -the event is sent to every client selecting on destination any of the event -types in the event_mask argument. -.IP \(bu 5 -If propagate is -.PN True -and no clients have selected on destination any of -the event types in event-mask, the destination is replaced with the -closest ancestor of destination for which some client has selected a -type in event-mask and for which no intervening window has that type in its -do-not-propagate-mask. -If no such window exists or if the window is -an ancestor of the focus window and -.PN InputFocus -was originally specified -as the destination, the event is not sent to any clients. -Otherwise, the event is reported to every client selecting on the final -destination any of the types specified in event_mask. -.LP -The event in the -.PN XEvent -structure must be one of the core events or one of the events -defined by an extension (or a -.PN BadValue -error results) so that the X server can correctly byte-swap -the contents as necessary. -The contents of the event are -otherwise unaltered and unchecked by the X server except to force send_event to -.PN True -in the forwarded event and to set the serial number in the event correctly; -therefore these fields -and the display field are ignored by -.PN XSendEvent . -.LP -.PN XSendEvent -returns zero if the conversion to wire protocol format failed -and returns nonzero otherwise. -.LP -.PN XSendEvent -can generate -.PN BadValue -and -.PN BadWindow -errors. -.NH 2 -Getting Pointer Motion History -.XS -\*(SN Getting Pointer Motion History -.XE -.LP -Some X server implementations will maintain a more complete -history of pointer motion than is reported by event notification. -The pointer position at each pointer hardware interrupt may be -stored in a buffer for later retrieval. -This buffer is called the motion history buffer. -For example, a few applications, such as paint programs, -want to have a precise history of where the pointer -traveled. -However, this historical information is highly excessive for most applications. -.LP -.sp -To determine the approximate maximum number of elements in the motion buffer, -use -.PN XDisplayMotionBufferSize . -.IN "XDisplayMotionBufferSize" "" "@DEF@" -.sM -.FD 0 -unsigned long XDisplayMotionBufferSize\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The server may retain the recent history of the pointer motion -and do so to a finer granularity than is reported by -.PN MotionNotify -events. -The -.PN XGetMotionEvents -function makes this history available. -.LP -.sp -To get the motion history for a specified window and time, use -.PN XGetMotionEvents . -.IN "XGetMotionEvents" "" "@DEF@" -.sM -.FD 0 -XTimeCoord *XGetMotionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIstart\fP\^, \fIstop\fP\^, \fInevents_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Time \fIstart\fP\^, \fIstop\fP\^; -.br - int *\fInevents_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIstart\fP 1i -.br -.ns -.IP \fIstop\fP 1i -Specify the time interval in which the events are returned from the motion -history buffer. -You can pass a timestamp or -.PN CurrentTime . -.IP \fInevents_return\fP 1i -Returns the number of events from the motion history buffer. -.LP -.eM -The -.PN XGetMotionEvents -function returns all events in the motion history buffer that fall between the -specified start and stop times, inclusive, and that have coordinates -that lie within the specified window (including its borders) at its present -placement. -If the server does not support motion history, -if the start time is later than the stop time, -or if the start time is in the future, -no events are returned; -.PN XGetMotionEvents -returns NULL. -If the stop time is in the future, it is equivalent to specifying -.PN CurrentTime . -The return type for this function is a structure defined as follows: -.LP -.IN "XTimeCoord" "" "@DEF@" -.sM -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - Time time; - short x, y; -} XTimeCoord; -.De -.LP -.eM -The time member is set to the time, in milliseconds. -The x and y members are set to the coordinates of the pointer and -are reported relative to the origin -of the specified window. -To free the data returned from this call, use -.PN XFree . -.LP -.PN XGetMotionEvents -can generate a -.PN BadWindow -error. -.NH 2 -Handling Protocol Errors -.XS -\*(SN Handling Protocol Errors -.XE -.LP -Xlib provides functions that you can use to enable or disable synchronization -and to use the default error handlers. -.NH 3 -Enabling or Disabling Synchronization -.XS -\*(SN Enabling or Disabling Synchronization -.XE -.LP -When debugging X applications, -it often is very convenient to require Xlib to behave synchronously -so that errors are reported as they occur. -The following function lets you disable or enable synchronous behavior. -Note that graphics may occur 30 or more times more slowly when -synchronization is enabled. -.IN "_Xdebug" -On POSIX-conformant systems, -there is also a global variable -.PN _Xdebug -that, if set to nonzero before starting a program under a debugger, will force -synchronous library behavior. -.LP -After completing their work, -all Xlib functions that generate protocol requests call what is known as -an after function. -.PN XSetAfterFunction -sets which function is to be called. -.IN "XSetAfterFunction" "" "@DEF@" -.sM -.FD 0 -int (*XSetAfterFunction\^(\^\fIdisplay\fP, \fIprocedure\fP\^))() -.br - Display *\fIdisplay\fP\^; -.br - int (\^*\^\fIprocedure\fP\^)\^(); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprocedure\fP 1i -Specifies the procedure to be called. -.LP -.eM -The specified procedure is called with only a display pointer. -.PN XSetAfterFunction -returns the previous after function. -.LP -To enable or disable synchronization, use -.PN XSynchronize . -.IN "Debugging" "synchronous mode" -.IN "XSynchronize" "" "@DEF@" -.sM -.FD 0 -int (*XSynchronize\^(\^\fIdisplay\fP, \fIonoff\fP\^)\^)() -.br - Display *\fIdisplay\fP\^; -.br - Bool \fIonoff\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIonoff\fP 1i -Specifies a Boolean value that indicates whether to enable -or disable synchronization. -.LP -.eM -The -.PN XSynchronize -function returns -the previous after function. -If onoff is -.PN True , -.PN XSynchronize -turns on synchronous behavior. -If onoff is -.PN False , -.PN XSynchronize -turns off synchronous behavior. -.NH 3 -Using the Default Error Handlers -.XS -\*(SN Using the Default Error Handlers -.XE -.LP -.IN "Debugging" "error handlers" -.IN "Error" "handlers" -There are two default error handlers in Xlib: -one to handle typically fatal conditions (for example, -the connection to a display server dying because a machine crashed) -and one to handle protocol errors from the X server. -These error handlers can be changed to user-supplied routines if you -prefer your own error handling and can be changed as often as you like. -If either function is passed a NULL pointer, it will -reinvoke the default handler. -The action of the default handlers is to print an explanatory -message and exit. -.LP -.sp -To set the error handler, use -.PN XSetErrorHandler . -.IN "XSetErrorHandler" "" "@DEF@" -.sM -.FD 0 -int (*XSetErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^) -.br - int (\^*\^\fIhandler\fP\^)\^(Display *, XErrorEvent *) -.FN -.IP \fIhandler\fP 1i -Specifies the program's supplied error handler. -.LP -.eM -Xlib generally calls the program's -supplied error handler whenever an error is received. -It is not called on -.PN BadName -errors from -.PN OpenFont , -.PN LookupColor , -or -.PN AllocNamedColor -protocol requests or on -.PN BadFont -errors from a -.PN QueryFont -protocol request. -These errors generally are reflected back to the program through the -procedural interface. -Because this condition is not assumed to be fatal, -it is acceptable for your error handler to return; -the returned value is ignored. -However, the error handler should not -call any functions (directly or indirectly) on the display -that will generate protocol requests or that will look for input events. -The previous error handler is returned. -.LP -The -.PN XErrorEvent -structure contains: -.IN "Debugging" "error event" -.LP -.IN "XErrorEvent" "" "@DEF" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int type; - Display *display; /* Display the event was read from */ - unsigned long serial; /* serial number of failed request */ - unsigned char error_code; /* error code of failed request */ - unsigned char request_code; /* Major op-code of failed request */ - unsigned char minor_code; /* Minor op-code of failed request */ - XID resourceid; /* resource id */ -} XErrorEvent; -.De -.LP -.IN "Serial Number" -The serial member is the number of requests, starting from one, -sent over the network connection since it was opened. -It is the number that was the value of -.PN NextRequest -immediately before the failing call was made. -The request_code member is a protocol request -of the procedure that failed, as defined in -.hN X11/Xproto.h . -The following error codes can be returned by the functions described in this -chapter: -.br -.ne 13 -.IN "Debugging" "error numbers" -.IN "Error" "codes" -.\".CP T 3 -.\"Error Codes -.IN "BadAccess" "" "@DEF@" -.IN "BadAlloc" "" "@DEF@" -.IN "BadAtom" "" "@DEF@" -.IN "BadColor" "" "@DEF@" -.IN "BadCursor" "" "@DEF@" -.IN "BadDrawable" "" "@DEF@" -.IN "BadFont" "" "@DEF@" -.IN "BadGC" "" "@DEF@" -.IN "BadIDChoice" "" "@DEF@" -.TS H -l c -lw(1.75i) lw(4i). -_ -.sp 6p -.B -Error Code Description -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN BadAccess -T} T{ -A client attempts to grab a key/button combination already grabbed -by another client. -.sp 3p -A client attempts to free a colormap entry that it had not already allocated -or to free an entry in a colormap that was created with all entries writable. -.sp 3p -A client attempts to store into a read-only or unallocated colormap entry. -.sp 3p -A client attempts to modify the access control list from other than the local -(or otherwise authorized) host. -.sp 3p -A client attempts to select an event type that another client -has already selected. -T} -.sp 3p -T{ -.PN BadAlloc -T} T{ -The server fails to allocate the requested resource. -Note that the explicit listing of -.PN BadAlloc -errors in requests only covers allocation errors at a very coarse level -and is not intended to (nor can it in practice hope to) cover all cases of -a server running out of allocation space in the middle of service. -The semantics when a server runs out of allocation space are left unspecified, -but a server may generate a -.PN BadAlloc -error on any request for this reason, -and clients should be prepared to receive such errors and handle or discard -them. -T} -.sp 3p -T{ -.PN BadAtom -T} T{ -A value for an atom argument does not name a defined atom. -T} -.sp 3p -T{ -.PN BadColor -T} T{ -A value for a colormap argument does not name a defined colormap. -T} -.sp 3p -T{ -.PN BadCursor -T} T{ -A value for a cursor argument does not name a defined cursor. -T} -.sp 3p -T{ -.PN BadDrawable -T} T{ -A value for a drawable argument does not name a defined window or pixmap. -T} -.sp 3p -T{ -.PN BadFont -T} T{ -A value for a font argument does not name a defined font (or, in some cases, -.PN GContext ). -T} -.sp 3p -T{ -.PN BadGC -T} T{ -A value for a -.PN GContext -argument does not name a defined -.PN GContext . -T} -.sp 3p -T{ -.PN BadIDChoice -T} T{ -The value chosen for a resource identifier either is not included in the -range assigned to the client or is already in use. -Under normal circumstances, -this cannot occur and should be considered a server or Xlib error. -T} -.sp 3p -T{ -.PN BadImplementation -T} T{ -The server does not implement some aspect of the request. -A server that generates this error for a core request is deficient. -As such, this error is not listed for any of the requests, -but clients should be prepared to receive such errors -and handle or discard them. -T} -.sp 3p -T{ -.PN BadLength -T} T{ -The length of a request is shorter or longer than that required to -contain the arguments. -This is an internal Xlib or server error. -.sp 3p -The length of a request exceeds the maximum length accepted by the server. -T} -.sp 3p -T{ -.PN BadMatch -T} T{ -In a graphics request, -the root and depth of the graphics context do not match those of the drawable. -.sp 3p -An -.PN InputOnly -window is used as a drawable. -.sp 3p -Some argument or pair of arguments has the correct type and range, -but it fails to match in some other way required by the request. -.sp 3p -An -.PN InputOnly -window lacks this attribute. -T} -.sp 3p -T{ -.PN BadName -T} T{ -A font or color of the specified name does not exist. -T} -.sp 3p -T{ -.PN BadPixmap -T} T{ -A value for a pixmap argument does not name a defined pixmap. -T} -.sp 3p -T{ -.PN BadRequest -T} T{ -The major or minor opcode does not specify a valid request. -This usually is an Xlib or server error. -T} -.sp 3p -T{ -.PN BadValue -T} T{ -Some numeric value falls outside of the range of values accepted -by the request. -Unless a specific range is specified for an argument, -the full range defined by the argument's type is accepted. -Any argument defined as a set of alternatives typically can generate -this error (due to the encoding). -T} -.sp 3p -T{ -.PN BadWindow -T} T{ -A value for a window argument does not name a defined window. -T} -.sp 6p -_ -.TE -.IN "BadImplementation" "" "@DEF@" -.IN "BadLength" "" "@DEF@" -.IN "BadMatch" "" "@DEF@" -.IN "BadName" "" "@DEF@" -.IN "BadPixmap" "" "@DEF@" -.IN "BadRequest" "" "@DEF@" -.IN "BadValue" "" "@DEF@" -.IN "BadWindow" "" "@DEF@" -.NT Note -The -.PN BadAtom , -.PN BadColor , -.PN BadCursor , -.PN BadDrawable , -.PN BadFont , -.PN BadGC , -.PN BadPixmap , -and -.PN BadWindow -errors are also used when the argument type is extended by a set of -fixed alternatives. -.NE -.sp -.LP -To obtain textual descriptions of the specified error code, use -.PN XGetErrorText . -.IN "XGetErrorText" "" "@DEF@" -.IN "Debugging" "error message strings" -.sM -.FD 0 -XGetErrorText\^(\^\fIdisplay\fP, \fIcode\fP, \fIbuffer_return\fP, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIcode\fP\^; -.br - char *\fIbuffer_return\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcode\fP 1i -Specifies the error code for which you want to obtain a description. -.IP \fIbuffer_return\fP 1i -Returns the error description. -.IP \fIlength\fP 1i -Specifies the size of the buffer. -.LP -.eM -The -.PN XGetErrorText -function copies a null-terminated string describing the specified error code -into the specified buffer. -The returned text is in the encoding of the current locale. -It is recommended that you use this function to obtain an error description -because extensions to Xlib may define their own error codes -and error strings. -.LP -.sp -To obtain error messages from the error database, use -.PN XGetErrorDatabaseText . -.IN "XGetErrorDatabaseText" "" "@DEF@" -.sM -.FD 0 -XGetErrorDatabaseText\^(\^\fIdisplay\fP, \fIname\fP, \fImessage\fP, \fIdefault_string\fP, \fIbuffer_return\fP, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIname\fP, *\fImessage\fP\^; -.br - char *\fIdefault_string\fP\^; -.br - char *\fIbuffer_return\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIname\fP 1i -Specifies the name of the application. -.IP \fImessage\fP 1i -Specifies the type of the error message. -.IP \fIdefault_string\fP 1i -Specifies the default error message if none is found in the database. -.IP \fIbuffer_return\fP 1i -Returns the error description. -.IP \fIlength\fP 1i -Specifies the size of the buffer. -.LP -.eM -The -.PN XGetErrorDatabaseText -function returns a null-terminated message -(or the default message) from the error message -database. -Xlib uses this function internally to look up its error messages. -The text in the default_string argument is assumed -to be in the encoding of the current locale, -and the text stored in the buffer_return argument -is in the encoding of the current locale. -.LP -The name argument should generally be the name of your application. -The message argument should indicate which type of error message you want. -If the name and message are not in the Host Portable Character Encoding, -the result is implementation-dependent. -Xlib uses three predefined ``application names'' to report errors. -In these names, -uppercase and lowercase matter. -.IP XProtoError 1i -The protocol error number is used as a string for the message argument. -.IP XlibMessage 1i -These are the message strings that are used internally by the library. -.IP XRequest 1i -For a core protocol request, -the major request protocol number is used for the message argument. -For an extension request, -the extension name (as given by -.PN InitExtension ) -followed by a period (\.) and the minor request protocol number -is used for the message argument. -If no string is found in the error database, -the default_string is returned to the buffer argument. -.LP -.sp -To report an error to the user when the requested display does not exist, use -.PN XDisplayName . -.IN "XDisplayName" "" "@DEF@" -.sM -.FD 0 -char *XDisplayName\^(\^\fIstring\fP\^) -.br - char *\fIstring\fP\^; -.FN -.IP \fIstring\fP 1i -Specifies the character string. -.LP -.eM -The -.PN XDisplayName -function returns the name of the display that -.PN XOpenDisplay -would attempt to use. -If a NULL string is specified, -.PN XDisplayName -looks in the environment for the display and returns the display name that -.PN XOpenDisplay -would attempt to use. -This makes it easier to report to the user precisely which display the -program attempted to open when the initial connection attempt failed. -.LP -.sp -To handle fatal I/O errors, use -.PN XSetIOErrorHandler . -.IN "XSetIOErrorHandler" "" "@DEF@" -.sM -.FD 0 -int (*XSetIOErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^) -.br - int (\^*\^\fIhandler\fP\^)(Display *); -.FN -.IP \fIhandler\fP 1i -Specifies the program's supplied error handler. -.LP -.eM -The -.PN XSetIOErrorHandler -sets the fatal I/O error handler. -Xlib calls the program's supplied error handler if any sort of system call -error occurs (for example, the connection to the server was lost). -This is assumed to be a fatal condition, -and the called routine should not return. -If the I/O error handler does return, -the client process exits. -.LP -Note that the previous error handler is returned. -.bp diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml new file mode 100644 index 000000000..1a9bfc139 --- /dev/null +++ b/libX11/specs/libX11/CH11.xml @@ -0,0 +1,2539 @@ +<chapter id="event_handling_functions">
+<title>Event Handling Functions</title>
+
+<para>
+This chapter discusses the Xlib functions you can use to:
+</para>
+<itemizedlist>
+ <listitem><para>Select events</para></listitem>
+ <listitem><para>Handle the output buffer and the event queue</para></listitem>
+ <listitem><para>Select events from the event queue</para></listitem>
+ <listitem><para>Send and get events</para></listitem>
+ <listitem><para>Handle protocol errors</para></listitem>
+</itemizedlist>
+<note><para>
+Some toolkits use their own event-handling functions and do not allow you to
+interchange these event-handling functions with those in Xlib. For further
+information, see the documentation supplied with the toolkit.
+</para></note>
+
+<para>
+Most applications simply are event loops: they wait for an event, decide what to do with it,
+execute some amount of code that results in changes to the display, and then wait for the next
+event.
+</para>
+
+<sect1 id="Selecting_Events">
+<title>Selecting Events</title>
+<!-- .XS -->
+<!-- (SN Selecting Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+There are two ways to select the events you want reported to your client
+application.
+One way is to set the event_mask member of the
+<function>XSetWindowAttributes</function>
+structure when you call
+<function>XCreateWindow</function>
+and
+<function>XChangeWindowAttributes</function>.
+Another way is to use
+<function>XSelectInput</function>.
+<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSelectInput</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSelectInput</function>
+function requests that the X server report the events associated with the
+specified event mask.
+Initially, X will not report any of these events.
+Events are reported relative to a window.
+If a window is not interested in a device event, it usually propagates to
+the closest ancestor that is interested,
+unless the do_not_propagate mask prohibits it.
+<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Setting the event-mask attribute of a window overrides any previous call
+for the same window but not for other clients.
+Multiple clients can select for the same events on the same window
+with the following restrictions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Multiple clients can select events on the same window because their event masks
+are disjoint.
+When the X server generates an event, it reports it
+to all interested clients.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one client at a time can select
+<function>CirculateRequest</function>,
+<function>ConfigureRequest</function>,
+or
+<function>MapRequest</function>
+events, which are associated with
+the event mask
+<function>SubstructureRedirectMask</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one client at a time can select
+a
+<function>ResizeRequest</function>
+event, which is associated with
+the event mask
+<function>ResizeRedirectMask</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one client at a time can select a
+<function>ButtonPress </function>
+event, which is associated with
+the event mask
+<function>ButtonPressMask</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The server reports the event to all interested clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XSelectInput</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_the_Output_Buffer">
+<title>Handling the Output Buffer</title>
+<!-- .XS -->
+<!-- (SN Handling the Output Buffer -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The output buffer is an area used by Xlib to store requests.
+The functions described in this section flush the output buffer
+if the function would block or not return an event.
+That is, all requests residing in the output buffer that
+have not yet been sent are transmitted to the X server.
+These functions differ in the additional tasks they might perform.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer, use
+<function>XFlush</function>.
+<indexterm significance="preferred"><primary>XFlush</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFlush</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFlush</function>
+function
+flushes the output buffer.
+Most client applications need not use this function because the output
+buffer is automatically flushed as needed by calls to
+<function>XPending</function>,
+<function>XNextEvent</function>,
+and
+<function>XWindowEvent</function>.
+<indexterm><primary>XPending</primary></indexterm>
+<indexterm><primary>XNextEvent</primary></indexterm>
+<indexterm><primary>XWindowEvent</primary></indexterm>
+Events generated by the server may be enqueued into the library's event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer and then wait until all requests have been processed,
+use
+<function>XSync</function>.
+<indexterm significance="preferred"><primary>XSync</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSync</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Bool<parameter> discard</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>discard</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether
+<function>XSync</function>
+discards all events on the event queue.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSync</function>
+function
+flushes the output buffer and then waits until all requests have been received
+and processed by the X server.
+Any errors generated must be handled by the error handler.
+For each protocol error received by Xlib,
+<function>XSync</function>
+calls the client application's error handling routine (see section 11.8.2).
+Any events generated by the server are enqueued into the library's
+event queue.
+</para>
+<para>
+<!-- .LP -->
+Finally, if you passed
+<function>False</function>,
+<function>XSync</function>
+does not discard the events in the queue.
+If you passed
+<function>True</function>,
+<function>XSync </function>
+discards all events in the queue,
+including those events that were on the queue before
+<function>XSync</function>
+was called.
+Client applications seldom need to call
+<function>XSync</function>.
+</para>
+</sect1>
+<sect1 id="Event_Queue_Management">
+<title>Event Queue Management</title>
+<!-- .XS -->
+<!-- (SN Event Queue Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib maintains an event queue.
+However, the operating system also may be buffering data
+in its network connection that is not yet read into the event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the number of events in the event queue, use
+<function>XEventsQueued</function>.
+<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XEventsQueued</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode.
+You can pass
+<function>QueuedAlready</function>,
+<function>QueuedAfterFlush</function>,
+or
+<function>QueuedAfterReading</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If mode is
+<function>QueuedAlready</function>,
+<function>XEventsQueued </function>
+returns the number of events
+already in the event queue (and never performs a system call).
+If mode is
+<function>QueuedAfterFlush</function>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue,
+<function>XEventsQueued</function>
+flushes the output buffer,
+attempts to read more events out of the application's connection,
+and returns the number read.
+If mode is
+<function>QueuedAfterReading</function>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue,
+<function>XEventsQueued</function>
+attempts to read more events out of the application's connection
+without flushing the output buffer and returns the number read.
+</para>
+<para>
+<!-- .LP -->
+<function>XEventsQueued</function>
+always returns immediately without I/O if there are events already in the
+queue.
+<function>XEventsQueued</function>
+with mode
+<function>QueuedAfterFlush</function>
+is identical in behavior to
+<function>XPending</function>.
+<function>XEventsQueued</function>
+with mode
+<function>QueuedAlready</function>
+is identical to the
+<function>XQLength</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the number of events that are pending, use
+<function>XPending</function>.
+<indexterm significance="preferred"><primary>XPending</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XPending</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPending</function>
+function returns the number of events that have been received from the
+X server but have not been removed from the event queue.
+<function>XPending</function>
+is identical to
+<function>XEventsQueued</function>
+with the mode
+<function>QueuedAfterFlush</function>
+specified.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Event_Queue">
+<title>Manipulating the Event Queue</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Event Queue -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that let you manipulate the event queue.
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Obtain events, in order, and remove them from the queue
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Peek at events in the queue without removing them
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain events that match the event mask or the arbitrary
+predicate procedures that you provide
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Returning_the_Next_Event">
+<title>Returning the Next Event</title>
+<!-- .XS -->
+<!-- (SN Returning the Next Event -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To get the next event and remove it from the queue, use
+<function>XNextEvent</function>.
+<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XNextEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the next event in the queue.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNextEvent</function>
+function copies the first event from the event queue into the specified
+<function>XEvent</function>
+structure and then removes it from the queue.
+If the event queue is empty,
+<function>XNextEvent</function>
+flushes the output buffer and blocks until an event is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To peek at the event queue, use
+<function>XPeekEvent</function>.
+<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPeekEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a copy of the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekEvent</function>
+function returns the first event from the event queue,
+but it does not remove the event from the queue.
+If the queue is empty,
+<function>XPeekEvent</function>
+flushes the output buffer and blocks until an event is received.
+It then copies the event into the client-supplied
+<function>XEvent</function>
+structure without removing it from the event queue.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">
+<title>Selecting Events Using a Predicate Procedure</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Predicate Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Each of the functions discussed in this section requires you to
+pass a predicate procedure that determines if an event matches
+what you want.
+Your predicate procedure must decide if the event is useful
+without calling any Xlib functions.
+If the predicate directly or indirectly causes the state of the event queue
+to change, the result is not defined.
+If Xlib has been initialized for threads, the predicate is called with
+the display locked and the result of a call by the predicate to any
+Xlib function that locks the display is not defined unless the caller
+has first called
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+The predicate procedure and its associated arguments are:
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> Bool</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XEvent</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument passed in from the
+<function>XIfEvent</function>,
+<function>XCheckIfEvent</function>,
+or
+<function>XPeekIfEvent </function>
+function.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The predicate procedure is called once for each
+event in the queue until it finds a match.
+After finding a match, the predicate procedure must return
+<function>True</function>.
+If it did not find a match, it must return
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+and, if found, remove the event from the queue, use
+<function>XIfEvent</function>.
+<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XIfEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIfEvent</function>
+function completes only when the specified predicate
+procedure returns
+<function>True </function>
+for an event,
+which indicates an event in the queue matches.
+<function>XIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+<function>XIfEvent</function>
+removes the matching event from the queue
+and copies the structure into the client-supplied
+<function>XEvent</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event without blocking, use
+<function>XCheckIfEvent</function>.
+<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckIfEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a copy of the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When the predicate procedure finds a match,
+<function>XCheckIfEvent</function>
+copies the matched event into the client-supplied
+<function>XEvent</function>
+structure and returns
+<function>True</function>.
+(This event is removed from the queue.)
+If the predicate procedure finds no match,
+<function>XCheckIfEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+All earlier events stored in the queue are not discarded.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+without removing the event from the queue, use
+<function>XPeekIfEvent</function>.
+<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPeekIfEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a copy of the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekIfEvent</function>
+function returns only when the specified predicate
+procedure returns
+<function>True</function>
+for an event.
+After the predicate procedure finds a match,
+<function>XPeekIfEvent</function>
+copies the matched event into the client-supplied
+<function>XEvent</function>
+structure without removing the event from the queue.
+<function>XPeekIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">
+<title>Selecting Events Using a Window or Event Mask</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Window or Event Mask -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The functions discussed in this section let you select events by window
+or event types, allowing you to process events out of order.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask, use
+<function>XWindowEvent</function>.
+<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XWindowEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWindowEvent</function>
+function searches the event queue for an event that matches both the specified
+window and event mask.
+When it finds a match,
+<function>XWindowEvent</function>
+removes that event from the queue and copies it into the specified
+<function>XEvent</function>
+structure.
+The other events stored in the queue are not discarded.
+If a matching event is not in the queue,
+<function>XWindowEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask (if any),
+use
+<function>XCheckWindowEvent</function>.
+<indexterm><primary>XCheckWindowEvent</primary></indexterm>
+This function is similar to
+<function>XWindowEvent </function>
+except that it never blocks and it returns a
+<function>Bool </function>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckWindowEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckWindowEvent</function>
+function searches the event queue and then the events available
+on the server connection for the first event that matches the specified window
+and event mask.
+If it finds a match,
+<function>XCheckWindowEvent</function>
+removes that event, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckWindowEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches an event mask, use
+<function>XMaskEvent</function>.
+<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMaskEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMaskEvent</function>
+function searches the event queue for the events associated with the
+specified mask.
+When it finds a match,
+<function>XMaskEvent</function>
+removes that event and copies it into the specified
+<function>XEvent</function>
+structure.
+The other events stored in the queue are not discarded.
+If the event you requested is not in the queue,
+<function>XMaskEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event that matches an event mask (if any), use
+<function>XCheckMaskEvent</function>.
+This function is similar to
+<function>XMaskEvent </function>
+except that it never blocks and it returns a
+<function>Bool </function>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckMaskEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckMaskEvent</function>
+function searches the event queue and then any events available on the
+server connection for the first event that matches the specified mask.
+If it finds a match,
+<function>XCheckMaskEvent</function>
+removes that event, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckMaskEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event in the queue that matches an event type, use
+<function>XCheckTypedEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckTypedEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> event_type</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type to be compared.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedEvent</function>
+function searches the event queue and then any events available
+on the server connection for the first event that matches the specified type.
+If it finds a match,
+<function>XCheckTypedEvent</function>
+removes that event, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event in the queue that matches an event type
+and a window, use
+<function>XCheckTypedWindowEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckTypedWindowEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> event_type</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type to be compared.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedWindowEvent</function>
+function searches the event queue and then any events available
+on the server connection for the first event that matches the specified
+type and window.
+If it finds a match,
+<function>XCheckTypedWindowEvent</function>
+removes the event from the queue, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedWindowEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Putting_an_Event_Back_into_the_Queue">
+<title>Putting an Event Back into the Queue</title>
+<!-- .XS -->
+<!-- (SN Putting an Event Back into the Queue -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To push an event back into the event queue, use
+<function>XPutBackEvent</function>.
+<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPutBackEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPutBackEvent</function>
+function pushes an event back onto the head of the display's event queue
+by copying the event into the queue.
+This can be useful if you read an event and then decide that you
+would rather deal with it later.
+There is no limit to the number of times in succession that you can call
+<function>XPutBackEvent</function>.
+</para>
+</sect1>
+<sect1 id="Sending_Events_to_Other_Applications">
+<title>Sending Events to Other Applications</title>
+<!-- .XS -->
+<!-- (SN Sending Events to Other Applications -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To send an event to a specified window, use
+<function>XSendEvent</function>.
+<indexterm><primary>XSendEvent</primary></indexterm>
+This function is often used in selection processing.
+For example, the owner of a selection should use
+<function>XSendEvent</function>
+to send a
+<function>SelectionNotify</function>
+event to a requestor when a selection has been converted
+and stored as a property.
+<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XSendEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Bool<parameter> propagate</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_send</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window the event is to be sent to, or
+<function>PointerWindow</function>,
+or
+<function>InputFocus</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>propagate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_send</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event that is to be sent.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSendEvent</function>
+function identifies the destination window,
+determines which clients should receive the specified events,
+and ignores any active grabs.
+This function requires you to pass an event mask.
+For a discussion of the valid event mask names,
+see section 10.3.
+This function uses the w argument to identify the destination window as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If w is
+<function>PointerWindow</function>,
+the destination window is the window that contains the pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If w is
+<function>InputFocus </function>
+and if the focus window contains the pointer,
+the destination window is the window that contains the pointer;
+otherwise, the destination window is the focus window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To determine which clients should receive the specified events,
+<function>XSendEvent</function>
+uses the propagate argument as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If event_mask is the empty set,
+the event is sent to the client that created the destination window.
+If that client no longer exists,
+no event is sent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If propagate is
+<function>False</function>,
+the event is sent to every client selecting on destination any of the event
+types in the event_mask argument.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If propagate is
+<function>True </function>
+and no clients have selected on destination any of
+the event types in event-mask, the destination is replaced with the
+closest ancestor of destination for which some client has selected a
+type in event-mask and for which no intervening window has that type in its
+do-not-propagate-mask.
+If no such window exists or if the window is
+an ancestor of the focus window and
+<function>InputFocus </function>
+was originally specified
+as the destination, the event is not sent to any clients.
+Otherwise, the event is reported to every client selecting on the final
+destination any of the types specified in event_mask.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The event in the
+<function>XEvent</function>
+structure must be one of the core events or one of the events
+defined by an extension (or a
+<function>BadValue</function>
+error results) so that the X server can correctly byte-swap
+the contents as necessary.
+The contents of the event are
+otherwise unaltered and unchecked by the X server except to force send_event to
+<function>True</function>
+in the forwarded event and to set the serial number in the event correctly;
+therefore these fields
+and the display field are ignored by
+<function>XSendEvent</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+returns zero if the conversion to wire protocol format failed
+and returns nonzero otherwise.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Getting_Pointer_Motion_History">
+<title>Getting Pointer Motion History</title>
+<!-- .XS -->
+<!-- (SN Getting Pointer Motion History -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some X server implementations will maintain a more complete
+history of pointer motion than is reported by event notification.
+The pointer position at each pointer hardware interrupt may be
+stored in a buffer for later retrieval.
+This buffer is called the motion history buffer.
+For example, a few applications, such as paint programs,
+want to have a precise history of where the pointer
+traveled.
+However, this historical information is highly excessive for most applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine the approximate maximum number of elements in the motion buffer,
+use
+<function>XDisplayMotionBufferSize</function>.
+<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned<function> long</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The server may retain the recent history of the pointer motion
+and do so to a finer granularity than is reported by
+<function>MotionNotify</function>
+events.
+The
+<function>XGetMotionEvents</function>
+function makes this history available.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the motion history for a specified window and time, use
+<function>XGetMotionEvents</function>.
+<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XTimeCoord<function> *XGetMotionEvents</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Timestart,<parameter> stop</parameter></paramdef>
+ <paramdef>int<parameter> *nevents_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>start</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the time interval in which the events are returned from the motion
+history buffer.
+You can pass a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nevents_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of events from the motion history buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetMotionEvents</function>
+function returns all events in the motion history buffer that fall between the
+specified start and stop times, inclusive, and that have coordinates
+that lie within the specified window (including its borders) at its present
+placement.
+If the server does not support motion history,
+if the start time is later than the stop time,
+or if the start time is in the future,
+no events are returned;
+<function>XGetMotionEvents</function>
+returns NULL.
+If the stop time is in the future, it is equivalent to specifying
+<function>CurrentTime</function>.
+The return type for this function is a structure defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ Time time;
+ short x, y;
+} XTimeCoord;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The time member is set to the time, in milliseconds.
+The x and y members are set to the coordinates of the pointer and
+are reported relative to the origin
+of the specified window.
+To free the data returned from this call, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetMotionEvents</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_Protocol_Errors">
+<title>Handling Protocol Errors</title>
+<!-- .XS -->
+<!-- (SN Handling Protocol Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to enable or disable synchronization
+and to use the default error handlers.
+</para>
+<sect2 id="Enabling_or_Disabling_Synchronization">
+<title>Enabling or Disabling Synchronization</title>
+<!-- .XS -->
+<!-- (SN Enabling or Disabling Synchronization -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When debugging X applications,
+it often is very convenient to require Xlib to behave synchronously
+so that errors are reported as they occur.
+The following function lets you disable or enable synchronous behavior.
+Note that graphics may occur 30 or more times more slowly when
+synchronization is enabled.
+<indexterm><primary>_Xdebug</primary></indexterm>
+On <acronym>POSIX</acronym>-conformant systems,
+there is also a global variable
+<function>_Xdebug </function>
+that, if set to nonzero before starting a program under a debugger, will force
+synchronous library behavior.
+</para>
+<para>
+<!-- .LP -->
+After completing their work,
+all Xlib functions that generate protocol requests call what is known as
+an after function.
+<function>XSetAfterFunction</function>
+sets which function is to be called.
+<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> int</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> (*procedure)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The specified procedure is called with only a display pointer.
+<function>XSetAfterFunction</function>
+returns the previous after function.
+</para>
+<para>
+<!-- .LP -->
+To enable or disable synchronization, use
+<function>XSynchronize</function>.
+<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> int</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Bool<parameter> onoff</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>onoff</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether to enable
+or disable synchronization.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSynchronize</function>
+function returns
+the previous after function.
+If onoff is
+<function>True</function>,
+<function>XSynchronize</function>
+turns on synchronous behavior.
+If onoff is
+<function>False</function>,
+<function>XSynchronize </function>
+turns off synchronous behavior.
+</para>
+</sect2>
+<sect2 id="Using_the_Default_Error_Handlers">
+<title>Using the Default Error Handlers</title>
+<!-- .XS -->
+<!-- (SN Using the Default Error Handlers -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>
+There are two default error handlers in Xlib:
+one to handle typically fatal conditions (for example,
+the connection to a display server dying because a machine crashed)
+and one to handle protocol errors from the X server.
+These error handlers can be changed to user-supplied routines if you
+prefer your own error handling and can be changed as often as you like.
+If either function is passed a NULL pointer, it will
+reinvoke the default handler.
+The action of the default handlers is to print an explanatory
+message and exit.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the error handler, use
+<function>XSetErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XSetErrorHandler</function></funcdef>
+ <paramdef>int <parameter> *handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the program's supplied error handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Xlib generally calls the program's
+supplied error handler whenever an error is received.
+It is not called on
+<function>BadName</function>
+errors from
+<function>OpenFont</function>,
+<function>LookupColor</function>,
+or
+<function>AllocNamedColor</function>
+protocol requests or on
+<function>BadFont</function>
+errors from a
+<function>QueryFont</function>
+protocol request.
+These errors generally are reflected back to the program through the
+procedural interface.
+Because this condition is not assumed to be fatal,
+it is acceptable for your error handler to return;
+the returned value is ignored.
+However, the error handler should not
+call any functions (directly or indirectly) on the display
+that will generate protocol requests or that will look for input events.
+The previous error handler is returned.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XErrorEvent</function>
+structure contains:
+<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int type;
+ Display *display; /* Display the event was read from */
+ unsigned long serial; /* serial number of failed request */
+ unsigned char error_code; /* error code of failed request */
+ unsigned char request_code; /* Major op-code of failed request */
+ unsigned char minor_code; /* Minor op-code of failed request */
+ XID resourceid; /* resource id */
+} XErrorEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Serial Number</primary></indexterm>
+The serial member is the number of requests, starting from one,
+sent over the network connection since it was opened.
+It is the number that was the value of
+<function>NextRequest </function>
+immediately before the failing call was made.
+The request_code member is a protocol request
+of the procedure that failed, as defined in
+< X11/Xproto.h .>
+The following error codes can be returned by the functions described in this
+chapter:
+</para>
+<!-- .br -->
+<!-- .ne 13 -->
+<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>
+<!-- .\".CP T 3 -->
+<!-- .\"Error Codes -->
+<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>
+<indexterm significance="preferred"><primary>BadColor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>
+<indexterm significance="preferred"><primary>BadFont</primary></indexterm>
+<indexterm significance="preferred"><primary>BadGC</primary></indexterm>
+<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Error Code</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>BadAccess</function></entry>
+ <entry>A client attempts to grab a key/button combination already grabbed
+ by another client.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to free a colormap entry that it had not already allocated
+ or to free an entry in a colormap that was created with all entries writable.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to modify the access control list from other than the local
+ (or otherwise authorized) host.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to select an event type that another client
+ has already selected.</entry>
+ </row>
+ <row>
+ <entry><function>BadAlloc</function></entry>
+ <entry>The server fails to allocate the requested resource.
+ Note that the explicit listing of
+ <function>BadAlloc</function>
+ errors in requests only covers allocation errors at a very coarse level
+ and is not intended to (nor can it in practice hope to) cover all cases of
+ a server running out of allocation space in the middle of service.
+ The semantics when a server runs out of allocation space are left unspecified,
+ but a server may generate a
+ <function>BadAlloc</function>
+ error on any request for this reason,
+ and clients should be prepared to receive such errors and handle or discard
+ them.</entry>
+ </row>
+ <row>
+ <entry><function>BadAtom</function></entry>
+ <entry>A value for an atom argument does not name a defined atom.</entry>
+ </row>
+ <row>
+ <entry><function>BadColor</function></entry>
+ <entry>A value for a colormap argument does not name a defined colormap.</entry>
+ </row>
+ <row>
+ <entry><function>BadCursor</function></entry>
+ <entry>A value for a cursor argument does not name a defined cursor.</entry>
+ </row>
+ <row>
+ <entry><function>BadDrawable</function></entry>
+ <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
+ </row>
+ <row>
+ <entry><function>BadFont</function></entry>
+ <entry>A value for a font argument does not name a defined font (or, in some cases,
+ <function>GContext</function>).</entry>
+ </row>
+ <row>
+ <entry><function>BadGC</function></entry>
+ <entry>A value for a
+ <function>GContext </function>
+ argument does not name a defined
+ <function>GContext</function>.</entry>
+ </row>
+ <row>
+ <entry><function>BadIDChoice</function></entry>
+ <entry>The value chosen for a resource identifier either is not included in the
+ range assigned to the client or is already in use.
+ Under normal circumstances,
+ this cannot occur and should be considered a server or Xlib error.</entry>
+ </row>
+ <row>
+ <entry><function>BadImplementation</function></entry>
+ <entry>The server does not implement some aspect of the request.
+ A server that generates this error for a core request is deficient.
+ As such, this error is not listed for any of the requests,
+ but clients should be prepared to receive such errors
+ and handle or discard them.</entry>
+ </row>
+ <row>
+ <entry><function>BadLength</function></entry>
+ <entry>The length of a request is shorter or longer than that required to
+ contain the arguments.
+ This is an internal Xlib or server error.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>
+ The length of a request exceeds the maximum length accepted by the server.</entry>
+ </row>
+ <row>
+ <entry><function>BadMatch</function></entry>
+ <entry>In a graphics request,
+ the root and depth of the graphics context do not match those of the drawable.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>An <function>InputOnly </function> window is used as a drawable.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>
+ Some argument or pair of arguments has the correct type and range,
+ but it fails to match in some other way required by the request.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>An <function>InputOnly </function>
+ window lacks this attribute.</entry>
+ </row>
+ <row>
+ <entry><function>BadName</function></entry>
+ <entry>A font or color of the specified name does not exist.</entry>
+ </row>
+ <row>
+ <entry><function>BadPixmap</function></entry>
+ <entry>A value for a pixmap argument does not name a defined pixmap.</entry>
+ </row>
+ <row>
+ <entry><function>BadRequest</function></entry>
+ <entry>The major or minor opcode does not specify a valid request.
+ This usually is an Xlib or server error.</entry>
+ </row>
+ <row>
+ <entry><function>BadValue</function></entry>
+ <entry>Some numeric value falls outside of the range of values accepted
+ by the request.
+ Unless a specific range is specified for an argument,
+ the full range defined by the argument's type is accepted.
+ Any argument defined as a set of alternatives typically can generate
+ this error (due to the encoding).</entry>
+ </row>
+ <row>
+ <entry><function>BadWindow</function></entry>
+ <entry>A value for a window argument does not name a defined window.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>
+<indexterm significance="preferred"><primary>BadLength</primary></indexterm>
+<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>
+<indexterm significance="preferred"><primary>BadName</primary></indexterm>
+<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>
+<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>BadValue</primary></indexterm>
+<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>
+<!-- .NT Note -->
+
+<note>
+<para>
+The
+<function>BadAtom</function>,
+<function>BadColor</function>,
+<function>BadCursor</function>,
+<function>BadDrawable</function>,
+<function>BadFont</function>,
+<function>BadGC</function>,
+<function>BadPixmap</function>,
+and
+<function>BadWindow</function>
+errors are also used when the argument type is extended by a set of
+fixed alternatives.
+</para>
+</note>
+
+<!-- .NE -->
+<!-- .sp -->
+<para>
+<!-- .LP -->
+To obtain textual descriptions of the specified error code, use
+<function>XGetErrorText</function>.
+<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>
+<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetErrorText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> code</parameter></paramdef>
+ <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>code</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the error code for which you want to obtain a description.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the error description.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorText</function>
+function copies a null-terminated string describing the specified error code
+into the specified buffer.
+The returned text is in the encoding of the current locale.
+It is recommended that you use this function to obtain an error description
+because extensions to Xlib may define their own error codes
+and error strings.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain error messages from the error database, use
+<function>XGetErrorDatabaseText</function>.
+<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetErrorDatabaseText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char*name,<parameter> *message</parameter></paramdef>
+ <paramdef>char<parameter> *default_string</parameter></paramdef>
+ <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default error message if none is found in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the error description.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorDatabaseText</function>
+function returns a null-terminated message
+(or the default message) from the error message
+database.
+Xlib uses this function internally to look up its error messages.
+The text in the default_string argument is assumed
+to be in the encoding of the current locale,
+and the text stored in the buffer_return argument
+is in the encoding of the current locale.
+</para>
+<para>
+<!-- .LP -->
+The name argument should generally be the name of your application.
+The message argument should indicate which type of error message you want.
+If the name and message are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Xlib uses three predefined ``application names'' to report errors.
+In these names,
+uppercase and lowercase matter.
+<variablelist>
+ <varlistentry>
+ <term>
+ XProtoError
+ </term>
+ <listitem>
+ <para>
+The protocol error number is used as a string for the message argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ XlibMessage
+ </term>
+ <listitem>
+ <para>
+These are the message strings that are used internally by the library.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ XRequest
+ </term>
+ <listitem>
+ <para>
+For a core protocol request,
+the major request protocol number is used for the message argument.
+For an extension request,
+the extension name (as given by
+<function>InitExtension</function>)
+followed by a period (\.) and the minor request protocol number
+is used for the message argument.
+If no string is found in the error database,
+the default_string is returned to the buffer argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To report an error to the user when the requested display does not exist, use
+<function>XDisplayName</function>.
+<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XDisplayName</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayName</function>
+function returns the name of the display that
+<function>XOpenDisplay</function>
+would attempt to use.
+If a NULL string is specified,
+<function>XDisplayName</function>
+looks in the environment for the display and returns the display name that
+<function>XOpenDisplay</function>
+would attempt to use.
+This makes it easier to report to the user precisely which display the
+program attempted to open when the initial connection attempt failed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To handle fatal I/O errors, use
+<function>XSetIOErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> int</function></funcdef>
+ <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the program's supplied error handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIOErrorHandler</function>
+sets the fatal I/O error handler.
+Xlib calls the program's supplied error handler if any sort of system call
+error occurs (for example, the connection to the server was lost).
+This is assumed to be a fatal condition,
+and the called routine should not return.
+If the I/O error handler does return,
+the client process exits.
+</para>
+<para>
+<!-- .LP -->
+Note that the previous error handler is returned.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH12 b/libX11/specs/libX11/CH12 deleted file mode 100644 index 08b9ba93a..000000000 --- a/libX11/specs/libX11/CH12 +++ /dev/null @@ -1,2680 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 12\fP\s-1 - -\s+1\fBInput Device Functions\fP\s-1 -.sp 2 -.nr H1 12 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 12: Input Device Functions -.XE -You can use the Xlib input device functions to: -.IP \(bu 5 -Grab the pointer and individual buttons on the pointer -.IP \(bu 5 -Grab the keyboard and individual keys on the keyboard -.IP \(bu 5 -Resume event processing -.IP \(bu 5 -Move the pointer -.IP \(bu 5 -Set the input focus -.IP \(bu 5 -Manipulate the keyboard and pointer settings -.IP \(bu 5 -Manipulate the keyboard encoding -.NH 2 -Pointer Grabbing -.XS -\*(SN Pointer Grabbing -.XE -.LP -Xlib provides functions that you can use to control input from the pointer, -which usually is a mouse. -Usually, as soon as keyboard and mouse events occur, -the X server delivers them to the appropriate client, -which is determined by the window and input focus. -The X server provides sufficient control over event delivery to -allow window managers to support mouse ahead and various other -styles of user interface. -Many of these user interfaces depend on synchronous delivery of events. -The delivery of pointer and keyboard events can be controlled -independently. -.LP -When mouse buttons or keyboard keys are grabbed, events -will be sent to the grabbing client rather than the normal -client who would have received the event. -If the keyboard or pointer is in asynchronous mode, -further mouse and keyboard events will continue to be processed. -If the keyboard or pointer is in synchronous mode, no -further events are processed until the grabbing client -allows them (see -.PN XAllowEvents ). -The keyboard or pointer is considered frozen during this -interval. -The event that triggered the grab can also be replayed. -.LP -Note that the logical state of a device (as seen by client applications) -may lag the physical state if device event processing is frozen. -.LP -.IN "Active grab" "" "@DEF@" -There are two kinds of grabs: -active and passive. -An active grab occurs when a single client grabs the keyboard and/or pointer -explicitly (see -.PN XGrabPointer -and -.PN XGrabKeyboard ). -.IN "Passive grab" -A passive grab occurs when clients grab a particular keyboard key -or pointer button in a window, -and the grab will activate when the key or button is actually pressed. -Passive grabs are convenient for implementing reliable pop-up menus. -For example, you can guarantee that the pop-up is mapped -before the up pointer button event occurs by -grabbing a button requesting synchronous behavior. -The down event will trigger the grab and freeze further -processing of pointer events until you have the chance to -map the pop-up window. -You can then allow further event processing. -The up event will then be correctly processed relative to the -pop-up window. -.LP -For many operations, -there are functions that take a time argument. -The X server includes a timestamp in various events. -One special time, called -.IN "CurrentTime" "" "@DEF@" -.IN "Time" "" "@DEF@" -.PN CurrentTime , -represents the current server time. -The X server maintains the time when the input focus was last changed, -when the keyboard was last grabbed, -when the pointer was last grabbed, -or when a selection was last changed. -Your -application may be slow reacting to an event. -You often need some way to specify that your -request should not occur if another application has in the meanwhile -taken control of the keyboard, pointer, or selection. -By providing the timestamp from the event in the request, -you can arrange that the operation not take effect -if someone else has performed an operation in the meanwhile. -.LP -A timestamp is a time value, expressed in milliseconds. -It typically is the time since the last server reset. -Timestamp values wrap around (after about 49.7 days). -The server, given its current time is represented by timestamp T, -always interprets timestamps from clients by treating half of the timestamp -space as being later in time than T. -One timestamp value, named -.PN CurrentTime , -is never generated by the server. -This value is reserved for use in requests to represent the current server time. -.LP -For many functions in this section, -you pass pointer event mask bits. -The valid pointer event mask bits are: -.PN ButtonPressMask , -.PN ButtonReleaseMask , -.PN EnterWindowMask , -.PN LeaveWindowMask , -.PN PointerMotionMask , -.PN PointerMotionHintMask , -.PN Button1MotionMask , -.PN Button2MotionMask , -.PN Button3MotionMask , -.PN Button4MotionMask , -.PN Button5MotionMask , -.PN ButtonMotionMask , -and -.PN KeyMapStateMask . -For other functions in this section, -you pass keymask bits. -The valid keymask bits are: -.PN ShiftMask , -.PN LockMask , -.PN ControlMask , -.PN Mod1Mask , -.PN Mod2Mask , -.PN Mod3Mask , -.PN Mod4Mask , -and -.PN Mod5Mask . -.LP -.sp -To grab the pointer, use -.PN XGrabPointer . -.IN "Grabbing" "pointer" -.IN "Pointer" "grabbing" -.IN "XGrabPointer" "" "@DEF@" -.sM -.FD 0 -int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^, - \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIgrab_window\fP\^; -.br - Bool \fIowner_events\fP\^; -.br - unsigned int \fIevent_mask\fP\^; -.br - int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; -.br - Window \fIconfine_to\fP\^; -.br - Cursor \fIcursor\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgrab_window\fP 1i -Specifies the grab window. -.IP \fIowner_events\fP 1i -Specifies a Boolean value that indicates whether the pointer -events are to be reported as usual or reported with respect to the grab window -if selected by the event mask. -.IP \fIevent_mask\fP 1i -Specifies which pointer events are reported to the client. -The mask is the bitwise inclusive OR of the valid pointer event mask bits. -.IP \fIpointer_mode\fP 1i -Specifies further processing of pointer events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fIkeyboard_mode\fP 1i -Specifies further processing of keyboard events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fIconfine_to\fP 1i -Specifies the window to confine the pointer in or -.PN None . -.IP \fIcursor\fP 1i -Specifies the cursor that is to be displayed during the grab or -.PN None . -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XGrabPointer -function actively grabs control of the pointer and returns -.PN GrabSuccess -if the grab was successful. -Further pointer events are reported only to the grabbing client. -.PN XGrabPointer -overrides any active pointer grab by this client. -If owner_events is -.PN False , -all generated pointer events -are reported with respect to grab_window and are reported only if -selected by event_mask. -If owner_events is -.PN True -and if a generated -pointer event would normally be reported to this client, -it is reported as usual. -Otherwise, the event is reported with respect to the -grab_window and is reported only if selected by event_mask. -For either value of owner_events, unreported events are discarded. -.LP -If the pointer_mode is -.PN GrabModeAsync , -pointer event processing continues as usual. -If the pointer is currently frozen by this client, -the processing of events for the pointer is resumed. -If the pointer_mode is -.PN GrabModeSync , -the state of the pointer, as seen by -client applications, -appears to freeze, and the X server generates no further pointer events -until the grabbing client calls -.PN XAllowEvents -or until the pointer grab is released. -Actual pointer changes are not lost while the pointer is frozen; -they are simply queued in the server for later processing. -.LP -If the keyboard_mode is -.PN GrabModeAsync , -keyboard event processing is unaffected by activation of the grab. -If the keyboard_mode is -.PN GrabModeSync , -the state of the keyboard, as seen by -client applications, -appears to freeze, and the X server generates no further keyboard events -until the grabbing client calls -.PN XAllowEvents -or until the pointer grab is released. -Actual keyboard changes are not lost while the pointer is frozen; -they are simply queued in the server for later processing. -.LP -If a cursor is specified, it is displayed regardless of what -window the pointer is in. -If -.PN None -is specified, -the normal cursor for that window is displayed -when the pointer is in grab_window or one of its subwindows; -otherwise, the cursor for grab_window is displayed. -.LP -If a confine_to window is specified, -the pointer is restricted to stay contained in that window. -The confine_to window need have no relationship to the grab_window. -If the pointer is not initially in the confine_to window, -it is warped automatically to the closest edge -just before the grab activates and enter/leave events are generated as usual. -If the confine_to window is subsequently reconfigured, -the pointer is warped automatically, as necessary, -to keep it contained in the window. -.LP -The time argument allows you to avoid certain circumstances that come up -if applications take a long time to respond or if there are long network -delays. -Consider a situation where you have two applications, both -of which normally grab the pointer when clicked on. -If both applications specify the timestamp from the event, -the second application may wake up faster and successfully grab the pointer -before the first application. -The first application then will get an indication that the other application -grabbed the pointer before its request was processed. -.LP -.PN XGrabPointer -generates -.PN EnterNotify -and -.PN LeaveNotify -events. -.LP -Either if grab_window or confine_to window is not viewable -or if the confine_to window lies completely outside the boundaries of the root -window, -.PN XGrabPointer -fails and returns -.PN GrabNotViewable . -If the pointer is actively grabbed by some other client, -it fails and returns -.PN AlreadyGrabbed . -If the pointer is frozen by an active grab of another client, -it fails and returns -.PN GrabFrozen . -If the specified time is earlier than the last-pointer-grab time or later -than the current X server time, it fails and returns -.PN GrabInvalidTime . -Otherwise, the last-pointer-grab time is set to the specified time -.Pn ( CurrentTime -is replaced by the current X server time). -.LP -.PN XGrabPointer -can generate -.PN BadCursor , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To ungrab the pointer, use -.PN XUngrabPointer . -.IN "Ungrabbing" "pointer" -.IN "Pointer" "ungrabbing" -.IN "XUngrabPointer" "" "@DEF@" -.sM -.FD 0 -XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XUngrabPointer -function releases the pointer and any queued events -if this client has actively grabbed the pointer from -.PN XGrabPointer , -.PN XGrabButton , -or from a normal button press. -.PN XUngrabPointer -does not release the pointer if the specified -time is earlier than the last-pointer-grab time or is later than the -current X server time. -It also generates -.PN EnterNotify -and -.PN LeaveNotify -events. -The X server performs an -.PN UngrabPointer -request automatically if the event window or confine_to window -for an active pointer grab becomes not viewable -or if window reconfiguration causes the confine_to window to lie completely -outside the boundaries of the root window. -.LP -.sp -To change an active pointer grab, use -.PN XChangeActivePointerGrab . -.IN "Pointer" "grabbing" -.IN "Changing" "pointer grab" -.IN "XChangeActivePointerGrab" "" "@DEF@" -.sM -.FD 0 -XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned int \fIevent_mask\fP\^; -.br - Cursor \fIcursor\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_mask\fP 1i -Specifies which pointer events are reported to the client. -The mask is the bitwise inclusive OR of the valid pointer event mask bits. -.IP \fIcursor\fP 1i -Specifies the cursor that is to be displayed or -.PN None . -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XChangeActivePointerGrab -function changes the specified dynamic parameters if the pointer is actively -grabbed by the client and if the specified time is no earlier than the -last-pointer-grab time and no later than the current X server time. -This function has no effect on the passive parameters of an -.PN XGrabButton . -The interpretation of event_mask and cursor is the same as described in -.PN XGrabPointer . -.LP -.PN XChangeActivePointerGrab -can generate -.PN BadCursor -and -.PN BadValue -errors. -.LP -.sp -To grab a pointer button, use -.PN XGrabButton . -.IN "Grabbing" "buttons" -.IN "Button" "grabbing" -.IN "XGrabButton" "" "@DEF@" -.sM -.FD 0 -XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, -.br - \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned int \fIbutton\fP\^; -.br - unsigned int \fImodifiers\fP\^; -.br - Window \fIgrab_window\fP\^; -.br - Bool \fIowner_events\fP\^; -.br - unsigned int \fIevent_mask\fP\^; -.br - int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; -.br - Window \fIconfine_to\fP\^; -.br - Cursor \fIcursor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Bu grabbed -.IP \fIbutton\fP 1i -Specifies the pointer button that is to be \*(Bu or -.PN AnyButton . -.IP \fImodifiers\fP 1i -Specifies the set of keymasks or -.PN AnyModifier . -The mask is the bitwise inclusive OR of the valid keymask bits. -.IP \fIgrab_window\fP 1i -Specifies the grab window. -.IP \fIowner_events\fP 1i -Specifies a Boolean value that indicates whether the pointer -events are to be reported as usual or reported with respect to the grab window -if selected by the event mask. -.IP \fIevent_mask\fP 1i -Specifies which pointer events are reported to the client. -The mask is the bitwise inclusive OR of the valid pointer event mask bits. -.IP \fIpointer_mode\fP 1i -Specifies further processing of pointer events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fIkeyboard_mode\fP 1i -Specifies further processing of keyboard events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fIconfine_to\fP 1i -Specifies the window to confine the pointer in or -.PN None . -.IP \fIcursor\fP 1i -Specifies the cursor that is to be displayed or -.PN None . -.LP -.eM -The -.PN XGrabButton -function establishes a passive grab. -In the future, -the pointer is actively grabbed (as for -.PN XGrabPointer ), -the last-pointer-grab time is set to the time at which the button was pressed -(as transmitted in the -.PN ButtonPress -event), and the -.PN ButtonPress -event is reported if all of the following conditions are true: -.IP \(bu 5 -The pointer is not grabbed, and the specified button is logically pressed -when the specified modifier keys are logically down, -and no other buttons or modifier keys are logically down. -.IP \(bu 5 -The grab_window contains the pointer. -.IP \(bu 5 -The confine_to window (if any) is viewable. -.IP \(bu 5 -A passive grab on the same button/key combination does not exist -on any ancestor of grab_window. -.LP -The interpretation of the remaining arguments is as for -.PN XGrabPointer . -The active grab is terminated automatically when the logical state of the -pointer has all buttons released -(independent of the state of the logical modifier keys). -.LP -Note that the logical state of a device (as seen by client applications) -may lag the physical state if device event processing is frozen. -.LP -This request overrides all previous grabs by the same client on the same -button/key combinations on the same window. -A modifiers of -.PN AnyModifier -is equivalent to issuing the grab request for all -possible modifier combinations (including the combination of no modifiers). -It is not required that all modifiers specified have currently assigned -KeyCodes. -A button of -.PN AnyButton -is equivalent to -issuing the request for all possible buttons. -Otherwise, it is not required that the specified button currently be assigned -to a physical button. -.LP -If some other client has already issued an -.PN XGrabButton -with the same button/key combination on the same window, a -.PN BadAccess -error results. -When using -.PN AnyModifier -or -.PN AnyButton , -the request fails completely, -and a -.PN BadAccess -error results (no grabs are -established) if there is a conflicting grab for any combination. -.PN XGrabButton -has no effect on an active grab. -.LP -.PN XGrabButton -can generate -.PN BadCursor , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To ungrab a pointer button, use -.PN XUngrabButton . -.IN "Ungrabbing" "buttons" -.IN "Button" "ungrabbing" -.IN "XUngrabButton" "" "@DEF@" -.sM -.FD 0 -XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned int \fIbutton\fP\^; -.br - unsigned int \fImodifiers\fP\^; -.br - Window \fIgrab_window\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Bu released -.IP \fIbutton\fP 1i -Specifies the pointer button that is to be \*(Bu or -.PN AnyButton . -.IP \fImodifiers\fP 1i -Specifies the set of keymasks or -.PN AnyModifier . -The mask is the bitwise inclusive OR of the valid keymask bits. -.IP \fIgrab_window\fP 1i -Specifies the grab window. -.LP -.eM -The -.PN XUngrabButton -function releases the passive button/key combination on the specified window if -it was grabbed by this client. -A modifiers of -.PN AnyModifier -is -equivalent to issuing -the ungrab request for all possible modifier combinations, including -the combination of no modifiers. -A button of -.PN AnyButton -is equivalent to issuing the -request for all possible buttons. -.PN XUngrabButton -has no effect on an active grab. -.LP -.PN XUngrabButton -can generate -.PN BadValue -and -.PN BadWindow -errors. -.NH 2 -Keyboard Grabbing -.XS -\*(SN Keyboard Grabbing -.XE -.LP -Xlib provides functions that you can use to grab or ungrab the keyboard -as well as allow events. -.LP -For many functions in this section, -you pass keymask bits. -The valid keymask bits are: -.PN ShiftMask , -.PN LockMask , -.PN ControlMask , -.PN Mod1Mask , -.PN Mod2Mask , -.PN Mod3Mask , -.PN Mod4Mask , -and -.PN Mod5Mask . -.LP -.sp -To grab the keyboard, use -.PN XGrabKeyboard . -.IN "Keyboard" "grabbing" -.IN "Grabbing" "keyboard" -.IN "XGrabKeyboard" "" "@DEF@" -.sM -.FD 0 -int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIgrab_window\fP\^; -.br - Bool \fIowner_events\fP\^; -.br - int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgrab_window\fP 1i -Specifies the grab window. -.IP \fIowner_events\fP 1i -Specifies a Boolean value that indicates whether the keyboard events -are to be reported as usual. -.IP \fIpointer_mode\fP 1i -Specifies further processing of pointer events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fIkeyboard_mode\fP 1i -Specifies further processing of keyboard events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XGrabKeyboard -function actively grabs control of the keyboard and generates -.PN FocusIn -and -.PN FocusOut -events. -Further key events are reported only to the -grabbing client. -.PN XGrabKeyboard -overrides any active keyboard grab by this client. -If owner_events is -.PN False , -all generated key events are reported with -respect to grab_window. -If owner_events is -.PN True -and if a generated -key event would normally be reported to this client, it is reported -normally; otherwise, the event is reported with respect to the -grab_window. -Both -.PN KeyPress -and -.PN KeyRelease -events are always reported, -independent of any event selection made by the client. -.LP -If the keyboard_mode argument is -.PN GrabModeAsync , -keyboard event processing continues -as usual. -If the keyboard is currently frozen by this client, -then processing of keyboard events is resumed. -If the keyboard_mode argument is -.PN GrabModeSync , -the state of the keyboard (as seen by client applications) appears to freeze, -and the X server generates no further keyboard events until the -grabbing client issues a releasing -.PN XAllowEvents -call or until the keyboard grab is released. -Actual keyboard changes are not lost while the keyboard is frozen; -they are simply queued in the server for later processing. -.LP -If pointer_mode is -.PN GrabModeAsync , -pointer event processing is unaffected -by activation of the grab. -If pointer_mode is -.PN GrabModeSync , -the state of the pointer (as seen by client applications) appears to freeze, -and the X server generates no further pointer events -until the grabbing client issues a releasing -.PN XAllowEvents -call or until the keyboard grab is released. -Actual pointer changes are not lost while the pointer is frozen; -they are simply queued in the server for later processing. -.LP -If the keyboard is actively grabbed by some other client, -.PN XGrabKeyboard -fails and returns -.PN AlreadyGrabbed . -If grab_window is not viewable, -it fails and returns -.PN GrabNotViewable . -If the keyboard is frozen by an active grab of another client, -it fails and returns -.PN GrabFrozen . -If the specified time is earlier than the last-keyboard-grab time -or later than the current X server time, -it fails and returns -.PN GrabInvalidTime . -Otherwise, the last-keyboard-grab time is set to the specified time -.Pn ( CurrentTime -is replaced by the current X server time). -.LP -.PN XGrabKeyboard -can generate -.PN BadValue -and -.PN BadWindow -errors. -.LP -.sp -To ungrab the keyboard, use -.PN XUngrabKeyboard . -.IN "Keyboard" "ungrabbing" -.IN "Ungrabbing" "keyboard" -.IN "XUngrabKeyboard" "" "@DEF@" -.sM -.FD 0 -XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XUngrabKeyboard -function -releases the keyboard and any queued events if this client has it actively grabbed from -either -.PN XGrabKeyboard -or -.PN XGrabKey . -.PN XUngrabKeyboard -does not release the keyboard and any queued events -if the specified time is earlier than -the last-keyboard-grab time or is later than the current X server time. -It also generates -.PN FocusIn -and -.PN FocusOut -events. -The X server automatically performs an -.PN UngrabKeyboard -request if the event window for an -active keyboard grab becomes not viewable. -.LP -.sp -To passively grab a single key of the keyboard, use -.PN XGrabKey . -.IN "Key" "grabbing" -.IN "Grabbing" "keys" -.IN "XGrabKey" "" "@DEF@" -.sM -.FD 0 -XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, -.br - \fIkeyboard_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIkeycode\fP\^; -.br - unsigned int \fImodifiers\fP\^; -.br - Window \fIgrab_window\fP\^; -.br - Bool \fIowner_events\fP\^; -.br - int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIkeycode\fP 1i -Specifies the KeyCode or -.PN AnyKey . -.IP \fImodifiers\fP 1i -Specifies the set of keymasks or -.PN AnyModifier . -The mask is the bitwise inclusive OR of the valid keymask bits. -.IP \fIgrab_window\fP 1i -Specifies the grab window. -.IP \fIowner_events\fP 1i -Specifies a Boolean value that indicates whether the keyboard events -are to be reported as usual. -.IP \fIpointer_mode\fP 1i -Specifies further processing of pointer events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.IP \fIkeyboard_mode\fP 1i -Specifies further processing of keyboard events. -You can pass -.PN GrabModeSync -or -.PN GrabModeAsync . -.LP -.eM -The -.PN XGrabKey -function establishes a passive grab on the keyboard. -In the future, -the keyboard is actively grabbed (as for -.PN XGrabKeyboard ), -the last-keyboard-grab time is set to the time at which the key was pressed -(as transmitted in the -.PN KeyPress -event), and the -.PN KeyPress -event is reported if all of the following conditions are true: -.IP \(bu 5 -The keyboard is not grabbed and the specified key -(which can itself be a modifier key) is logically pressed -when the specified modifier keys are logically down, -and no other modifier keys are logically down. -.IP \(bu 5 -Either the grab_window is an ancestor of (or is) the focus window, -or the grab_window is a descendant of the focus window and contains the pointer. -.IP \(bu 5 -A passive grab on the same key combination does not exist -on any ancestor of grab_window. -.LP -The interpretation of the remaining arguments is as for -.PN XGrabKeyboard . -The active grab is terminated automatically when the logical state of the -keyboard has the specified key released -(independent of the logical state of the modifier keys). -.LP -Note that the logical state of a device (as seen by client applications) -may lag the physical state if device event processing is frozen. -.LP -A modifiers argument of -.PN AnyModifier -is equivalent to issuing the request for all -possible modifier combinations (including the combination of no -modifiers). -It is not required that all modifiers specified have -currently assigned KeyCodes. -A keycode argument of -.PN AnyKey -is equivalent to issuing -the request for all possible KeyCodes. -Otherwise, the specified keycode must be in -the range specified by min_keycode and max_keycode in the connection -setup, -or a -.PN BadValue -error results. -.LP -If some other client has issued a -.PN XGrabKey -with the same key combination on the same window, a -.PN BadAccess -error results. -When using -.PN AnyModifier -or -.PN AnyKey , -the request fails completely, -and a -.PN BadAccess -error results (no grabs are established) -if there is a conflicting grab for any combination. -.LP -.PN XGrabKey -can generate -.PN BadAccess , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To ungrab a key, use -.PN XUngrabKey . -.IN "Key" "ungrabbing" -.IN "Ungrabbing" "keys" -.IN "XUngrabKey" "" "@DEF@" -.sM -.FD 0 -XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIkeycode\fP\^; -.br - unsigned int \fImodifiers\fP\^; -.br - Window \fIgrab_window\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIkeycode\fP 1i -Specifies the KeyCode or -.PN AnyKey . -.IP \fImodifiers\fP 1i -Specifies the set of keymasks or -.PN AnyModifier . -The mask is the bitwise inclusive OR of the valid keymask bits. -.IP \fIgrab_window\fP 1i -Specifies the grab window. -.LP -.eM -The -.PN XUngrabKey -function releases the key combination on the specified window if it was grabbed -by this client. -It has no effect on an active grab. -A modifiers of -.PN AnyModifier -is equivalent to issuing -the request for all possible modifier combinations -(including the combination of no modifiers). -A keycode argument of -.PN AnyKey -is equivalent to issuing the request for all possible key codes. -.LP -.PN XUngrabKey -can generate -.PN BadValue -and -.PN BadWindow -errors. -.NH 2 -Resuming Event Processing -.XS -\*(SN Resuming Event Processing -.XE -.LP -The previous sections discussed grab mechanisms with which processing -of events by the server can be temporarily suspended. This section -describes the mechanism for resuming event processing. -.LP -.sp -To allow further events to be processed when the device has been frozen, use -.PN XAllowEvents . -.IN "XAllowEvents" "" "@DEF@" -.sM -.FD 0 -XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIevent_mode\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_mode\fP 1i -Specifies the event mode. -You can pass -.PN AsyncPointer , -.PN SyncPointer , -.PN AsyncKeyboard , -.PN SyncKeyboard , -.PN ReplayPointer , -.PN ReplayKeyboard , -.PN AsyncBoth , -or -.PN SyncBoth . -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XAllowEvents -function releases some queued events if the client has caused a device -to freeze. -It has no effect if the specified time is earlier than the last-grab -time of the most recent active grab for the client or if the specified time -is later than the current X server time. -Depending on the event_mode argument, the following occurs: -.TS -lw(1.25i) lw(4.5i). -T{ -.PN AsyncPointer -T} T{ -If the pointer is frozen by the client, -pointer event processing continues as usual. -If the pointer is frozen twice by the client on behalf of two separate grabs, -.PN AsyncPointer -thaws for both. -.PN AsyncPointer -has no effect if the pointer is not frozen by the client, -but the pointer need not be grabbed by the client. -T} -.sp 6p -T{ -.PN SyncPointer -T} T{ -If the pointer is frozen and actively grabbed by the client, -pointer event processing continues as usual until the next -.PN ButtonPress -or -.PN ButtonRelease -event is reported to the client. -At this time, -the pointer again appears to freeze. -However, if the reported event causes the pointer grab to be released, -the pointer does not freeze. -.PN SyncPointer -has no effect if the pointer is not frozen by the client -or if the pointer is not grabbed by the client. -T} -.sp 6p -T{ -.PN ReplayPointer -T} T{ -If the pointer is actively grabbed by the client and is frozen as the result of -an event having been sent to the client (either from the activation of an -.PN XGrabButton -or from a previous -.PN XAllowEvents -with mode -.PN SyncPointer -but not from an -.PN XGrabPointer ), -the pointer grab is released and that event is completely reprocessed. -This time, however, the function ignores any passive grabs at or above -(toward the root of) the grab_window of the grab just released. -The request has no effect if the pointer is not grabbed by the client -or if the pointer is not frozen as the result of an event. -T} -.sp 6p -T{ -.PN AsyncKeyboard -T} T{ -If the keyboard is frozen by the client, -keyboard event processing continues as usual. -If the keyboard is frozen twice by the client on behalf of two separate grabs, -.PN AsyncKeyboard -thaws for both. -.PN AsyncKeyboard -has no effect if the keyboard is not frozen by the client, -but the keyboard need not be grabbed by the client. -T} -.sp 6p -T{ -.PN SyncKeyboard -T} T{ -If the keyboard is frozen and actively grabbed by the client, -keyboard event processing continues as usual until the next -.PN KeyPress -or -.PN KeyRelease -event is reported to the client. -At this time, -the keyboard again appears to freeze. -However, if the reported event causes the keyboard grab to be released, -the keyboard does not freeze. -.PN SyncKeyboard -has no effect if the keyboard is not frozen by the client -or if the keyboard is not grabbed by the client. -T} -.sp 6p -T{ -.PN ReplayKeyboard -T} T{ -If the keyboard is actively grabbed by the client and is frozen -as the result of an event having been sent to the client (either from the -activation of an -.PN XGrabKey -or from a previous -.PN XAllowEvents -with mode -.PN SyncKeyboard -but not from an -.PN XGrabKeyboard ), -the keyboard grab is released and that event is completely reprocessed. -This time, however, the function ignores any passive grabs at or above -(toward the root of) -the grab_window of the grab just released. -The request has no effect if the keyboard is not grabbed by the client -or if the keyboard is not frozen as the result of an event. -T} -.sp 6p -T{ -.PN SyncBoth -T} T{ -If both pointer and keyboard are frozen by the client, -event processing for both devices continues as usual until the next -.PN ButtonPress , -.PN ButtonRelease , -.PN KeyPress , -or -.PN KeyRelease -event is reported to the client for a grabbed device -(button event for the pointer, key event for the keyboard), -at which time the devices again appear to freeze. -However, if the reported event causes the grab to be released, -then the devices do not freeze (but if the other device is still -grabbed, then a subsequent event for it will still cause both devices -to freeze). -.PN SyncBoth -has no effect unless both pointer and keyboard -are frozen by the client. -If the pointer or keyboard is frozen twice -by the client on behalf of two separate grabs, -.PN SyncBoth -thaws for both (but a subsequent freeze for -.PN SyncBoth -will only freeze each device once). -T} -.sp 6p -T{ -.PN AsyncBoth -T} T{ -If the pointer and the keyboard are frozen by the -client, event processing for both devices continues as usual. -If a device is frozen twice by the client on behalf of two separate grabs, -.PN AsyncBoth -thaws for both. -.PN AsyncBoth -has no effect unless both -pointer and keyboard are frozen by the client. -T} -.TE -.LP -.PN AsyncPointer , -.PN SyncPointer , -and -.PN ReplayPointer -have no effect on the -processing of keyboard events. -.PN AsyncKeyboard , -.PN SyncKeyboard , -and -.PN ReplayKeyboard -have no effect on the -processing of pointer events. -It is possible for both a pointer grab and a keyboard grab (by the same -or different clients) to be active simultaneously. -If a device is frozen on behalf of either grab, -no event processing is performed for the device. -It is possible for a single device to be frozen because of both grabs. -In this case, -the freeze must be released on behalf of both grabs before events can -again be processed. -If a device is frozen twice by a single client, -then a single -.PN AllowEvents -releases both. -.LP -.PN XAllowEvents -can generate a -.PN BadValue -error. -.NH 2 -Moving the Pointer -.XS -\*(SN Moving the Pointer -.XE -.LP -Although movement of the pointer normally should be left to the -control of the end user, sometimes it is necessary to move the -pointer to a new position under program control. -.LP -.sp -To move the pointer to an arbitrary point in a window, use -.PN XWarpPointer . -.IN "XWarpPointer" "" "@DEF@" -.sM -.FD 0 -XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^, -.br - \fIdest_y\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIsrc_w\fP\^, \fIdest_w\fP\^; -.br - int \fIsrc_x\fP\^, \fIsrc_y\fP\^; -.br - unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^; -.br - int \fIdest_x\fP\^, \fIdest_y\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsrc_w\fP 1i -Specifies the source window or -.PN None . -.IP \fIdest_w\fP 1i -Specifies the destination window or -.PN None . -.IP \fIsrc_x\fP 1i -.br -.ns -.IP \fIsrc_y\fP 1i -.br -.ns -.IP \fIsrc_width\fP 1i -.br -.ns -.IP \fIsrc_height\fP 1i -Specify a rectangle in the source window. -.IP \fIdest_x\fP 1i -.br -.ns -.IP \fIdest_y\fP 1i -Specify the x and y coordinates within the destination window. -.LP -.eM -If dest_w is -.PN None , -.PN XWarpPointer -moves the pointer by the offsets (dest_x, dest_y) relative to the current -position of the pointer. -If dest_w is a window, -.PN XWarpPointer -moves the pointer to the offsets (dest_x, dest_y) relative to the origin of -dest_w. -However, if src_w is a window, -the move only takes place if the window src_w contains the pointer -and if the specified rectangle of src_w contains the pointer. -.LP -The src_x and src_y coordinates are relative to the origin of src_w. -If src_height is zero, -it is replaced with the current height of src_w minus src_y. -If src_width is zero, -it is replaced with the current width of src_w minus src_x. -.LP -There is seldom any reason for calling this function. -The pointer should normally be left to the user. -If you do use this function, however, it generates events just as if the user -had instantaneously moved the pointer from one position to another. -Note that you cannot use -.PN XWarpPointer -to move the pointer outside the confine_to window of an active pointer grab. -An attempt to do so will only move the pointer as far as the closest edge of the -confine_to window. -.LP -.PN XWarpPointer -can generate a -.PN BadWindow -error. -.NH 2 -Controlling Input Focus -.XS -\*(SN Controlling Input Focus -.XE -.LP -Xlib provides functions that you can use to set and get the input focus. -The input focus is a shared resource, and cooperation among clients is -required for correct interaction. See the -\fIInter-Client Communication Conventions Manual\fP -for input focus policy. -.LP -.sp -To set the input focus, use -.PN XSetInputFocus . -.IN "XSetInputFocus" "" "@DEF@" -.sM -.FD 0 -XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIfocus\fP\^; -.br - int \fIrevert_to\fP\^; -.br - Time \fItime\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfocus\fP 1i -Specifies the window, -.PN PointerRoot , -or -.PN None . -.IP \fIrevert_to\fP 1i -Specifies where the input focus reverts to if the window becomes not -viewable. -You can pass -.PN RevertToParent , -.PN RevertToPointerRoot , -or -.PN RevertToNone . -.IP \fItime\fP 1i -Specifies the time. -You can pass either a timestamp or -.PN CurrentTime . -.LP -.eM -The -.PN XSetInputFocus -function changes the input focus and the last-focus-change time. -It has no effect if the specified time is earlier than the current -last-focus-change time or is later than the current X server time. -Otherwise, the last-focus-change time is set to the specified time -.Pn ( CurrentTime -is replaced by the current X server time). -.PN XSetInputFocus -causes the X server to generate -.PN FocusIn -and -.PN FocusOut -events. -.LP -Depending on the focus argument, -the following occurs: -.IP \(bu 5 -If focus is -.PN None , -all keyboard events are discarded until a new focus window is set, -and the revert_to argument is ignored. -.IP \(bu 5 -If focus is a window, -it becomes the keyboard's focus window. -If a generated keyboard event would normally be reported to this window -or one of its inferiors, the event is reported as usual. -Otherwise, the event is reported relative to the focus window. -.IP \(bu 5 -If focus is -.PN PointerRoot , -the focus window is dynamically taken to be the root window of whatever screen -the pointer is on at each keyboard event. -In this case, the revert_to argument is ignored. -.LP -The specified focus window must be viewable at the time -.PN XSetInputFocus -is called, -or a -.PN BadMatch -error results. -If the focus window later becomes not viewable, -the X server -evaluates the revert_to argument to determine the new focus window as follows: -.IP \(bu 5 -If revert_to is -.PN RevertToParent , -the focus reverts to the parent (or the closest viewable ancestor), -and the new revert_to value is taken to be -.PN RevertToNone . -.IP \(bu 5 -If revert_to is -.PN RevertToPointerRoot -or -.PN RevertToNone , -the focus reverts to -.PN PointerRoot -or -.PN None , -respectively. -When the focus reverts, -the X server generates -.PN FocusIn -and -.PN FocusOut -events, but the last-focus-change time is not affected. -.LP -.PN XSetInputFocus -can generate -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To obtain the current input focus, use -.PN XGetInputFocus . -.IN "XGetInputFocus" "" "@DEF@" -.sM -.FD 0 -XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window *\fIfocus_return\fP\^; -.br - int *\fIrevert_to_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfocus_return\fP 1i -Returns the focus window, -.PN PointerRoot , -or -.PN None . -.IP \fIrevert_to_return\fP 1i -Returns the current focus state -.Pn ( RevertToParent , -.PN RevertToPointerRoot , -or -.PN RevertToNone ). -.LP -.eM -The -.PN XGetInputFocus -function returns the focus window and the current focus state. -.NH 2 -Manipulating the Keyboard and Pointer Settings -.XS -\*(SN Manipulating the Keyboard and Pointer Settings -.XE -.LP -Xlib provides functions that you can use to -change the keyboard control, obtain a list of the auto-repeat keys, -turn keyboard auto-repeat on or off, ring the bell, -set or obtain the pointer button or keyboard mapping, -and obtain a bit vector for the keyboard. -.LP -.IN "Keyboard" "bell volume" -.IN "Keyboard" "keyclick volume" -.IN "Keyboard" "bit vector" -.IN "Mouse" "programming" -This section discusses -the user-preference options of bell, key click, -pointer behavior, and so on. -The default values for many of these options are server dependent. -Not all implementations will actually be able to control all of these -parameters. -.LP -The -.PN XChangeKeyboardControl -function changes control of a keyboard and operates on a -.PN XKeyboardControl -structure: -.sM -.LP -/* Mask bits for ChangeKeyboardControl */ -.TS -lw(.5i) lw(2.5i) lw(.8i). -T{ -#define -T} T{ -.PN KBKeyClickPercent -T} T{ -(1L<<0) -T} -T{ -#define -T} T{ -.PN KBBellPercent -T} T{ -(1L<<1) -T} -T{ -#define -T} T{ -.PN KBBellPitch -T} T{ -(1L<<2) -T} -T{ -#define -T} T{ -.PN KBBellDuration -T} T{ -(1L<<3) -T} -T{ -#define -T} T{ -.PN KBLed -T} T{ -(1L<<4) -T} -T{ -#define -T} T{ -.PN KBLedMode -T} T{ -(1L<<5) -T} -T{ -#define -T} T{ -.PN KBKey -T} T{ -(1L<<6) -T} -T{ -#define -T} T{ -.PN KBAutoRepeatMode -T} T{ -(1L<<7) -T} -.TE -.IN "XKeyboardControl" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -/* Values */ - -typedef struct { - int key_click_percent; - int bell_percent; - int bell_pitch; - int bell_duration; - int led; - int led_mode; /* LedModeOn, LedModeOff */ - int key; - int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, - AutoRepeatModeDefault */ -} XKeyboardControl; -.De -.LP -.eM -The key_click_percent member sets the volume for key clicks between 0 (off) -and 100 (loud) inclusive, if possible. -A setting of \-1 restores the default. -Other negative values generate a -.PN BadValue -error. -.LP -The bell_percent sets the base volume for the bell between 0 (off) and 100 -(loud) inclusive, if possible. -A setting of \-1 restores the default. -Other negative values generate a -.PN BadValue -error. -The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible. -A setting of \-1 restores the default. -Other negative values generate a -.PN BadValue -error. -The bell_duration member sets the duration of the -bell specified in milliseconds, if possible. -A setting of \-1 restores the default. -Other negative values generate a -.PN BadValue -error. -.LP -If both the led_mode and led members are specified, -the state of that LED is changed, if possible. -The led_mode member can be set to -.PN LedModeOn -or -.PN LedModeOff . -If only led_mode is specified, the state of -all LEDs are changed, if possible. -At most 32 LEDs numbered from one are supported. -No standard interpretation of LEDs is defined. -If led is specified without led_mode, a -.PN BadMatch -error results. -.LP -If both the auto_repeat_mode and key members are specified, -the auto_repeat_mode of that key is changed (according to -.PN AutoRepeatModeOn , -.PN AutoRepeatModeOff , -or -.PN AutoRepeatModeDefault ), -if possible. -If only auto_repeat_mode is -specified, the global auto_repeat_mode for the entire keyboard is -changed, if possible, and does not affect the per-key settings. -If a key is specified without an auto_repeat_mode, a -.PN BadMatch -error results. -Each key has an individual mode of whether or not it should auto-repeat -and a default setting for the mode. -In addition, -there is a global mode of whether auto-repeat should be enabled or not -and a default setting for that mode. -When global mode is -.PN AutoRepeatModeOn , -keys should obey their individual auto-repeat modes. -When global mode is -.PN AutoRepeatModeOff , -no keys should auto-repeat. -An auto-repeating key generates alternating -.PN KeyPress -and -.PN KeyRelease -events. -When a key is used as a modifier, -it is desirable for the key not to auto-repeat, -regardless of its auto-repeat setting. -.LP -A bell generator connected with the console but not directly on a -keyboard is treated as if it were part of the keyboard. -The order in which controls are verified and altered is server-dependent. -If an error is generated, a subset of the controls may have been altered. -.LP -.sp -.IN "XChangeKeyboardControl" "" "@DEF@" -.sM -.FD 0 -XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned long \fIvalue_mask\fP\^; -.br - XKeyboardControl *\fIvalues\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIvalue_mask\fP 1i -Specifies which controls to change. -This mask is the bitwise inclusive OR of the valid control mask bits. -.IP \fIvalues\fP 1i -Specifies one value for each bit set to 1 in the mask. -.LP -.eM -The -.PN XChangeKeyboardControl -function controls the keyboard characteristics defined by the -.PN XKeyboardControl -structure. -The value_mask argument specifies which values are to be changed. -.LP -.PN XChangeKeyboardControl -can generate -.PN BadMatch -and -.PN BadValue -errors. -.LP -.sp -To obtain the current control values for the keyboard, use -.PN XGetKeyboardControl . -.IN "XGetKeyboardControl" "" "@DEF@" -.sM -.FD 0 -XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XKeyboardState *\fIvalues_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIvalues_return\fP 1i -Returns the current keyboard controls in the specified -.PN XKeyboardState -structure. -.LP -.eM -The -.PN XGetKeyboardControl -function returns the current control values for the keyboard to the -.PN XKeyboardState -structure. -.LP -.IN "XGetKeyboardControl" -.IN "XKeyboardState" "" "@DEF@" -.sM -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - int key_click_percent; - int bell_percent; - unsigned int bell_pitch, bell_duration; - unsigned long led_mask; - int global_auto_repeat; - char auto_repeats[32]; -} XKeyboardState; -.De -.LP -.eM -For the LEDs, -the least significant bit of led_mask corresponds to LED one, -and each bit set to 1 in led_mask indicates an LED that is lit. -The global_auto_repeat member can be set to -.PN AutoRepeatModeOn -or -.PN AutoRepeatModeOff . -The auto_repeats member is a bit vector. -Each bit set to 1 indicates that auto-repeat is enabled -for the corresponding key. -The vector is represented as 32 bytes. -Byte N (from 0) contains the bits for keys 8N to 8N + 7 -with the least significant bit in the byte representing key 8N. -.LP -.sp -To turn on keyboard auto-repeat, use -.PN XAutoRepeatOn . -.IN "XAutoRepeatOn" "" "@DEF@" -.sM -.FD 0 -XAutoRepeatOn\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XAutoRepeatOn -function turns on auto-repeat for the keyboard on the specified display. -.LP -.sp -To turn off keyboard auto-repeat, use -.PN XAutoRepeatOff . -.IN "XAutoRepeatOff" "" "@DEF@" -.sM -.FD 0 -XAutoRepeatOff\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XAutoRepeatOff -function turns off auto-repeat for the keyboard on the specified display. -.LP -.sp -To ring the bell, use -.PN XBell . -.IN "XBell" "" "@DEF@" -.sM -.FD 0 -XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIpercent\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIpercent\fP 1i -Specifies the volume for the bell, -which can range from \-100 to 100 inclusive. -.LP -.eM -The -.PN XBell -function rings the bell on the keyboard on the specified display, if possible. -The specified volume is relative to the base volume for the keyboard. -If the value for the percent argument is not in the range \-100 to 100 -inclusive, a -.PN BadValue -error results. -The volume at which the bell rings -when the percent argument is nonnegative is: -.IP -base \- [(base * percent) / 100] + percent -.LP -The volume at which the bell rings -when the percent argument is negative is: -.IP -base + [(base * percent) / 100] -.LP -To change the base volume of the bell, use -.PN XChangeKeyboardControl . -.LP -.PN XBell -can generate a -.PN BadValue -error. -.LP -.sp -To obtain a bit vector that describes the state of the keyboard, use -.PN XQueryKeymap . -.IN "XQueryKeymap" "" "@DEF@" -.sM -.FD 0 -XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char \fIkeys_return\fP[32]\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIkeys_return\fP 1i -Returns an array of bytes that identifies which keys are pressed down. -Each bit represents one key of the keyboard. -.LP -.eM -The -.PN XQueryKeymap -function returns a bit vector for the logical state of the keyboard, -where each bit set to 1 indicates that the corresponding key is currently -pressed down. -The vector is represented as 32 bytes. -Byte N (from 0) contains the bits for keys 8N to 8N + 7 -with the least significant bit in the byte representing key 8N. -.LP -Note that the logical state of a device (as seen by client applications) -may lag the physical state if device event processing is frozen. -.LP -.sp -To set the mapping of the pointer buttons, use -.PN XSetPointerMapping . -.IN "XSetPointerMapping" "" "@DEF@" -.sM -.FD 0 -int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned char \fImap\fP\^[]\^; -.br - int \fInmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImap\fP 1i -Specifies the mapping list. -.IP \fInmap\fP 1i -Specifies the number of items in the mapping list. -.LP -.eM -The -.PN XSetPointerMapping -function sets the mapping of the pointer. -If it succeeds, the X server generates a -.PN MappingNotify -event, and -.PN XSetPointerMapping -returns -.PN MappingSuccess . -Element map[i] defines the logical button number for the physical button -i+1. -The length of the list must be the same as -.PN XGetPointerMapping -would return, -or a -.PN BadValue -error results. -A zero element disables a button, and elements are not restricted in -value by the number of physical buttons. -However, no two elements can have the same nonzero value, -or a -.PN BadValue -error results. -If any of the buttons to be altered are logically in the down state, -.PN XSetPointerMapping -returns -.PN MappingBusy , -and the mapping is not changed. -.LP -.PN XSetPointerMapping -can generate a -.PN BadValue -error. -.LP -.sp -To get the pointer mapping, use -.PN XGetPointerMapping . -.IN "XGetPointerMapping" "" "@DEF@" -.sM -.FD 0 -int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned char \fImap_return\fP\^[]\^; -.br - int \fInmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImap_return\fP 1i -Returns the mapping list. -.IP \fInmap\fP 1i -Specifies the number of items in the mapping list. -.LP -.eM -The -.PN XGetPointerMapping -function returns the current mapping of the pointer. -Pointer buttons are numbered starting from one. -.PN XGetPointerMapping -returns the number of physical buttons actually on the pointer. -The nominal mapping for a pointer is map[i]=i+1. -The nmap argument specifies the length of the array where the pointer -mapping is returned, and only the first nmap elements are returned -in map_return. -.LP -.sp -To control the pointer's interactive feel, use -.PN XChangePointerControl . -.IN "XChangePointerControl" "" "@DEF@" -.sM -.FD 0 -XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^, -.br - \fIaccel_denominator\fP\^, \fIthreshold\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^; -.br - int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^; -.br - int \fIthreshold\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdo_accel\fP 1i -Specifies a Boolean value that controls whether the values for -the accel_numerator or accel_denominator are used. -.IP \fIdo_threshold\fP 1i -Specifies a Boolean value that controls whether the value for the -threshold is used. -.IP \fIaccel_numerator\fP 1i -Specifies the numerator for the acceleration multiplier. -.IP \fIaccel_denominator\fP 1i -Specifies the denominator for the acceleration multiplier. -.IP \fIthreshold\fP 1i -Specifies the acceleration threshold. -.LP -.eM -The -.PN XChangePointerControl -function defines how the pointing device moves. -The acceleration, expressed as a fraction, is a -multiplier for movement. -For example, -specifying 3/1 means the pointer moves three times as fast as normal. -The fraction may be rounded arbitrarily by the X server. -Acceleration -only takes effect if the pointer moves more than threshold pixels at -once and only applies to the amount beyond the value in the threshold argument. -Setting a value to \-1 restores the default. -The values of the do_accel and do_threshold arguments must be -.PN True -for the pointer values to be set, -or the parameters are unchanged. -Negative values (other than \-1) generate a -.PN BadValue -error, as does a zero value -for the accel_denominator argument. -.LP -.PN XChangePointerControl -can generate a -.PN BadValue -error. -.LP -.sp -To get the current pointer parameters, use -.PN XGetPointerControl . -.IN "XGetPointerControl" "" "@DEF@" -.sM -.FD 0 -XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^, -.br - \fIthreshold_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^; -.br - int *\fIthreshold_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIaccel_numerator_return\fP 1i -Returns the numerator for the acceleration multiplier. -.IP \fIaccel_denominator_return\fP 1i -Returns the denominator for the acceleration multiplier. -.IP \fIthreshold_return\fP 1i -Returns the acceleration threshold. -.LP -.eM -The -.PN XGetPointerControl -function returns the pointer's current acceleration multiplier -and acceleration threshold. -.NH 2 -Manipulating the Keyboard Encoding -.XS -\*(SN Manipulating the Keyboard Encoding -.XE -.LP -A KeyCode represents a physical (or logical) key. -KeyCodes lie in the inclusive range [8,255]. -A KeyCode value carries no intrinsic information, -although server implementors may attempt to encode geometry -(for example, matrix) information in some fashion so that it can -be interpreted in a server-dependent fashion. -The mapping between keys and KeyCodes cannot be changed. -.LP -A KeySym is an encoding of a symbol on the cap of a key. -The set of defined KeySyms includes the ISO Latin character sets (1\-4), -Katakana, Arabic, Cyrillic, Greek, Technical, -Special, Publishing, APL, Hebrew, Thai, Korean -and a miscellany of keys found -on keyboards (Return, Help, Tab, and so on). -To the extent possible, these sets are derived from international -standards. -In areas where no standards exist, -some of these sets are derived from Digital Equipment Corporation standards. -The list of defined symbols can be found in -.hN X11/keysymdef.h . -Unfortunately, some C preprocessors have -limits on the number of defined symbols. -If you must use KeySyms not -in the Latin 1\-4, Greek, and miscellaneous classes, -you may have to define a symbol for those sets. -Most applications usually only include -.hN X11/keysym.h , -which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous. -.LP -A list of KeySyms is associated with each KeyCode. -The list is intended to convey the set of symbols on the corresponding key. -If the list (ignoring trailing -.PN NoSymbol -entries) is -a single KeySym ``\fIK\fP'', -then the list is treated as if it were the list -``\fIK\fP NoSymbol \fIK\fP NoSymbol''. -If the list (ignoring trailing -.PN NoSymbol -entries) is a pair of KeySyms ``\fIK1 K2\fP'', -then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP''. -If the list (ignoring trailing -.PN NoSymbol -entries) is a triple of KeySyms ``\fIK1 K2 K3\fP'', -then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol''. -When an explicit ``void'' element is desired in the list, -the value -.PN VoidSymbol -can be used. -.LP -The first four elements of the list are split into two groups of KeySyms. -Group 1 contains the first and second KeySyms; -Group 2 contains the third and fourth KeySyms. -Within each group, -if the second element of the group is -.PN NoSymbol , -then the group should be treated as if the second element were -the same as the first element, -except when the first element is an alphabetic KeySym ``\fIK\fP'' -for which both lowercase and uppercase forms are defined. -In that case, -the group should be treated as if the first element were -the lowercase form of ``\fIK\fP'' and the second element were -the uppercase form of ``\fIK\fP''. -.LP -The standard rules for obtaining a KeySym from a -.PN KeyPress -event make use of only the Group 1 and Group 2 KeySyms; -no interpretation of other KeySyms in the list is given. -Which group to use is determined by the modifier state. -Switching between groups is controlled by the KeySym named MODE SWITCH, -by attaching that KeySym to some KeyCode and attaching -that KeyCode to any one of the modifiers -.PN Mod1 -through -.PN Mod5 . -This modifier is called the \fIgroup modifier\fP\^. -For any KeyCode, -Group 1 is used when the group modifier is off, -and Group 2 is used when the group modifier is on. -.LP -The -.PN Lock -modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock -is attached to some KeyCode and that KeyCode is attached to the -.PN Lock -modifier. The -.PN Lock -modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock -is attached to some KeyCode and that KeyCode is attached to the -.PN Lock -modifier. If the -.PN Lock -modifier could be interpreted as both -CapsLock and ShiftLock, the CapsLock interpretation is used. -.LP -The operation of keypad keys is controlled by the KeySym named XK_Num_Lock, -by attaching that KeySym to some KeyCode and attaching that KeyCode to any -one of the modifiers -.PN Mod1 -through -.PN Mod5 . -This modifier is called the -\fInumlock modifier\fP\^. The standard KeySyms with the prefix ``XK_KP_'' -in their -name are called keypad KeySyms; these are KeySyms with numeric value in -the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition, -vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF -are also keypad KeySyms. -.LP -Within a group, the choice of KeySym is determined by applying the first -rule that is satisfied from the following list: -.IP \(bu 5 -The numlock modifier is on and the second KeySym is a keypad KeySym. In -this case, if the -.PN Shift -modifier is on, or if the -.PN Lock -modifier is on and -is interpreted as ShiftLock, then the first KeySym is used, otherwise the -second KeySym is used. -.IP \(bu 5 -The -.PN Shift -and -.PN Lock -modifiers are both off. In this case, the first -KeySym is used. -.IP \(bu 5 -The -.PN Shift -modifier is off, and the -.PN Lock -modifier is on and is -interpreted as CapsLock. In this case, the first KeySym is used, but if -that KeySym is lowercase alphabetic, then the corresponding uppercase -KeySym is used instead. -.IP \(bu 5 -The -.PN Shift -modifier is on, and the -.PN Lock -modifier is on and is interpreted -as CapsLock. In this case, the second KeySym is used, but if that KeySym -is lowercase alphabetic, then the corresponding uppercase KeySym is used -instead. -.IP \(bu 5 -The -.PN Shift -modifier is on, or the -.PN Lock -modifier is on and is interpreted -as ShiftLock, or both. In this case, the second KeySym is used. -.LP -No spatial geometry of the symbols on the key is defined by -their order in the KeySym list, -although a geometry might be defined on a -server-specific basis. -The X server does not use the mapping between KeyCodes and KeySyms. -Rather, it merely stores it for reading and writing by clients. -.sp -.LP -To obtain the legal KeyCodes for a display, use -.PN XDisplayKeycodes . -.IN "XDisplayKeycodes" "" "@DEF@" -.sM -.FD 0 -XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \ -\fImax_keycodes_return\fP\^) -.br - Display *\^\fIdisplay\fP\^; -.br - int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImin_keycodes_return\fP 1i -Returns the minimum number of KeyCodes. -.IP \fImax_keycodes_return\fP 1i -Returns the maximum number of KeyCodes. -.LP -.eM -The -.PN XDisplayKeycodes -function returns the min-keycodes and max-keycodes supported by the -specified display. -The minimum number of KeyCodes returned is never less than 8, -and the maximum number of KeyCodes returned is never greater than 255. -Not all KeyCodes in this range are required to have corresponding keys. -.sp -.LP -To obtain the symbols for the specified KeyCodes, use -.PN XGetKeyboardMapping . -.IN "XGetKeyboardMapping" "" "@DEF@" -.sM -.FD 0 -KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, -.br - \fIkeysyms_per_keycode_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - KeyCode \fIfirst_keycode\fP\^; -.br - int \fIkeycode_count\fP\^; -.br - int *\fIkeysyms_per_keycode_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Kc returned -.IP \fIfirst_keycode\fP 1i -Specifies the first KeyCode that is to be \*(Kc. -.IP \fIkeycode_count\fP 1i -Specifies the number of KeyCodes that are to be returned. -.IP \fIkeysyms_per_keycode_return\fP 1i -Returns the number of KeySyms per KeyCode. -.LP -.eM -The -.PN XGetKeyboardMapping -function returns the symbols for the specified number of KeyCodes -starting with first_keycode. -The value specified in first_keycode must be greater than -or equal to min_keycode as returned by -.PN XDisplayKeycodes , -or a -.PN BadValue -error results. -In addition, the following expression must be less than or equal -to max_keycode as returned by -.PN XDisplayKeycodes : -.LP -.Ds -first_keycode + keycode_count \- 1 -.De -.LP -If this is not the case, a -.PN BadValue -error results. -The number of elements in the KeySyms list is: -.LP -.Ds -keycode_count * keysyms_per_keycode_return -.De -.LP -KeySym number N, counting from zero, for KeyCode K has the following index -in the list, counting from zero: -.Ds -(K \- first_code) * keysyms_per_code_return + N -.De -.LP -The X server arbitrarily chooses the keysyms_per_keycode_return value -to be large enough to report all requested symbols. -A special KeySym value of -.PN NoSymbol -is used to fill in unused elements for -individual KeyCodes. -To free the storage returned by -.PN XGetKeyboardMapping , -use -.PN XFree . -.LP -.PN XGetKeyboardMapping -can generate a -.PN BadValue -error. -.LP -.sp -To change the keyboard mapping, use -.PN XChangeKeyboardMapping . -.IN "XChangeKeyboardMapping" "" "@DEF@" -.sM -.FD 0 -XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIfirst_keycode\fP\^; -.br - int \fIkeysyms_per_keycode\fP\^; -.br - KeySym *\fIkeysyms\fP\^; -.br - int \fInum_codes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Kc changed -.IP \fIfirst_keycode\fP 1i -Specifies the first KeyCode that is to be \*(Kc. -.IP \fIkeysyms_per_keycode\fP 1i -Specifies the number of KeySyms per KeyCode. -.IP \fIkeysyms\fP 1i -Specifies an array of KeySyms. -.IP \fInum_codes\fP 1i -Specifies the number of KeyCodes that are to be changed. -.LP -.eM -The -.PN XChangeKeyboardMapping -function defines the symbols for the specified number of KeyCodes -starting with first_keycode. -The symbols for KeyCodes outside this range remain unchanged. -The number of elements in keysyms must be: -.LP -.Ds -num_codes * keysyms_per_keycode -.De -.LP -The specified first_keycode must be greater than or equal to min_keycode -returned by -.PN XDisplayKeycodes , -or a -.PN BadValue -error results. -In addition, the following expression must be less than or equal to -max_keycode as returned by -.PN XDisplayKeycodes , -or a -.PN BadValue -error results: -.LP -.Ds -first_keycode + num_codes \- 1 -.De -.LP -KeySym number N, counting from zero, for KeyCode K has the following index -in keysyms, counting from zero: -.LP -.Ds -(K \- first_keycode) * keysyms_per_keycode + N -.De -.LP -The specified keysyms_per_keycode can be chosen arbitrarily by the client -to be large enough to hold all desired symbols. -A special KeySym value of -.PN NoSymbol -should be used to fill in unused elements -for individual KeyCodes. -It is legal for -.PN NoSymbol -to appear in nontrailing positions -of the effective list for a KeyCode. -.PN XChangeKeyboardMapping -generates a -.PN MappingNotify -event. -.LP -There is no requirement that the X server interpret this mapping. -It is merely stored for reading and writing by clients. -.LP -.PN XChangeKeyboardMapping -can generate -.PN BadAlloc -and -.PN BadValue -errors. -.LP -The next six functions make use of the -.PN XModifierKeymap -data structure, which contains: -.LP -.IN "XModifierKeymap" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int max_keypermod; /* This server's max number of keys per modifier */ - KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */ -} XModifierKeymap; -.De -.LP -.eM -To create an -.PN XModifierKeymap -structure, use -.PN XNewModifiermap . -.IN "XNewModifiermap" "" "@DEF@" -.sM -.FD 0 -XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^) -.br - int \fImax_keys_per_mod\fP\^; -.FN -.IP \fImax_keys_per_mod\fP 1i -Specifies the number of KeyCode entries preallocated to the modifiers -in the map. -.LP -.eM -The -.PN XNewModifiermap -function returns a pointer to -.PN XModifierKeymap -structure for later use. -.LP -.sp -To add a new entry to an -.PN XModifierKeymap -structure, use -.PN XInsertModifiermapEntry . -.IN "XInsertModifiermapEntry" "" "@DEF@" -.sM -.FD 0 -XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \ -\fIkeycode_entry\fP, \fImodifier\fP\^) -.br - XModifierKeymap *\fImodmap\fP\^; -.br - KeyCode \fIkeycode_entry\fP\^; -.br - int \fImodifier\fP\^; -.FN -.IP \fImodmap\fP 1i -Specifies the -.PN XModifierKeymap -structure. -.IP \fIkeycode_entry\fP 1i -Specifies the KeyCode. -.IP \fImodifier\fP 1i -Specifies the modifier. -.LP -.eM -The -.PN XInsertModifiermapEntry -function adds the specified KeyCode to the set that controls the specified -modifier and returns the resulting -.PN XModifierKeymap -structure (expanded as needed). -.LP -.sp -To delete an entry from an -.PN XModifierKeymap -structure, use -.PN XDeleteModifiermapEntry . -.IN "XDeleteModifiermapEntry" "" "@DEF@" -.sM -.FD 0 -XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \ -\fIkeycode_entry\fP, \fImodifier\fP\^) -.br - XModifierKeymap *\fImodmap\fP\^; -.br - KeyCode \fIkeycode_entry\fP\^; -.br - int \fImodifier\fP\^; -.FN -.IP \fImodmap\fP 1i -Specifies the -.PN XModifierKeymap -structure. -.IP \fIkeycode_entry\fP 1i -Specifies the KeyCode. -.IP \fImodifier\fP 1i -Specifies the modifier. -.LP -.eM -The -.PN XDeleteModifiermapEntry -function deletes the specified KeyCode from the set that controls the -specified modifier and returns a pointer to the resulting -.PN XModifierKeymap -structure. -.LP -.sp -To destroy an -.PN XModifierKeymap -structure, use -.PN XFreeModifiermap . -.IN "XFreeModifiermap" "" "@DEF@" -.sM -.FD 0 -XFreeModifiermap(\^\fImodmap\fP\^) -.br - XModifierKeymap *\fImodmap\fP; -.FN -.IP \fImodmap\fP 1i -Specifies the -.PN XModifierKeymap -structure. -.LP -.eM -The -.PN XFreeModifiermap -function frees the specified -.PN XModifierKeymap -structure. -.LP -.sp -To set the KeyCodes to be used as modifiers, use -.PN XSetModifierMapping . -.IN "XSetModifierMapping" "" "@DEF@" -.sM -.FD 0 -int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XModifierKeymap *\fImodmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImodmap\fP 1i -Specifies the -.PN XModifierKeymap -structure. -.LP -.eM -The -.PN XSetModifierMapping -function specifies the KeyCodes of the keys (if any) that are to be used -as modifiers. -If it succeeds, -the X server generates a -.PN MappingNotify -event, and -.PN XSetModifierMapping -returns -.PN MappingSuccess . -X permits at most 8 modifier keys. -If more than 8 are specified in the -.PN XModifierKeymap -structure, a -.PN BadLength -error results. -.LP -The modifiermap member of the -.PN XModifierKeymap -structure contains 8 sets of max_keypermod KeyCodes, -one for each modifier in the order -.PN Shift , -.PN Lock , -.PN Control , -.PN Mod1 , -.PN Mod2 , -.PN Mod3 , -.PN Mod4 , -and -.PN Mod5 . -Only nonzero KeyCodes have meaning in each set, -and zero KeyCodes are ignored. -In addition, all of the nonzero KeyCodes must be in the range specified by -min_keycode and max_keycode in the -.PN Display -structure, -or a -.PN BadValue -error results. -.LP -An X server can impose restrictions on how modifiers can be changed, -for example, -if certain keys do not generate up transitions in hardware, -if auto-repeat cannot be disabled on certain keys, -or if multiple modifier keys are not supported. -If some such restriction is violated, -the status reply is -.PN MappingFailed , -and none of the modifiers are changed. -If the new KeyCodes specified for a modifier differ from those -currently defined and any (current or new) keys for that modifier are -in the logically down state, -.PN XSetModifierMapping -returns -.PN MappingBusy , -and none of the modifiers is changed. -.LP -.PN XSetModifierMapping -can generate -.PN BadAlloc -and -.PN BadValue -errors. -.LP -.sp -To obtain the KeyCodes used as modifiers, use -.PN XGetModifierMapping . -.IN "XGetModifierMapping" "" "@DEF@" -.sM -.FD 0 -XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; - -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XGetModifierMapping -function returns a pointer to a newly created -.PN XModifierKeymap -structure that contains the keys being used as modifiers. -The structure should be freed after use by calling -.PN XFreeModifiermap . -If only zero values appear in the set for any modifier, -that modifier is disabled. -.bp diff --git a/libX11/specs/libX11/CH12.xml b/libX11/specs/libX11/CH12.xml new file mode 100644 index 000000000..210a2be9f --- /dev/null +++ b/libX11/specs/libX11/CH12.xml @@ -0,0 +1,3928 @@ +<chapter id="input_device_functions">
+<title>Input Device Functions</title>
+
+<para>
+You can use the Xlib input device functions to:
+</para>
+
+<itemizedlist>
+ <listitem><para>Grab the pointer and individual buttons on the pointer</para></listitem>
+ <listitem><para>Grab the keyboard and individual keys on the keyboard</para></listitem>
+ <listitem><para>Resume event processing</para></listitem>
+ <listitem><para>Move the pointer</para></listitem>
+ <listitem><para>Set the input focus</para></listitem>
+ <listitem><para>Manipulate the keyboard and pointer settings</para></listitem>
+ <listitem><para>Manipulate the keyboard encoding</para></listitem>
+</itemizedlist>
+
+<sect1 id="Pointer_Grabbing_">
+<title>Pointer Grabbing </title>
+<!-- .XS -->
+<!-- (SN Pointer Grabbing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to control input from the pointer,
+which usually is a mouse.
+Usually, as soon as keyboard and mouse events occur,
+the X server delivers them to the appropriate client,
+which is determined by the window and input focus.
+The X server provides sufficient control over event delivery to
+allow window managers to support mouse ahead and various other
+styles of user interface.
+Many of these user interfaces depend on synchronous delivery of events.
+The delivery of pointer and keyboard events can be controlled
+independently.
+</para>
+<para>
+<!-- .LP -->
+When mouse buttons or keyboard keys are grabbed, events
+will be sent to the grabbing client rather than the normal
+client who would have received the event.
+If the keyboard or pointer is in asynchronous mode,
+further mouse and keyboard events will continue to be processed.
+If the keyboard or pointer is in synchronous mode, no
+further events are processed until the grabbing client
+allows them (see
+<function>XAllowEvents</function>).
+The keyboard or pointer is considered frozen during this
+interval.
+The event that triggered the grab can also be replayed.
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>
+There are two kinds of grabs:
+active and passive.
+An active grab occurs when a single client grabs the keyboard and/or pointer
+explicitly (see
+<function>XGrabPointer</function>
+and
+<function>XGrabKeyboard</function>).
+<indexterm><primary>Passive grab</primary></indexterm>
+A passive grab occurs when clients grab a particular keyboard key
+or pointer button in a window,
+and the grab will activate when the key or button is actually pressed.
+Passive grabs are convenient for implementing reliable pop-up menus.
+For example, you can guarantee that the pop-up is mapped
+before the up pointer button event occurs by
+grabbing a button requesting synchronous behavior.
+The down event will trigger the grab and freeze further
+processing of pointer events until you have the chance to
+map the pop-up window.
+You can then allow further event processing.
+The up event will then be correctly processed relative to the
+pop-up window.
+</para>
+<para>
+<!-- .LP -->
+For many operations,
+there are functions that take a time argument.
+The X server includes a timestamp in various events.
+One special time, called
+<indexterm significance="preferred"><primary>CurrentTime</primary></indexterm>
+<indexterm significance="preferred"><primary>Time</primary></indexterm>
+<function>CurrentTime</function>,
+represents the current server time.
+The X server maintains the time when the input focus was last changed,
+when the keyboard was last grabbed,
+when the pointer was last grabbed,
+or when a selection was last changed.
+Your
+application may be slow reacting to an event.
+You often need some way to specify that your
+request should not occur if another application has in the meanwhile
+taken control of the keyboard, pointer, or selection.
+By providing the timestamp from the event in the request,
+you can arrange that the operation not take effect
+if someone else has performed an operation in the meanwhile.
+</para>
+<para>
+<!-- .LP -->
+A timestamp is a time value, expressed in milliseconds.
+It typically is the time since the last server reset.
+Timestamp values wrap around (after about 49.7 days).
+The server, given its current time is represented by timestamp T,
+always interprets timestamps from clients by treating half of the timestamp
+space as being later in time than T.
+One timestamp value, named
+<function>CurrentTime</function>,
+is never generated by the server.
+This value is reserved for use in requests to represent the current server time.
+</para>
+<para>
+<!-- .LP -->
+For many functions in this section,
+you pass pointer event mask bits.
+The valid pointer event mask bits are:
+<function>ButtonPressMask</function>,
+<function>ButtonReleaseMask</function>,
+<function>EnterWindowMask</function>,
+<function>LeaveWindowMask</function>,
+<function>PointerMotionMask</function>,
+<function>PointerMotionHintMask</function>,
+<function>Button1MotionMask</function>,
+<function>Button2MotionMask</function>,
+<function>Button3MotionMask</function>,
+<function>Button4MotionMask</function>,
+<function>Button5MotionMask</function>,
+<function>ButtonMotionMask</function>,
+and
+<function>KeyMapStateMask</function>.
+For other functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+<function>ShiftMask</function>,
+<function>LockMask</function>,
+<function>ControlMask</function>,
+<function>Mod1Mask</function>,
+<function>Mod2Mask</function>,
+<function>Mod3Mask</function>,
+<function>Mod4Mask</function>,
+and
+<function>Mod5Mask</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the pointer, use
+<function>XGrabPointer</function>.
+<indexterm><primary>Grabbing</primary><secondary>pointer</secondary></indexterm>
+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGrabPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+ <paramdef>Window<parameter> confine_to</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the pointer
+events are to be reported as usual or reported with respect to the grab window
+if selected by the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window to confine the pointer in or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed during the grab or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabPointer</function>
+function actively grabs control of the pointer and returns
+<function>GrabSuccess</function>
+if the grab was successful.
+Further pointer events are reported only to the grabbing client.
+<function>XGrabPointer</function>
+overrides any active pointer grab by this client.
+If owner_events is
+<function>False</function>,
+all generated pointer events
+are reported with respect to grab_window and are reported only if
+selected by event_mask.
+If owner_events is
+<function>True</function>
+and if a generated
+pointer event would normally be reported to this client,
+it is reported as usual.
+Otherwise, the event is reported with respect to the
+grab_window and is reported only if selected by event_mask.
+For either value of owner_events, unreported events are discarded.
+</para>
+<para>
+<!-- .LP -->
+If the pointer_mode is
+<function>GrabModeAsync</function>,
+pointer event processing continues as usual.
+If the pointer is currently frozen by this client,
+the processing of events for the pointer is resumed.
+If the pointer_mode is
+<function>GrabModeSync</function>,
+the state of the pointer, as seen by
+client applications,
+appears to freeze, and the X server generates no further pointer events
+until the grabbing client calls
+<function>XAllowEvents</function>
+or until the pointer grab is released.
+Actual pointer changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard_mode is
+<function>GrabModeAsync</function>,
+keyboard event processing is unaffected by activation of the grab.
+If the keyboard_mode is
+<function>GrabModeSync</function>,
+the state of the keyboard, as seen by
+client applications,
+appears to freeze, and the X server generates no further keyboard events
+until the grabbing client calls
+<function>XAllowEvents</function>
+or until the pointer grab is released.
+Actual keyboard changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If a cursor is specified, it is displayed regardless of what
+window the pointer is in.
+If
+<function>None</function>
+is specified,
+the normal cursor for that window is displayed
+when the pointer is in grab_window or one of its subwindows;
+otherwise, the cursor for grab_window is displayed.
+</para>
+<para>
+<!-- .LP -->
+If a confine_to window is specified,
+the pointer is restricted to stay contained in that window.
+The confine_to window need have no relationship to the grab_window.
+If the pointer is not initially in the confine_to window,
+it is warped automatically to the closest edge
+just before the grab activates and enter/leave events are generated as usual.
+If the confine_to window is subsequently reconfigured,
+the pointer is warped automatically, as necessary,
+to keep it contained in the window.
+</para>
+<para>
+<!-- .LP -->
+The time argument allows you to avoid certain circumstances that come up
+if applications take a long time to respond or if there are long network
+delays.
+Consider a situation where you have two applications, both
+of which normally grab the pointer when clicked on.
+If both applications specify the timestamp from the event,
+the second application may wake up faster and successfully grab the pointer
+before the first application.
+The first application then will get an indication that the other application
+grabbed the pointer before its request was processed.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabPointer </function>
+generates
+<function>EnterNotify </function>
+and
+<function>LeaveNotify </function>
+events.
+</para>
+<para>
+<!-- .LP -->
+Either if grab_window or confine_to window is not viewable
+or if the confine_to window lies completely outside the boundaries of the root
+window,
+<function>XGrabPointer</function>
+fails and returns
+<function>GrabNotViewable</function>.
+If the pointer is actively grabbed by some other client,
+it fails and returns
+<function>AlreadyGrabbed</function>.
+If the pointer is frozen by an active grab of another client,
+it fails and returns
+<function>GrabFrozen</function>.
+If the specified time is earlier than the last-pointer-grab time or later
+than the current X server time, it fails and returns
+<function>GrabInvalidTime</function>.
+Otherwise, the last-pointer-grab time is set to the specified time
+(<function>CurrentTime </function>
+is replaced by the current X server time).
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabPointer</function>
+can generate
+<function>BadCursor</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the pointer, use
+<function>XUngrabPointer</function>.
+<indexterm><primary>Ungrabbing</primary><secondary>pointer</secondary></indexterm>
+<indexterm><primary>Pointer</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabPointer</function>
+function releases the pointer and any queued events
+if this client has actively grabbed the pointer from
+<function>XGrabPointer</function>,
+<function>XGrabButton</function>,
+or from a normal button press.
+<function>XUngrabPointer</function>
+does not release the pointer if the specified
+time is earlier than the last-pointer-grab time or is later than the
+current X server time.
+It also generates
+<function>EnterNotify </function>
+and
+<function>LeaveNotify </function>
+events.
+The X server performs an
+<function>UngrabPointer </function>
+request automatically if the event window or confine_to window
+for an active pointer grab becomes not viewable
+or if window reconfiguration causes the confine_to window to lie completely
+outside the boundaries of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change an active pointer grab, use
+<function>XChangeActivePointerGrab</function>.
+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+<indexterm ><primary>Changing</primary><secondary>pointer grab</secondary></indexterm>
+<indexterm significance="preferred"><primary>XChangeActivePointerGrab</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeActivePointerGrab</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeActivePointerGrab</function>
+function changes the specified dynamic parameters if the pointer is actively
+grabbed by the client and if the specified time is no earlier than the
+last-pointer-grab time and no later than the current X server time.
+This function has no effect on the passive parameters of an
+<function>XGrabButton</function>.
+The interpretation of event_mask and cursor is the same as described in
+<function>XGrabPointer</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeActivePointerGrab</function>
+can generate
+<function>BadCursor </function>
+and
+<function>BadValue</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab a pointer button, use
+<function>XGrabButton</function>.
+<indexterm><primary>Grabbing</primary><secondary>buttons</secondary></indexterm>
+<indexterm><primary>Button</primary><secondary>grabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabButton</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGrabButton</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> button</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+ <paramdef>Window<parameter> confine_to</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Bu grabbed -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pointer button that is to be (Bu or
+<function>AnyButton</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the pointer
+events are to be reported as usual or reported with respect to the grab window
+if selected by the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window to confine the pointer in or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabButton</function>
+function establishes a passive grab.
+In the future,
+the pointer is actively grabbed (as for
+<function>XGrabPointer</function>),
+the last-pointer-grab time is set to the time at which the button was pressed
+(as transmitted in the
+<function>ButtonPress</function>
+event), and the
+<function>ButtonPress</function>
+event is reported if all of the following conditions are true:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The pointer is not grabbed, and the specified button is logically pressed
+when the specified modifier keys are logically down,
+and no other buttons or modifier keys are logically down.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The grab_window contains the pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The confine_to window (if any) is viewable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A passive grab on the same button/key combination does not exist
+on any ancestor of grab_window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The interpretation of the remaining arguments is as for
+<function>XGrabPointer</function>.
+The active grab is terminated automatically when the logical state of the
+pointer has all buttons released
+(independent of the state of the logical modifier keys).
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+This request overrides all previous grabs by the same client on the same
+button/key combinations on the same window.
+A modifiers of
+<function>AnyModifier </function>
+is equivalent to issuing the grab request for all
+possible modifier combinations (including the combination of no modifiers).
+It is not required that all modifiers specified have currently assigned
+KeyCodes.
+A button of
+<function>AnyButton </function>
+is equivalent to
+issuing the request for all possible buttons.
+Otherwise, it is not required that the specified button currently be assigned
+to a physical button.
+</para>
+<para>
+<!-- .LP -->
+If some other client has already issued an
+<function>XGrabButton</function>
+with the same button/key combination on the same window, a
+<function>BadAccess </function>
+error results.
+When using
+<function>AnyModifier </function>
+or
+<function>AnyButton</function>,
+the request fails completely,
+and a
+<function>BadAccess</function>
+error results (no grabs are
+established) if there is a conflicting grab for any combination.
+<function>XGrabButton</function>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabButton</function>
+can generate
+<function>BadCursor</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a pointer button, use
+<function>XUngrabButton</function>.
+<indexterm><primary>Ungrabbing</primary><secondary>buttons</secondary></indexterm>
+<indexterm><primary>Button</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabButton</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabButton</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> button</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Bu released -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pointer button that is to be (Bu or
+<function>AnyButton</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabButton</function>
+function releases the passive button/key combination on the specified window if
+it was grabbed by this client.
+A modifiers of
+<function>AnyModifier </function>
+is
+equivalent to issuing
+the ungrab request for all possible modifier combinations, including
+the combination of no modifiers.
+A button of
+<function>AnyButton </function>
+is equivalent to issuing the
+request for all possible buttons.
+<function>XUngrabButton</function>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<function>XUngrabButton</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Keyboard_Grabbing_">
+<title>Keyboard Grabbing </title>
+<!-- .XS -->
+<!-- (SN Keyboard Grabbing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to grab or ungrab the keyboard
+as well as allow events.
+</para>
+<para>
+<!-- .LP -->
+For many functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+<function>ShiftMask</function>,
+<function>LockMask</function>,
+<function>ControlMask</function>,
+<function>Mod1Mask</function>,
+<function>Mod2Mask</function>,
+<function>Mod3Mask</function>,
+<function>Mod4Mask</function>,
+and
+<function>Mod5Mask</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the keyboard, use
+<function>XGrabKeyboard</function>.
+<indexterm><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>keyboard</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabKeyboard</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGrabKeyboard</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the keyboard events
+are to be reported as usual.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabKeyboard</function>
+function actively grabs control of the keyboard and generates
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events.
+Further key events are reported only to the
+grabbing client.
+<function>XGrabKeyboard</function>
+overrides any active keyboard grab by this client.
+If owner_events is
+<function>False</function>,
+all generated key events are reported with
+respect to grab_window.
+If owner_events is
+<function>True </function>
+and if a generated
+key event would normally be reported to this client, it is reported
+normally; otherwise, the event is reported with respect to the
+grab_window.
+Both
+<function>KeyPress </function>
+and
+<function>KeyRelease </function>
+events are always reported,
+independent of any event selection made by the client.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard_mode argument is
+<function>GrabModeAsync</function>,
+keyboard event processing continues
+as usual.
+If the keyboard is currently frozen by this client,
+then processing of keyboard events is resumed.
+If the keyboard_mode argument is
+<function>GrabModeSync</function>,
+the state of the keyboard (as seen by client applications) appears to freeze,
+and the X server generates no further keyboard events until the
+grabbing client issues a releasing
+<function>XAllowEvents </function>
+call or until the keyboard grab is released.
+Actual keyboard changes are not lost while the keyboard is frozen;
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If pointer_mode is
+<function>GrabModeAsync</function>,
+pointer event processing is unaffected
+by activation of the grab.
+If pointer_mode is
+<function>GrabModeSync</function>,
+the state of the pointer (as seen by client applications) appears to freeze,
+and the X server generates no further pointer events
+until the grabbing client issues a releasing
+<function>XAllowEvents </function>
+call or until the keyboard grab is released.
+Actual pointer changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard is actively grabbed by some other client,
+<function>XGrabKeyboard</function>
+fails and returns
+<function>AlreadyGrabbed</function>.
+If grab_window is not viewable,
+it fails and returns
+<function>GrabNotViewable</function>.
+If the keyboard is frozen by an active grab of another client,
+it fails and returns
+<function>GrabFrozen</function>.
+If the specified time is earlier than the last-keyboard-grab time
+or later than the current X server time,
+it fails and returns
+<function>GrabInvalidTime</function>.
+Otherwise, the last-keyboard-grab time is set to the specified time
+(<function>CurrentTime </function>
+is replaced by the current X server time).
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabKeyboard</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the keyboard, use
+<function>XUngrabKeyboard</function>.
+<indexterm><primary>Keyboard</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm><primary>Ungrabbing</primary><secondary>keyboard</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabKeyboard</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabKeyboard</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabKeyboard</function>
+function
+releases the keyboard and any queued events if this client has it actively grabbed from
+either
+<function>XGrabKeyboard</function>
+or
+<function>XGrabKey</function>.
+<function>XUngrabKeyboard</function>
+does not release the keyboard and any queued events
+if the specified time is earlier than
+the last-keyboard-grab time or is later than the current X server time.
+It also generates
+<function>FocusIn </function>
+and
+<function>FocusOut </function>
+events.
+The X server automatically performs an
+<function>UngrabKeyboard </function>
+request if the event window for an
+active keyboard grab becomes not viewable.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To passively grab a single key of the keyboard, use
+<function>XGrabKey</function>.
+<indexterm><primary>Key</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>keys</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabKey</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGrabKey</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> keycode</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode or
+<function>AnyKey</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the keyboard events
+are to be reported as usual.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabKey</function>
+function establishes a passive grab on the keyboard.
+In the future,
+the keyboard is actively grabbed (as for
+<function>XGrabKeyboard</function>),
+the last-keyboard-grab time is set to the time at which the key was pressed
+(as transmitted in the
+<function>KeyPress</function>
+event), and the
+<function>KeyPress</function>
+event is reported if all of the following conditions are true:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The keyboard is not grabbed and the specified key
+(which can itself be a modifier key) is logically pressed
+when the specified modifier keys are logically down,
+and no other modifier keys are logically down.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Either the grab_window is an ancestor of (or is) the focus window,
+or the grab_window is a descendant of the focus window and contains the pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A passive grab on the same key combination does not exist
+on any ancestor of grab_window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The interpretation of the remaining arguments is as for
+<function>XGrabKeyboard</function>.
+The active grab is terminated automatically when the logical state of the
+keyboard has the specified key released
+(independent of the logical state of the modifier keys).
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+A modifiers argument of
+<function>AnyModifier</function>
+is equivalent to issuing the request for all
+possible modifier combinations (including the combination of no
+modifiers).
+It is not required that all modifiers specified have
+currently assigned KeyCodes.
+A keycode argument of
+<function>AnyKey</function>
+is equivalent to issuing
+the request for all possible KeyCodes.
+Otherwise, the specified keycode must be in
+the range specified by min_keycode and max_keycode in the connection
+setup,
+or a
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If some other client has issued a
+<function>XGrabKey</function>
+with the same key combination on the same window, a
+<function>BadAccess </function>
+error results.
+When using
+<function>AnyModifier</function>
+or
+<function>AnyKey</function>,
+the request fails completely,
+and a
+<function>BadAccess </function>
+error results (no grabs are established)
+if there is a conflicting grab for any combination.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabKey</function>
+can generate
+<function>BadAccess</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a key, use
+<function>XUngrabKey</function>.
+<indexterm><primary>Key</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm><primary>Ungrabbing</primary><secondary>keys</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabKey</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabKey</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> keycode</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode or
+<function>AnyKey</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabKey</function>
+function releases the key combination on the specified window if it was grabbed
+by this client.
+It has no effect on an active grab.
+A modifiers of
+<function>AnyModifier</function>
+is equivalent to issuing
+the request for all possible modifier combinations
+(including the combination of no modifiers).
+A keycode argument of
+<function>AnyKey</function>
+is equivalent to issuing the request for all possible key codes.
+</para>
+<para>
+<!-- .LP -->
+<function>XUngrabKey</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Resuming_Event_Processing">
+<title>Resuming Event Processing</title>
+<!-- .XS -->
+<!-- (SN Resuming Event Processing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The previous sections discussed grab mechanisms with which processing
+of events by the server can be temporarily suspended. This section
+describes the mechanism for resuming event processing.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allow further events to be processed when the device has been frozen, use
+<function>XAllowEvents</function>.
+<indexterm significance="preferred"><primary>XAllowEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAllowEvents</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> event_mode</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mode.
+You can pass
+<function>AsyncPointer</function>,
+<function>SyncPointer</function>,
+<function>AsyncKeyboard</function>,
+<function>SyncKeyboard</function>,
+<function>ReplayPointer</function>,
+<function>ReplayKeyboard</function>,
+<function>AsyncBoth</function>,
+or
+<function>SyncBoth</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllowEvents</function>
+function releases some queued events if the client has caused a device
+to freeze.
+It has no effect if the specified time is earlier than the last-grab
+time of the most recent active grab for the client or if the specified time
+is later than the current X server time.
+Depending on the event_mode argument, the following occurs:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>AsyncPointer</function></entry>
+ <entry>If the pointer is frozen by the client,
+ pointer event processing continues as usual.
+ If the pointer is frozen twice by the client on behalf of two separate grabs,
+ <function>AsyncPointer </function>
+ thaws for both.
+ <function>AsyncPointer</function>
+ has no effect if the pointer is not frozen by the client,
+ but the pointer need not be grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>SyncPointer </function></entry>
+ <entry>If the pointer is frozen and actively grabbed by the client,
+ pointer event processing continues as usual until the next
+ <function>ButtonPress </function>
+ or
+ <function>ButtonRelease </function>
+ event is reported to the client.
+ At this time,
+ the pointer again appears to freeze.
+ However, if the reported event causes the pointer grab to be released,
+ the pointer does not freeze.
+ <function>SyncPointer </function>
+ has no effect if the pointer is not frozen by the client
+ or if the pointer is not grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>ReplayPointer</function></entry>
+ <entry>If the pointer is actively grabbed by the client and is frozen as the result of
+ an event having been sent to the client (either from the activation of an
+ <function>XGrabButton </function>
+ or from a previous
+ <function>XAllowEvents </function>
+ with mode
+ <function>SyncPointer</function>
+ but not from an
+ <function>XGrabPointer</function>),
+ the pointer grab is released and that event is completely reprocessed.
+ This time, however, the function ignores any passive grabs at or above
+ (toward the root of) the grab_window of the grab just released.
+ The request has no effect if the pointer is not grabbed by the client
+ or if the pointer is not frozen as the result of an event.</entry>
+ </row>
+ <row>
+ <entry><function>AsyncKeyboard </function></entry>
+ <entry>If the keyboard is frozen by the client,
+ keyboard event processing continues as usual.
+ If the keyboard is frozen twice by the client on behalf of two separate grabs,
+ <function>AsyncKeyboard </function>
+ thaws for both.
+ <function>AsyncKeyboard </function>
+ has no effect if the keyboard is not frozen by the client,
+ but the keyboard need not be grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>SyncKeyboard</function></entry>
+ <entry>If the keyboard is frozen and actively grabbed by the client,
+ keyboard event processing continues as usual until the next
+ <function>KeyPress </function>
+ or
+ <function>KeyRelease </function>
+ event is reported to the client.
+ At this time,
+ the keyboard again appears to freeze.
+ However, if the reported event causes the keyboard grab to be released,
+ the keyboard does not freeze.
+ <function>SyncKeyboard </function>
+ has no effect if the keyboard is not frozen by the client
+ or if the keyboard is not grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>ReplayKeyboard</function></entry>
+ <entry>If the keyboard is actively grabbed by the client and is frozen
+ as the result of an event having been sent to the client (either from the
+ activation of an
+ <function>XGrabKey </function>
+ or from a previous
+ <function>XAllowEvents </function>
+ with mode
+ <function>SyncKeyboard </function>
+ but not from an
+ <function>XGrabKeyboard</function>),
+ the keyboard grab is released and that event is completely reprocessed.
+ This time, however, the function ignores any passive grabs at or above
+ (toward the root of)
+ the grab_window of the grab just released.
+ The request has no effect if the keyboard is not grabbed by the client
+ or if the keyboard is not frozen as the result of an event.</entry>
+ </row>
+ <row>
+ <entry><function>SyncBoth</function></entry>
+ <entry>If both pointer and keyboard are frozen by the client,
+ event processing for both devices continues as usual until the next
+ <function>ButtonPress</function>,
+ <function>ButtonRelease</function>,
+ <function>KeyPress</function>,
+ or
+ <function>KeyRelease </function>
+ event is reported to the client for a grabbed device
+ (button event for the pointer, key event for the keyboard),
+ at which time the devices again appear to freeze.
+ However, if the reported event causes the grab to be released,
+ then the devices do not freeze (but if the other device is still
+ grabbed, then a subsequent event for it will still cause both devices
+ to freeze).
+ <function>SyncBoth</function>
+ has no effect unless both pointer and keyboard
+ are frozen by the client.
+ If the pointer or keyboard is frozen twice
+ by the client on behalf of two separate grabs,
+ <function>SyncBoth </function>
+ thaws for both (but a subsequent freeze for
+ <function>SyncBoth </function>
+ will only freeze each device once).</entry>
+ </row>
+ <row>
+ <entry><function>AsyncBoth</function></entry>
+ <entry>If the pointer and the keyboard are frozen by the
+ client, event processing for both devices continues as usual.
+ If a device is frozen twice by the client on behalf of two separate grabs,
+ <function>AsyncBoth </function>
+ thaws for both.
+ <function>AsyncBoth </function>
+ has no effect unless both
+ pointer and keyboard are frozen by the client.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+<function>AsyncPointer</function>,
+<function>SyncPointer</function>,
+and
+<function>ReplayPointer </function>
+have no effect on the
+processing of keyboard events.
+<function>AsyncKeyboard</function>,
+<function>SyncKeyboard</function>,
+and
+<function>ReplayKeyboard </function>
+have no effect on the
+processing of pointer events.
+It is possible for both a pointer grab and a keyboard grab (by the same
+or different clients) to be active simultaneously.
+If a device is frozen on behalf of either grab,
+no event processing is performed for the device.
+It is possible for a single device to be frozen because of both grabs.
+In this case,
+the freeze must be released on behalf of both grabs before events can
+again be processed.
+If a device is frozen twice by a single client,
+then a single
+<function>AllowEvents</function>
+releases both.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllowEvents</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+</sect1>
+<sect1 id="Moving_the_Pointer">
+<title>Moving the Pointer</title>
+<!-- .XS -->
+<!-- (SN Moving the Pointer -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Although movement of the pointer normally should be left to the
+control of the end user, sometimes it is necessary to move the
+pointer to a new position under program control.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To move the pointer to an arbitrary point in a window, use
+<function>XWarpPointer</function>.
+<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XWarpPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>
+ <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+ <paramdef>unsignedintsrc_width,<parameter> src_height</parameter></paramdef>
+ <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source window or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination window or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify a rectangle in the source window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates within the destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If dest_w is
+<function>None</function>,
+<function>XWarpPointer</function>
+moves the pointer by the offsets (dest_x, dest_y) relative to the current
+position of the pointer.
+If dest_w is a window,
+<function>XWarpPointer</function>
+moves the pointer to the offsets (dest_x, dest_y) relative to the origin of
+dest_w.
+However, if src_w is a window,
+the move only takes place if the window src_w contains the pointer
+and if the specified rectangle of src_w contains the pointer.
+</para>
+<para>
+<!-- .LP -->
+The src_x and src_y coordinates are relative to the origin of src_w.
+If src_height is zero,
+it is replaced with the current height of src_w minus src_y.
+If src_width is zero,
+it is replaced with the current width of src_w minus src_x.
+</para>
+<para>
+<!-- .LP -->
+There is seldom any reason for calling this function.
+The pointer should normally be left to the user.
+If you do use this function, however, it generates events just as if the user
+had instantaneously moved the pointer from one position to another.
+Note that you cannot use
+<function>XWarpPointer</function>
+to move the pointer outside the confine_to window of an active pointer grab.
+An attempt to do so will only move the pointer as far as the closest edge of the
+confine_to window.
+</para>
+<para>
+<!-- .LP -->
+<function>XWarpPointer</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Controlling_Input_Focus">
+<title>Controlling Input Focus</title>
+<!-- .XS -->
+<!-- (SN Controlling Input Focus -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and get the input focus.
+The input focus is a shared resource, and cooperation among clients is
+required for correct interaction. See the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>
+for input focus policy.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the input focus, use
+<function>XSetInputFocus</function>.
+<indexterm significance="preferred"><primary>XSetInputFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetInputFocus</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> focus</parameter></paramdef>
+ <paramdef>int<parameter> revert_to</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>focus</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window,
+<function>PointerRoot</function>,
+or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>revert_to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies where the input focus reverts to if the window becomes not
+viewable.
+You can pass
+<function>RevertToParent</function>,
+<function>RevertToPointerRoot</function>,
+or
+<function>RevertToNone</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetInputFocus</function>
+function changes the input focus and the last-focus-change time.
+It has no effect if the specified time is earlier than the current
+last-focus-change time or is later than the current X server time.
+Otherwise, the last-focus-change time is set to the specified time
+(<function>CurrentTime </function>
+is replaced by the current X server time).
+<function>XSetInputFocus</function>
+causes the X server to generate
+<function>FocusIn </function>
+and
+<function>FocusOut </function>
+events.
+</para>
+<para>
+<!-- .LP -->
+Depending on the focus argument,
+the following occurs:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If focus is
+<function>None</function>,
+all keyboard events are discarded until a new focus window is set,
+and the revert_to argument is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If focus is a window,
+it becomes the keyboard's focus window.
+If a generated keyboard event would normally be reported to this window
+or one of its inferiors, the event is reported as usual.
+Otherwise, the event is reported relative to the focus window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If focus is
+<function>PointerRoot</function>,
+the focus window is dynamically taken to be the root window of whatever screen
+the pointer is on at each keyboard event.
+In this case, the revert_to argument is ignored.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The specified focus window must be viewable at the time
+<function>XSetInputFocus</function>
+is called,
+or a
+<function>BadMatch</function>
+error results.
+If the focus window later becomes not viewable,
+the X server
+evaluates the revert_to argument to determine the new focus window as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If revert_to is
+<function>RevertToParent</function>,
+the focus reverts to the parent (or the closest viewable ancestor),
+and the new revert_to value is taken to be
+<function>RevertToNone</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If revert_to is
+<function>RevertToPointerRoot </function>
+or
+<function>RevertToNone</function>,
+the focus reverts to
+<function>PointerRoot</function>
+or
+<function>None</function>,
+respectively.
+When the focus reverts,
+the X server generates
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events, but the last-focus-change time is not affected.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XSetInputFocus</function>
+can generate
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current input focus, use
+<function>XGetInputFocus</function>.
+<indexterm significance="preferred"><primary>XGetInputFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetInputFocus</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> *focus_return</parameter></paramdef>
+ <paramdef>int<parameter> *revert_to_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>focus_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the focus window,
+<function>PointerRoot</function>,
+or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>revert_to_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current focus state
+(<function>RevertToParent</function>,
+<function>RevertToPointerRoot</function>,
+or
+<function>RevertToNone</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetInputFocus</function>
+function returns the focus window and the current focus state.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Keyboard_and_Pointer_Settings">
+<title>Manipulating the Keyboard and Pointer Settings</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Keyboard and Pointer Settings -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to
+change the keyboard control, obtain a list of the auto-repeat keys,
+turn keyboard auto-repeat on or off, ring the bell,
+set or obtain the pointer button or keyboard mapping,
+and obtain a bit vector for the keyboard.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Keyboard</primary><secondary>bell volume</secondary></indexterm>
+<indexterm><primary>Keyboard</primary><secondary>keyclick volume</secondary></indexterm>
+<indexterm><primary>Keyboard</primary><secondary>bit vector</secondary></indexterm>
+<indexterm><primary>Mouse</primary><secondary>programming</secondary></indexterm>
+This section discusses
+the user-preference options of bell, key click,
+pointer behavior, and so on.
+The default values for many of these options are server dependent.
+Not all implementations will actually be able to control all of these
+parameters.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XChangeKeyboardControl</function>
+function changes control of a keyboard and operates on a
+<function>XKeyboardControl</function>
+structure:
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+/* Mask bits for ChangeKeyboardControl */
+
+
+#define KBBellPercent (1L<<0)
+#define KBBellPitch (1L<<1)
+#define KBBellDuration (1L<<2)
+#define KBLed (1L<<3)
+#define KBLedMode (1L<<4)
+#define KBKey (1L<<5)
+#define KBAutoRepeatMode (1L<<6)
+
+
+/* Values */
+
+typedef struct {
+int key_click_percent;
+int bell_percent;
+int bell_pitch;
+int bell_duration;
+int led;
+int led_mode; /* LedModeOn, LedModeOff */
+int key;
+int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn,
+ AutoRepeatModeDefault */
+} XKeyboardControl;
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The key_click_percent member sets the volume for key clicks between 0 (off)
+and 100 (loud) inclusive, if possible.
+A setting of -1 restores the default.
+Other negative values generate a
+<function>BadValue</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+The bell_percent sets the base volume for the bell between 0 (off) and 100
+(loud) inclusive, if possible.
+A setting of -1 restores the default.
+Other negative values generate a
+<function>BadValue</function>
+error.
+The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.
+A setting of -1 restores the default.
+Other negative values generate a
+<function>BadValue</function>
+error.
+The bell_duration member sets the duration of the
+bell specified in milliseconds, if possible.
+A setting of -1 restores the default.
+Other negative values generate a
+<function>BadValue</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+If both the led_mode and led members are specified,
+the state of that <acronym>LED</acronym> is changed, if possible.
+The led_mode member can be set to
+<function>LedModeOn</function>
+or
+<function>LedModeOff</function>.
+If only led_mode is specified, the state of
+all LEDs are changed, if possible.
+At most 32 LEDs numbered from one are supported.
+No standard interpretation of LEDs is defined.
+If led is specified without led_mode, a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If both the auto_repeat_mode and key members are specified,
+the auto_repeat_mode of that key is changed (according to
+<function>AutoRepeatModeOn</function>,
+<function>AutoRepeatModeOff</function>,
+or
+<function>AutoRepeatModeDefault</function>),
+if possible.
+If only auto_repeat_mode is
+specified, the global auto_repeat_mode for the entire keyboard is
+changed, if possible, and does not affect the per-key settings.
+If a key is specified without an auto_repeat_mode, a
+<function>BadMatch</function>
+error results.
+Each key has an individual mode of whether or not it should auto-repeat
+and a default setting for the mode.
+In addition,
+there is a global mode of whether auto-repeat should be enabled or not
+and a default setting for that mode.
+When global mode is
+<function>AutoRepeatModeOn</function>,
+keys should obey their individual auto-repeat modes.
+When global mode is
+<function>AutoRepeatModeOff</function>,
+no keys should auto-repeat.
+An auto-repeating key generates alternating
+<function>KeyPress</function>
+and
+<function>KeyRelease</function>
+events.
+When a key is used as a modifier,
+it is desirable for the key not to auto-repeat,
+regardless of its auto-repeat setting.
+</para>
+<para>
+<!-- .LP -->
+A bell generator connected with the console but not directly on a
+keyboard is treated as if it were part of the keyboard.
+The order in which controls are verified and altered is server-dependent.
+If an error is generated, a subset of the controls may have been altered.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeKeyboardControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> value_mask</parameter></paramdef>
+ <paramdef>XKeyboardControl<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which controls to change.
+This mask is the bitwise inclusive OR of the valid control mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies one value for each bit set to 1 in the mask.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeKeyboardControl</function>
+function controls the keyboard characteristics defined by the
+<function>XKeyboardControl</function>
+structure.
+The value_mask argument specifies which values are to be changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeKeyboardControl</function>
+can generate
+<function>BadMatch</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current control values for the keyboard, use
+<function>XGetKeyboardControl</function>.
+<indexterm significance="preferred"><primary>XGetKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetKeyboardControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XKeyboardState<parameter> *values_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current keyboard controls in the specified
+<function>XKeyboardState </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetKeyboardControl</function>
+function returns the current control values for the keyboard to the
+<function>XKeyboardState</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XGetKeyboardControl</primary></indexterm>
+<indexterm significance="preferred"><primary>XKeyboardState</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ int key_click_percent;
+ int bell_percent;
+ unsigned int bell_pitch, bell_duration;
+ unsigned long led_mask;
+ int global_auto_repeat;
+ char auto_repeats[32];
+} XKeyboardState;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For the LEDs,
+the least significant bit of led_mask corresponds to <acronym>LED</acronym> one,
+and each bit set to 1 in led_mask indicates an <acronym>LED</acronym> that is lit.
+The global_auto_repeat member can be set to
+<function>AutoRepeatModeOn</function>
+or
+<function>AutoRepeatModeOff</function>.
+The auto_repeats member is a bit vector.
+Each bit set to 1 indicates that auto-repeat is enabled
+for the corresponding key.
+The vector is represented as 32 bytes.
+Byte N (from 0) contains the bits for keys 8N to 8N + 7
+with the least significant bit in the byte representing key 8N.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn on keyboard auto-repeat, use
+<function>XAutoRepeatOn</function>.
+<indexterm significance="preferred"><primary>XAutoRepeatOn</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAutoRepeatOn</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAutoRepeatOn</function>
+function turns on auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn off keyboard auto-repeat, use
+<function>XAutoRepeatOff</function>.
+<indexterm significance="preferred"><primary>XAutoRepeatOff</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAutoRepeatOff</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAutoRepeatOff</function>
+function turns off auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ring the bell, use
+<function>XBell</function>.
+<indexterm significance="preferred"><primary>XBell</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XBell</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> percent</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>percent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the volume for the bell,
+which can range from -100 to 100 inclusive.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XBell</function>
+function rings the bell on the keyboard on the specified display, if possible.
+The specified volume is relative to the base volume for the keyboard.
+If the value for the percent argument is not in the range -100 to 100
+inclusive, a
+<function>BadValue</function>
+error results.
+The volume at which the bell rings
+when the percent argument is nonnegative is:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+base - [(base * percent) / 100] + percent
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The volume at which the bell rings
+when the percent argument is negative is:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+base + [(base * percent) / 100]
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To change the base volume of the bell, use
+<function>XChangeKeyboardControl</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XBell</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a bit vector that describes the state of the keyboard, use
+<function>XQueryKeymap</function>.
+<indexterm significance="preferred"><primary>XQueryKeymap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XQueryKeymap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> keys_return[32]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keys_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of bytes that identifies which keys are pressed down.
+Each bit represents one key of the keyboard.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryKeymap</function>
+function returns a bit vector for the logical state of the keyboard,
+where each bit set to 1 indicates that the corresponding key is currently
+pressed down.
+The vector is represented as 32 bytes.
+Byte N (from 0) contains the bits for keys 8N to 8N + 7
+with the least significant bit in the byte representing key 8N.
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the mapping of the pointer buttons, use
+<function>XSetPointerMapping</function>.
+<indexterm significance="preferred"><primary>XSetPointerMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XSetPointerMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> map[]</parameter></paramdef>
+ <paramdef>int<parameter> nmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>map</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetPointerMapping</function>
+function sets the mapping of the pointer.
+If it succeeds, the X server generates a
+<function>MappingNotify</function>
+event, and
+<function>XSetPointerMapping</function>
+returns
+<function>MappingSuccess</function>.
+Element map[i] defines the logical button number for the physical button
+i+1.
+The length of the list must be the same as
+<function>XGetPointerMapping</function>
+would return,
+or a
+<function>BadValue</function>
+error results.
+A zero element disables a button, and elements are not restricted in
+value by the number of physical buttons.
+However, no two elements can have the same nonzero value,
+or a
+<function>BadValue</function>
+error results.
+If any of the buttons to be altered are logically in the down state,
+<function>XSetPointerMapping</function>
+returns
+<function>MappingBusy</function>,
+and the mapping is not changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetPointerMapping</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the pointer mapping, use
+<function>XGetPointerMapping</function>.
+<indexterm significance="preferred"><primary>XGetPointerMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGetPointerMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> map_return[]</parameter></paramdef>
+ <paramdef>int<parameter> nmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>map_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPointerMapping</function>
+function returns the current mapping of the pointer.
+Pointer buttons are numbered starting from one.
+<function>XGetPointerMapping</function>
+returns the number of physical buttons actually on the pointer.
+The nominal mapping for a pointer is map[i]=i+1.
+The nmap argument specifies the length of the array where the pointer
+mapping is returned, and only the first nmap elements are returned
+in map_return.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To control the pointer's interactive feel, use
+<function>XChangePointerControl</function>.
+<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangePointerControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Booldo_accel,<parameter> do_threshold</parameter></paramdef>
+ <paramdef>intaccel_numerator,<parameter> accel_denominator</parameter></paramdef>
+ <paramdef>int<parameter> threshold</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>do_accel</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that controls whether the values for
+the accel_numerator or accel_denominator are used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>do_threshold</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that controls whether the value for the
+threshold is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_numerator</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the numerator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_denominator</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the denominator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>threshold</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the acceleration threshold.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangePointerControl</function>
+function defines how the pointing device moves.
+The acceleration, expressed as a fraction, is a
+multiplier for movement.
+For example,
+specifying 3/1 means the pointer moves three times as fast as normal.
+The fraction may be rounded arbitrarily by the X server.
+Acceleration
+only takes effect if the pointer moves more than threshold pixels at
+once and only applies to the amount beyond the value in the threshold argument.
+Setting a value to -1 restores the default.
+The values of the do_accel and do_threshold arguments must be
+<function>True </function>
+for the pointer values to be set,
+or the parameters are unchanged.
+Negative values (other than -1) generate a
+<function>BadValue</function>
+error, as does a zero value
+for the accel_denominator argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangePointerControl</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current pointer parameters, use
+<function>XGetPointerControl</function>.
+<indexterm significance="preferred"><primary>XGetPointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetPointerControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int*accel_numerator_return,<parameter> *accel_denominator_return</parameter></paramdef>
+ <paramdef>int<parameter> *threshold_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_numerator_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the numerator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_denominator_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the denominator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>threshold_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the acceleration threshold.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPointerControl</function>
+function returns the pointer's current acceleration multiplier
+and acceleration threshold.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Keyboard_Encoding">
+<title>Manipulating the Keyboard Encoding</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Keyboard Encoding -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A KeyCode represents a physical (or logical) key.
+KeyCodes lie in the inclusive range [8,255].
+A KeyCode value carries no intrinsic information,
+although server implementors may attempt to encode geometry
+(for example, matrix) information in some fashion so that it can
+be interpreted in a server-dependent fashion.
+The mapping between keys and KeyCodes cannot be changed.
+</para>
+<para>
+<!-- .LP -->
+A KeySym is an encoding of a symbol on the cap of a key.
+The set of defined KeySyms includes the ISO Latin character sets (1-4),
+Katakana, Arabic, Cyrillic, Greek, Technical,
+Special, Publishing, APL, Hebrew, Thai, Korean
+and a miscellany of keys found
+on keyboards (Return, Help, Tab, and so on).
+To the extent possible, these sets are derived from international
+standards.
+In areas where no standards exist,
+some of these sets are derived from Digital Equipment Corporation standards.
+The list of defined symbols can be found in
+<!-- .hN X11/keysymdef.h . -->
+Unfortunately, some C preprocessors have
+limits on the number of defined symbols.
+If you must use KeySyms not
+in the Latin 1-4, Greek, and miscellaneous classes,
+you may have to define a symbol for those sets.
+Most applications usually only include
+<!-- .hN X11/keysym.h , -->
+which defines symbols for ISO Latin 1-4, Greek, and miscellaneous.
+</para>
+<para>
+<!-- .LP -->
+A list of KeySyms is associated with each KeyCode.
+The list is intended to convey the set of symbols on the corresponding key.
+If the list (ignoring trailing
+<function>NoSymbol</function>
+entries) is
+a single KeySym ``<emphasis remap='I'>K</emphasis>'',
+then the list is treated as if it were the list
+``<emphasis remap='I'>K</emphasis> NoSymbol <emphasis remap='I'>K</emphasis> NoSymbol''.
+If the list (ignoring trailing
+<function>NoSymbol</function>
+entries) is a pair of KeySyms ``<emphasis remap='I'>K1 K2</emphasis>'',
+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K1 K2</emphasis>''.
+If the list (ignoring trailing
+<function>NoSymbol</function>
+entries) is a triple of KeySyms ``<emphasis remap='I'>K1 K2 K3</emphasis>'',
+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K3</emphasis> NoSymbol''.
+When an explicit ``void'' element is desired in the list,
+the value
+<function>VoidSymbol</function>
+can be used.
+</para>
+<para>
+<!-- .LP -->
+The first four elements of the list are split into two groups of KeySyms.
+Group 1 contains the first and second KeySyms;
+Group 2 contains the third and fourth KeySyms.
+Within each group,
+if the second element of the group is
+<function>NoSymbol</function>,
+then the group should be treated as if the second element were
+the same as the first element,
+except when the first element is an alphabetic KeySym ``<emphasis remap='I'>K</emphasis>''
+for which both lowercase and uppercase forms are defined.
+In that case,
+the group should be treated as if the first element were
+the lowercase form of ``<emphasis remap='I'>K</emphasis>'' and the second element were
+the uppercase form of ``<emphasis remap='I'>K</emphasis>''.
+</para>
+<para>
+<!-- .LP -->
+The standard rules for obtaining a KeySym from a
+<function>KeyPress</function>
+event make use of only the Group 1 and Group 2 KeySyms;
+no interpretation of other KeySyms in the list is given.
+Which group to use is determined by the modifier state.
+Switching between groups is controlled by the KeySym named MODE SWITCH,
+by attaching that KeySym to some KeyCode and attaching
+that KeyCode to any one of the modifiers
+<function>Mod1</function>
+through
+<function>Mod5</function>.
+This modifier is called the <emphasis remap='I'>group modifier</emphasis>.
+For any KeyCode,
+Group 1 is used when the group modifier is off,
+and Group 2 is used when the group modifier is on.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>Lock</function>
+modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+<function>Lock</function>
+modifier. The
+<function>Lock</function>
+modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+<function>Lock </function>
+modifier. If the
+<function>Lock </function>
+modifier could be interpreted as both
+CapsLock and ShiftLock, the CapsLock interpretation is used.
+</para>
+<para>
+<!-- .LP -->
+The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,
+by attaching that KeySym to some KeyCode and attaching that KeyCode to any
+one of the modifiers
+<function>Mod1 </function>
+through
+<function>Mod5</function>.
+This modifier is called the
+<emphasis remap='I'>numlock modifier</emphasis>. The standard KeySyms with the prefix ``XK_KP_''
+in their
+name are called keypad KeySyms; these are KeySyms with numeric value in
+the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition,
+vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF
+are also keypad KeySyms.
+</para>
+<para>
+<!-- .LP -->
+Within a group, the choice of KeySym is determined by applying the first
+rule that is satisfied from the following list:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The numlock modifier is on and the second KeySym is a keypad KeySym. In
+this case, if the
+<function>Shift </function>
+modifier is on, or if the
+<function>Lock </function>
+modifier is on and
+is interpreted as ShiftLock, then the first KeySym is used, otherwise the
+second KeySym is used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+and
+<function>Lock </function>
+modifiers are both off. In this case, the first
+KeySym is used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+modifier is off, and the
+<function>Lock </function>
+modifier is on and is
+interpreted as CapsLock. In this case, the first KeySym is used, but if
+that KeySym is lowercase alphabetic, then the corresponding uppercase
+KeySym is used instead.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+modifier is on, and the
+<function>Lock </function>
+modifier is on and is interpreted
+as CapsLock. In this case, the second KeySym is used, but if that KeySym
+is lowercase alphabetic, then the corresponding uppercase KeySym is used
+instead.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+modifier is on, or the
+<function>Lock </function>
+modifier is on and is interpreted
+as ShiftLock, or both. In this case, the second KeySym is used.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+No spatial geometry of the symbols on the key is defined by
+their order in the KeySym list,
+although a geometry might be defined on a
+server-specific basis.
+The X server does not use the mapping between KeyCodes and KeySyms.
+Rather, it merely stores it for reading and writing by clients.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the legal KeyCodes for a display, use
+<function>XDisplayKeycodes</function>.
+<indexterm significance="preferred"><primary>XDisplayKeycodes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDisplayKeycodes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int*min_keycodes_return,<parameter> *max_keycodes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_keycodes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the minimum number of KeyCodes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_keycodes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum number of KeyCodes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayKeycodes</function>
+function returns the min-keycodes and max-keycodes supported by the
+specified display.
+The minimum number of KeyCodes returned is never less than 8,
+and the maximum number of KeyCodes returned is never greater than 255.
+Not all KeyCodes in this range are required to have corresponding keys.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the symbols for the specified KeyCodes, use
+<function>XGetKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XGetKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>KeySym<function> *XGetKeyboardMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>KeyCode<parameter> first_keycode</parameter></paramdef>
+ <paramdef>int<parameter> keycode_count</parameter></paramdef>
+ <paramdef>int<parameter> *keysyms_per_keycode_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Kc returned -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>first_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeyCode that is to be (Kc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeyCodes that are to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms_per_keycode_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of KeySyms per KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetKeyboardMapping</function>
+function returns the symbols for the specified number of KeyCodes
+starting with first_keycode.
+The value specified in first_keycode must be greater than
+or equal to min_keycode as returned by
+<function>XDisplayKeycodes</function>,
+or a
+<function>BadValue </function>
+error results.
+In addition, the following expression must be less than or equal
+to max_keycode as returned by
+<function>XDisplayKeycodes :</function>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+first_keycode + keycode_count - 1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If this is not the case, a
+<function>BadValue </function>
+error results.
+The number of elements in the KeySyms list is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+keycode_count * keysyms_per_keycode_return
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+KeySym number N, counting from zero, for KeyCode K has the following index
+in the list, counting from zero:
+<literallayout class="monospaced">
+(K - first_code) * keysyms_per_code_return + N
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The X server arbitrarily chooses the keysyms_per_keycode_return value
+to be large enough to report all requested symbols.
+A special KeySym value of
+<function>NoSymbol </function>
+is used to fill in unused elements for
+individual KeyCodes.
+To free the storage returned by
+<function>XGetKeyboardMapping</function>,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetKeyboardMapping</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the keyboard mapping, use
+<function>XChangeKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XChangeKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeKeyboardMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> first_keycode</parameter></paramdef>
+ <paramdef>int<parameter> keysyms_per_keycode</parameter></paramdef>
+ <paramdef>KeySym<parameter> *keysyms</parameter></paramdef>
+ <paramdef>int<parameter> num_codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Kc changed -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>first_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeyCode that is to be (Kc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms_per_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeySyms per KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of KeySyms.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_codes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeyCodes that are to be changed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeKeyboardMapping</function>
+function defines the symbols for the specified number of KeyCodes
+starting with first_keycode.
+The symbols for KeyCodes outside this range remain unchanged.
+The number of elements in keysyms must be:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+num_codes * keysyms_per_keycode
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The specified first_keycode must be greater than or equal to min_keycode
+returned by
+<function>XDisplayKeycodes</function>,
+or a
+<function>BadValue </function>
+error results.
+In addition, the following expression must be less than or equal to
+max_keycode as returned by
+<function>XDisplayKeycodes</function>,
+or a
+<function>BadValue </function>
+error results:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+first_keycode + num_codes - 1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+KeySym number N, counting from zero, for KeyCode K has the following index
+in keysyms, counting from zero:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(K - first_keycode) * keysyms_per_keycode + N
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The specified keysyms_per_keycode can be chosen arbitrarily by the client
+to be large enough to hold all desired symbols.
+A special KeySym value of
+<function>NoSymbol </function>
+should be used to fill in unused elements
+for individual KeyCodes.
+It is legal for
+<function>NoSymbol </function>
+to appear in nontrailing positions
+of the effective list for a KeyCode.
+<function>XChangeKeyboardMapping</function>
+generates a
+<function>MappingNotify </function>
+event.
+</para>
+<para>
+<!-- .LP -->
+There is no requirement that the X server interpret this mapping.
+It is merely stored for reading and writing by clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeKeyboardMapping</function>
+can generate
+<function>BadAlloc </function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+The next six functions make use of the
+<function>XModifierKeymap</function>
+data structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XModifierKeymap</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int max_keypermod; /* This server's max number of keys per modifier */
+ KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */
+} XModifierKeymap;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To create an
+<function>XModifierKeymap</function>
+structure, use
+<function>XNewModifiermap</function>.
+<indexterm significance="preferred"><primary>XNewModifiermap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XNewModifiermap</function></funcdef>
+ <paramdef>int<parameter> max_keys_per_mod</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_keys_per_mod</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeyCode entries preallocated to the modifiers
+in the map.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNewModifiermap</function>
+function returns a pointer to
+<function>XModifierKeymap</function>
+structure for later use.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a new entry to an
+<function>XModifierKeymap</function>
+structure, use
+<function>XInsertModifiermapEntry</function>.
+<indexterm significance="preferred"><primary>XInsertModifiermapEntry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XInsertModifiermapEntry</function></funcdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+ <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>
+ <paramdef>int<parameter> modifier</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode_entry</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifier.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInsertModifiermapEntry</function>
+function adds the specified KeyCode to the set that controls the specified
+modifier and returns the resulting
+<function>XModifierKeymap</function>
+structure (expanded as needed).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry from an
+<function>XModifierKeymap</function>
+structure, use
+<function>XDeleteModifiermapEntry</function>.
+<indexterm significance="preferred"><primary>XDeleteModifiermapEntry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XDeleteModifiermapEntry</function></funcdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+ <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>
+ <paramdef>int<parameter> modifier</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode_entry</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifier.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteModifiermapEntry</function>
+function deletes the specified KeyCode from the set that controls the
+specified modifier and returns a pointer to the resulting
+<function>XModifierKeymap</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an
+<function>XModifierKeymap</function>
+structure, use
+<function>XFreeModifiermap</function>.
+<indexterm significance="preferred"><primary>XFreeModifiermap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeModifiermap</function></funcdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeModifiermap</function>
+function frees the specified
+<function>XModifierKeymap</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the KeyCodes to be used as modifiers, use
+<function>XSetModifierMapping</function>.
+<indexterm significance="preferred"><primary>XSetModifierMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XSetModifierMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetModifierMapping</function>
+function specifies the KeyCodes of the keys (if any) that are to be used
+as modifiers.
+If it succeeds,
+the X server generates a
+<function>MappingNotify</function>
+event, and
+<function>XSetModifierMapping</function>
+returns
+<function>MappingSuccess</function>.
+X permits at most 8 modifier keys.
+If more than 8 are specified in the
+<function>XModifierKeymap</function>
+structure, a
+<function>BadLength</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The modifiermap member of the
+<function>XModifierKeymap</function>
+structure contains 8 sets of max_keypermod KeyCodes,
+one for each modifier in the order
+<function>Shift</function>,
+<function>Lock</function>,
+<function>Control</function>,
+<function>Mod1</function>,
+<function>Mod2</function>,
+<function>Mod3</function>,
+<function>Mod4</function>,
+and
+<function>Mod5</function>.
+Only nonzero KeyCodes have meaning in each set,
+and zero KeyCodes are ignored.
+In addition, all of the nonzero KeyCodes must be in the range specified by
+min_keycode and max_keycode in the
+<function>Display </function>
+structure,
+or a
+<function>BadValue </function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+An X server can impose restrictions on how modifiers can be changed,
+for example,
+if certain keys do not generate up transitions in hardware,
+if auto-repeat cannot be disabled on certain keys,
+or if multiple modifier keys are not supported.
+If some such restriction is violated,
+the status reply is
+<function>MappingFailed</function>,
+and none of the modifiers are changed.
+If the new KeyCodes specified for a modifier differ from those
+currently defined and any (current or new) keys for that modifier are
+in the logically down state,
+<function>XSetModifierMapping</function>
+returns
+<function>MappingBusy</function>,
+and none of the modifiers is changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetModifierMapping</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the KeyCodes used as modifiers, use
+<function>XGetModifierMapping</function>.
+<indexterm significance="preferred"><primary>XGetModifierMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XGetModifierMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetModifierMapping</function>
+function returns a pointer to a newly created
+<function>XModifierKeymap</function>
+structure that contains the keys being used as modifiers.
+The structure should be freed after use by calling
+<function>XFreeModifiermap</function>.
+If only zero values appear in the set for any modifier,
+that modifier is disabled.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH13 b/libX11/specs/libX11/CH13 deleted file mode 100644 index ed143c690..000000000 --- a/libX11/specs/libX11/CH13 +++ /dev/null @@ -1,7673 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 13\fP\s-1 - -\s+1\fBLocales and Internationalized Text Functions\fP\s-1 -.sp 2 -.nr H1 13 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 13: Locales and Internationalized Text Functions -.XE -An internationalized application is one that is adaptable to the requirements -of different native languages, local customs, and character string encodings. -The process of adapting the operation to a particular native language, -local custom, or string encoding is called \fIlocalization\fP\^. -A goal of internationalization is to permit localization -without program source modifications or recompilation. -.LP -As one of the localization mechanisms, -Xlib provides an X Input Method -.Pn ( XIM ) -functional interface for internationalized text input -and an X Output Method -.Pn ( XOM ) -functional interface for internationalized text output. -.LP -Internationalization in X is based on the concept of a \fIlocale\fP. -A locale defines the localized behavior of a program at run time. -Locales affect Xlib in its: -.IP \(bu 5 -Encoding and processing of input method text -.IP \(bu 5 -Encoding of resource files and values -.IP \(bu 5 -Encoding and imaging of text strings -.IP \(bu 5 -Encoding and decoding for inter-client text communication -.LP -Characters from various languages are represented in a computer -using an encoding. -Different languages have different encodings, -and there are even different encodings for the same characters -in the same language. -.LP -This chapter defines support for localized text imaging and text input -and describes the locale mechanism that controls all locale-dependent -Xlib functions. -Sets of functions are provided for multibyte (char *) text as well as -wide character (wchar_t) text in the form supported -by the host C language environment. -The multibyte and wide character functions -are equivalent except for the form of the text argument. -.LP -The Xlib internationalization functions are not meant to provide -support for multilingual applications (mixing multiple languages -within a single piece of text), but they make it possible to -implement applications that work in limited fashion with more than -one language in independent contexts. -.LP -The remainder of this chapter discusses: -.IP \(bu 5 -X locale management -.IP \(bu 5 -Locale and modifier dependencies -.IP \(bu 5 -Variable argument lists -.IP \(bu 5 -Output methods -.IP \(bu 5 -Input methods -.IP \(bu 5 -String constants -.NH 2 -X Locale Management -.XS -\*(SN X Locale Management -.XE -.LP -X supports one or more of the locales defined by the host environment. -On implementations that conform to the ANSI C library, -the locale announcement method is -.PN setlocale . -This function configures the locale operation of both -the host C library and Xlib. -The operation of Xlib is governed by the LC_CTYPE category; -this is called the \fIcurrent locale\fP. -An implementation is permitted to provide implementation-dependent -mechanisms for announcing the locale in addition to -.PN setlocale . -.LP -On implementations that do not conform to the ANSI C library, -the locale announcement method is Xlib implementation-dependent. -.LP -The mechanism by which the semantic operation of Xlib is defined -for a specific locale is implementation-dependent. -.LP -.sp -X is not required to support all the locales supported by the host. -To determine if the current locale is supported by X, use -.PN XSupportsLocale . -.IN "XSupportsLocale" "" "@DEF@" -.sM -.FD 0 -Bool XSupportsLocale\^(\|) -.FN -.LP -.eM -The -.PN XSupportsLocale -function returns -.PN True -if Xlib functions are capable of operating under the current locale. -If it returns -.PN False , -Xlib locale-dependent functions for which the -.PN XLocaleNotSupported -return status is defined will return -.PN XLocaleNotSupported . -Other Xlib locale-dependent routines will operate in the ``C'' locale. -.LP -The client is responsible for selecting its locale and X modifiers. -Clients should provide a means for the user to override the clients' -locale selection at client invocation. -Most single-display X clients operate in a single locale -for both X and the host processing environment. -They will configure the locale by calling three functions: -the host locale configuration function, -.PN XSupportsLocale , -and -.PN XSetLocaleModifiers . -.LP -The semantics of certain categories of X internationalization capabilities -can be configured by setting modifiers. -Modifiers are named by implementation-dependent and locale-specific strings. -The only standard use for this capability at present -is selecting one of several styles of keyboard input method. -.LP -.sp -To configure Xlib locale modifiers for the current locale, use -.PN XSetLocaleModifiers . -.IN "XSetLocaleModifiers" "" "@DEF@" -.sM -.FD 0 -char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^) -.br - char *\fImodifier_list\fP\^; -.FN -.IP \fImodifier_list\fP 1i -Specifies the modifiers. -.LP -.eM -The -.PN XSetLocaleModifiers -function sets the X modifiers for the current locale setting. -The modifier_list argument is a null-terminated string of the form -``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is, -having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^'' -entries, where \fIcategory\fP is a category name -and \fIvalue\fP is the (possibly empty) setting for that category. -The values are encoded in the current locale. -Category names are restricted to the POSIX Portable Filename Character Set. -.LP -The local host X locale modifiers announcer (on POSIX-compliant systems, -the XMODIFIERS environment variable) is appended to the modifier_list to -provide default values on the local host. -If a given category appears more than once in the list, -the first setting in the list is used. -If a given category is not included in the full modifier list, -the category is set to an implementation-dependent default -for the current locale. -An empty value for a category explicitly specifies the -implementation-dependent default. -.LP -If the function is successful, it returns a pointer to a string. -The contents of the string are such that a subsequent call with that string -(in the same locale) will restore the modifiers to the same settings. -If modifier_list is a NULL pointer, -.PN XSetLocaleModifiers -also returns a pointer to such a string, -and the current locale modifiers are not changed. -.LP -If invalid values are given for one or more modifier categories supported by -the locale, a NULL pointer is returned, and none of the -current modifiers are changed. -.LP -At program startup, -the modifiers that are in effect are unspecified until -the first successful call to set them. Whenever the locale is changed, the -modifiers that are in effect become unspecified until the next successful call -to set them. -Clients should always call -.PN XSetLocaleModifiers -with a non-NULL modifier_list after setting the locale -before they call any locale-dependent Xlib routine. -.LP -The only standard modifier category currently defined is ``im'', -which identifies the desired input method. -The values for input method are not standardized. -A single locale may use multiple input methods, -switching input method under user control. -The modifier may specify the initial input method in effect -or an ordered list of input methods. -Multiple input methods may be specified in a single im value string -in an implementation-dependent manner. -.LP -The returned modifiers string is owned by Xlib and should not be modified or -freed by the client. -It may be freed by Xlib after the current locale or modifiers are changed. -Until freed, it will not be modified by Xlib. -.LP -The recommended procedure for clients initializing their locale and modifiers -is to obtain locale and modifier announcers separately from -one of the following prioritized sources: -.IP \(bu 5 -A command line option -.IP \(bu 5 -A resource -.IP \(bu 5 -The empty string ("\^") -.LP -The first of these that is defined should be used. -Note that when a locale command line option or locale resource is defined, -the effect should be to set all categories to the specified locale, -overriding any category-specific settings in the local host environment. -.NH 2 -Locale and Modifier Dependencies -.XS -\*(SN Locale and Modifier Dependencies -.XE -.LP -The internationalized Xlib functions operate in the current locale -configured by the host environment and X locale modifiers set by -.PN XSetLocaleModifiers -or in the locale and modifiers configured at the time -some object supplied to the function was created. -For each locale-dependent function, -the following table describes the locale (and modifiers) dependency: -.TS H -lw(1.25i) lw(2.5i) lw(2i). -_ -.sp 6p -.B -Locale from Affects the Function In -.sp 6p -_ -.sp 6p -.TH -.R - Locale Query/Configuration: -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XSupportsLocale -T} T{ -Locale queried -T} - T{ -.PN XSetLocaleModifiers -T} T{ -Locale modified -T} -.sp - Resources: -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XrmGetFileDatabase -T} T{ -Locale of -.PN XrmDatabase -T} - T{ -.PN XrmGetStringDatabase -T} -T{ -.PN XrmDatabase -T} T{ -.PN XrmPutFileDatabase -T} T{ -Locale of -.PN XrmDatabase -T} - T{ -.PN XrmLocaleOfDatabase -T} -.sp - Setting Standard Properties: -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XmbSetWMProperties -T} T{ -Encoding of supplied/returned -T} - text (some WM_ property - text in environment locale) -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XmbTextPropertyToTextList -T} T{ -Encoding of supplied/returned text -T} - T{ -.PN XwcTextPropertyToTextList -T} - T{ -.PN XmbTextListToTextProperty -T} - T{ -.PN XwcTextListToTextProperty -T} -.sp - Text Input: -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XOpenIM -T} T{ -XIM input method selection -T} - T{ -.PN XRegisterIMInstantiateCallback -T} T{ -XIM selection -T} - T{ -.PN XUnregisterIMInstantiateCallback -T} T{ -XIM selection -T} -T{ -.PN XIM -T} T{ -.PN XCreateIC -T} T{ -XIC input method configuration -T} - T{ -.PN XLocaleOfIM , -and so on -T} T{ -Queried locale -T} -T{ -.PN XIC -T} T{ -.PN XmbLookupString -T} T{ -Keyboard layout -T} - T{ -.PN XwcLookupString -T} T{ -Encoding of returned text -T} -.sp - Text Drawing: -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XOpenOM -T} T{ -XOM output method selection -T} - T{ -.PN XCreateFontSet -T} T{ -Charsets of fonts in -.PN XFontSet -T} -T{ -.PN XOM -T} T{ -.PN XCreateOC -T} T{ -XOC output method configuration -T} - T{ -.PN XLocaleOfOM , -and so on -T} T{ -Queried locale -T} -T{ -.PN XFontSet -T} T{ -.PN XmbDrawText , -T} T{ -Locale of supplied text -T} - T{ -.PN XwcDrawText , -and so on -T} T{ -Locale of supplied text -T} - T{ -.PN XExtentsOfFontSet , -and so on -T} T{ -Locale-dependent metrics -T} - T{ -.PN XmbTextExtents , -T} - T{ -.PN XwcTextExtents , -and so on -T} -.sp - Xlib Errors: -.sp 6p -T{ -.PN setlocale -T} T{ -.PN XGetErrorDatabaseText -T} T{ -Locale of error message -T} - T{ -.PN XGetErrorText -T} -.sp 6p -_ -.TE -.LP -Clients may assume that a locale-encoded text string returned -by an X function can be passed to a C library routine, or vice versa, -if the locale is the same at the two calls. -.LP -All text strings processed by internationalized Xlib functions are assumed -to begin in the initial state of the encoding of the locale, if the encoding -is state-dependent. -.LP -All Xlib functions behave as if they do not change the current locale -or X modifier setting. -(This means that if they do change locale or call -.PN XSetLocaleModifiers -with a non-NULL argument, they must save and restore the current state on -entry and exit.) -Also, Xlib functions on implementations that conform to the ANSI C library do -not alter the global state associated with the ANSI C functions -.PN mblen , -.PN mbtowc , -.PN wctomb , -and -.PN strtok . -.NH 2 -Variable Argument Lists -.XS -\*(SN Variable Argument Lists -.XE -.LP -Various functions in this chapter have arguments that conform -to the ANSI C variable argument list calling convention. -Each function denoted with an argument of the form ``...'' takes -a variable-length list of name and value pairs, -where each name is a string and each value is of type -.PN XPointer . -A name argument that is NULL identifies the end of the list. -.LP -A variable-length argument list may contain a nested list. -If the name -.PN XNVaNestedList -is specified in place of an argument name, -then the following value is interpreted as an -.PN XVaNestedList -value that specifies a list of values logically inserted into the -original list at the point of declaration. -A NULL identifies the end of a nested list. -.LP -.sp -To allocate a nested variable argument list dynamically, use -.PN XVaCreateNestedList . -.IN "XVaCreateNestedList" "" @DEF@" -.sM -.FD 0 -typedef void * XVaNestedList; - -XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...) -.br - int \fIdummy\fP\^; -.FN -.IP \fIdummy\fP 1i -Specifies an unused argument (required by ANSI C). -.ds Al -.IP ... 1i -Specifies the variable length argument list\*(Al. -.LP -.eM -The -.PN XVaCreateNestedList -function allocates memory and copies its arguments into -a single list pointer, -which may be used as a value for arguments requiring a list value. -Any entries are copied as specified. -Data passed by reference is not copied; -the caller must ensure data remains valid for the lifetime -of the nested list. -The list should be freed using -.PN XFree -when it is no longer needed. -.NH 2 -Output Methods -.XS -\*(SN Output Methods -.XE -.LP -This section provides discussions of the following X Output Method -(XOM) topics: -.IP \(bu 5 -Output method overview -.IP \(bu 5 -Output method functions -.IP \(bu 5 -Output method values -.IP \(bu 5 -Output context functions -.IP \(bu 5 -Output context values -.IP \(bu 5 -Creating and freeing a font set -.IP \(bu 5 -Obtaining font set metrics -.IP \(bu 5 -Drawing text using font sets -.NH 3 -Output Method Overview -.XS -\*(SN Output Method Overview -.XE -.LP -Locale-dependent text may include one or more text components, each of -which may require different fonts and character set encodings. -In some languages, each component might have a different -drawing direction, and some components might contain -context-dependent characters that change shape based on -relationships with neighboring characters. -.LP -When drawing such locale-dependent text, some locale-specific -knowledge is required; -for example, what fonts are required to draw the text, -how the text can be separated into components, and which -fonts are selected to draw each component. -Further, when bidirectional text must be drawn, -the internal representation order of the text must be changed -into the visual representation order to be drawn. -.LP -An X Output Method provides a functional interface so that clients -do not have to deal directly with such locale-dependent details. -Output methods provide the following capabilities: -.IP \(bu 5 -Creating a set of fonts required to draw locale-dependent text. -.IP \(bu 5 -Drawing locale-dependent text with a font set without the caller -needing to be aware of locale dependencies. -.IP \(bu 5 -Obtaining the escapement and extents in pixels of locale-dependent text. -.IP \(bu 5 -Determining if bidirectional or context-dependent drawing is required -in a specific locale with a specific font set. -.LP -Two different abstractions are used in the representation of -the output method for clients. -.LP -The abstraction used to communicate with an output method -is an opaque data structure represented by the -.PN XOM -data type. -The abstraction for representing the state of a particular output thread -is called an \fIoutput context\fP. -The Xlib representation of an output context is an -.PN XOC , -which is compatible with -.PN XFontSet -in terms of its functional interface, but is -a broader, more generalized abstraction. -.NH 3 -Output Method Functions -.XS -\*(SN Output Method Functions -.XE -.LP -To open an output method, use -.PN XOpenOM . -.IN "XOpenOM" "" "@DEF@" -.sM -.FD 0 -XOM XOpenOM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XrmDatabase \fIdb\fP\^; -.br - char *\fIres_name\fP\^; -.br - char *\fIres_class\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdb\fP 1i -Specifies a pointer to the resource database. -.IP \fIres_name\fP 1i -Specifies the full resource name of the application. -.IP \fIres_class\fP 1i -Specifies the full class name of the application. -.LP -.eM -The -.PN XOpenOM -function opens an output method -matching the current locale and modifiers specification. -The current locale and modifiers are bound to the output method -when -.PN XOpenOM -is called. -The locale associated with an output method cannot be changed. -.LP -The specific output method to which this call will be routed -is identified on the basis of the current locale and modifiers. -.PN XOpenOM -will identify a default output method corresponding to the -current locale. -That default can be modified using -.PN XSetLocaleModifiers -to set the output method modifier. -.LP -The db argument is the resource database to be used by the output method -for looking up resources that are private to the output method. -It is not intended that this database be used to look -up values that can be set as OC values in an output context. -If db is NULL, -no database is passed to the output method. -.LP -The res_name and res_class arguments specify the resource name -and class of the application. -They are intended to be used as prefixes by the output method -when looking up resources that are common to all output contexts -that may be created for this output method. -The characters used for resource names and classes must be in the -X Portable Character Set. -The resources looked up are not fully specified -if res_name or res_class is NULL. -.LP -The res_name and res_class arguments are not assumed to exist beyond -the call to -.PN XOpenOM . -The specified resource database is assumed to exist for the lifetime -of the output method. -.LP -.PN XOpenOM -returns NULL if no output method could be opened. -.LP -.sp -To close an output method, use -.PN XCloseOM . -.IN "XCloseOM" "" "@DEF@" -.sM -.FD 0 -Status XCloseOM\^(\^\fIom\fP\^) -.br - XOM \fIom\fP\^; -.FN -.IP \fIom\fP 1i -Specifies the output method. -.LP -.eM -The -.PN XCloseOM -function closes the specified output method. -.LP -.sp -To set output method attributes, use -.PN XSetOMValues . -.IN "XSetOMValues" "" "@DEF@" -.sM -.FD 0 -char * XSetOMValues\^(\^\fIom\fP\^, ...) -.br - XOM \fIom\fP\^; -.FN -.IP \fIom\fP 1i -Specifies the output method. -.ds Al \ to set XOM values -.IP ... 1i -Specifies the variable-length argument list\*(Al. -.LP -.eM -The -.PN XSetOMValues -function presents a variable argument list programming interface -for setting properties or features of the specified output method. -This function returns NULL if it succeeds; -otherwise, -it returns the name of the first argument that could not be obtained. -.LP -No standard arguments are currently defined by Xlib. -.LP -.sp -To query an output method, use -.PN XGetOMValues . -.IN "XGetOMValues" "" "@DEF@" -.sM -.FD 0 -char * XGetOMValues\^(\^\fIom\fP\^, ...) -.br - XOM \fIom\fP\^; -.FN -.IP \fIom\fP 1i -Specifies the output method. -.ds Al \ to get XOM values -.IP ... 1i -Specifies the variable-length argument list\*(Al. -.LP -.eM -The -.PN XGetOMValues -function presents a variable argument list programming interface -for querying properties or features of the specified output method. -This function returns NULL if it succeeds; -otherwise, -it returns the name of the first argument that could not be obtained. -.LP -To obtain the display associated with an output method, use -.PN XDisplayOfOM . -.IN "XDisplayOfOM" "" "@DEF@" -.sM -.FD 0 -Display * XDisplayOfOM\^(\^\fIom\fP\^) -.br - XOM \fIom\fP\^; -.FN -.IP \fIom\fP 1i -Specifies the output method. -.LP -.eM -The -.PN XDisplayOfOM -function returns the display associated with the specified output method. -.LP -.sp -To get the locale associated with an output method, use -.PN XLocaleOfOM . -.IN "XLocaleOfOM" "" "@DEF@" -.sM -.FD 0 -char * XLocaleOfOM\^(\^\fIom\fP\^) -.br - XOM \fIom\fP\^; -.FN -.IP \fIom\fP 1i -Specifies the output method. -.LP -.eM -The -.PN XLocaleOfOM -returns the locale associated with the specified output method. -.NH 3 -X Output Method Values -.XS -\*(SN X Output Method Values -.XE -.LP -The following table describes how XOM values are interpreted by an -output method. -The first column lists the XOM values. The second column indicates -how each of the XOM values are treated by a particular output style. -.LP -.LP -The following key applies to this table. -.TS H -lw(1i) lw(4.75i). -_ -.sp 6p -.B -Key Explanation -.sp 6p -_ -.sp 6p -.TH -.R -G T{ -This value may be read using -.PN XGetOMValues . -T} -.sp 6p -_ -.TE -.LP -.TS H -lw(2.25i) c -lw(2.25i) c. -_ -.sp 6p -.B -XOM Value Key -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN XNRequiredCharSet -T} T{ -G -T} -T{ -.PN XNQueryOrientation -T} T{ -G -T} -T{ -.PN XNDirectionalDependentDrawing -T} T{ -G -T} -T{ -.PN XNContextualDrawing -T} T{ -G -T} -.sp 6p -_ -.TE -.LP -.NH 4 -Required Char Set -.XS -\*(SN Required Char Set -.XE -.LP -The -.PN XNRequiredCharSet -argument returns the list of charsets that are required for loading the fonts -needed for the locale. -The value of the argument is a pointer to a structure of type -.PN XOMCharSetList . -.LP -The -.PN XOMCharSetList -structure is defined as follows: -.IN "XOMCharSetList" "" "@DEF@" -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int charset_count; - char **charset_list; -} XOMCharSetList; -.De -.LP -.eM -The charset_list member is a list of one or more null-terminated -charset names, and the charset_count member is the number of -charset names. -.LP -The required charset list is owned by Xlib and should not be modified or -freed by the client. -It will be freed by a call to -.PN XCloseOM -with the associated -.PN XOM . -Until freed, its contents will not be modified by Xlib. -.LP -.NH 4 -Query Orientation -.XS -\*(SN Query Orientation -.XE -.LP -The -.PN XNQueryOrientation -argument returns the global orientation of text when drawn. -Other than -.PN XOMOrientation_LTR_TTB , -the set of orientations supported is locale-dependent. -The value of the argument is a pointer to a structure of type -.PN XOMOrientation . -Clients are responsible for freeing the -.PN XOMOrientation -structure by using -.PN XFree ; -this also frees the contents of the structure. -.LP -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int num_orientation; - XOrientation *orientation; /* Input Text description */ -} XOMOrientation; - -typedef enum { - XOMOrientation_LTR_TTB, - XOMOrientation_RTL_TTB, - XOMOrientation_TTB_LTR, - XOMOrientation_TTB_RTL, - XOMOrientation_Context -} XOrientation; -.De -.LP -.eM -The possible value for XOrientation may be: -.IP \(bu 5 -.PN XOMOrientation_LTR_TTB -left-to-right, top-to-bottom global orientation -.IP \(bu 5 -.PN XOMOrientation_RTL_TTB -right-to-left, top-to-bottom global orientation -.IP \(bu 5 -.PN XOMOrientation_TTB_LTR -top-to-bottom, left-to-right global orientation -.IP \(bu 5 -.PN XOMOrientation_TTB_RTL -top-to-bottom, right-to-left global orientation -.IP \(bu 5 -.PN XOMOrientation_Context -contextual global orientation -.LP -.NH 4 -Directional Dependent Drawing -.XS -\*(SN Directional Dependent Drawing -.XE -.LP -The -.PN XNDirectionalDependentDrawing -argument indicates whether the text rendering functions -implement implicit handling of directional text. If this value -is -.PN True , -the output method has knowledge of directional -dependencies and reorders text as necessary when -rendering text. If this value is -.PN False , -the output method does not implement any directional text -handling, and all character directions are assumed to be left-to-right. -.LP -Regardless of the rendering order of characters, -the origins of all characters are on the primary draw direction side -of the drawing origin. -.LP -This OM value presents functionality identical to the -.PN XDirectionalDependentDrawing -function. -.NH 4 -Context Dependent Drawing -.XS -\*(SN Context Dependent Drawing -.XE -.LP -The -.PN XNContextualDrawing -argument indicates whether the text rendering functions -implement implicit context-dependent drawing. If this value is -.PN True , -the output method has knowledge of context dependencies and -performs character shape editing, combining glyphs to present -a single character as necessary. The actual shape editing is -dependent on the locale implementation and the font set used. -.LP -This OM value presents functionality identical to the -.PN XContextualDrawing -function. -.NH 3 -Output Context Functions -.XS -\*(SN Output Context Functions -.XE -.LP -An output context is an abstraction that contains both the data -required by an output method and the information required -to display that data. -There can be multiple output contexts for one output method. -The programming interfaces for creating, reading, or modifying -an output context use a variable argument list. -The name elements of the argument lists are referred to as XOC values. -It is intended that output methods be controlled by these XOC values. -As new XOC values are created, -they should be registered with the X Consortium. -An -.PN XOC -can be used anywhere an -.PN XFontSet -can be used, and vice versa; -.PN XFontSet -is retained for compatibility with previous releases. -The concepts of output methods and output contexts include broader, -more generalized abstraction than font set, -supporting complex and more intelligent text display, and dealing not only -with multiple fonts but also with context dependencies. -However, -.PN XFontSet -is widely used in several interfaces, so -.PN XOC -is defined as an upward compatible type of -.PN XFontSet . -.LP -.sp -To create an output context, use -.PN XCreateOC . -.IN "XCreateOC" "" "@DEF@" -.sM -.FD 0 -XOC XCreateOC\^(\^\fIom\fP\^, ...) -.br - XOM \fIom\fP\^; -.FN -.IP \fIom\fP 1i -Specifies the output method. -.ds Al \ to set XOC values -.IP ... 1i -Specifies the variable-length argument list\*(Al. -.LP -.eM -The -.PN XCreateOC -function creates an output context within the specified output method. -.LP -The base font names argument is mandatory at creation time, and -the output context will not be created unless it is provided. -All other output context values can be set later. -.LP -.PN XCreateOC -returns NULL if no output context could be created. -NULL can be returned for any of the following reasons: -.IP \(bu 5 -A required argument was not set. -.IP \(bu 5 -A read-only argument was set. -.IP \(bu 5 -An argument name is not recognized. -.IP \(bu 5 -The output method encountered an output method implementation-dependent error. -.LP -.PN XCreateOC -can generate a -.PN BadAtom -error. -.LP -.sp -To destroy an output context, use -.PN XDestroyOC . -.IN "XDestroyOC" "" "@DEF@" -.sM -.FD 0 -void XDestroyOC\^(\^\fIoc\fP\^) -.br - XOC \fIoc\fP\^; -.FN -.IP \fIoc\fP 1i -Specifies the output context. -.LP -.eM -The -.PN XDestroyOC -function destroys the specified output context. -.LP -.sp -To get the output method associated with an output context, use -.PN XOMOfOC . -.IN "XOMOfOC" "" "@DEF@" -.sM -.FD 0 -XOM XOMOfOC\^(\^\fIoc\fP\^) -.br - XOC \fIoc\fP\^; -.FN -.IP \fIoc\fP 1i -Specifies the output context. -.LP -.eM -The -.PN XOMOfOC -function returns the output method associated with the -specified output context. -.LP -.sp -Xlib provides two functions for setting and reading output context values, -respectively, -.PN XSetOCValues -and -.PN XGetOCValues . -Both functions have a variable-length argument list. -In that argument list, any XOC value's name must be denoted -with a character string using the X Portable Character Set. -.LP -.sp -To set XOC values, use -.PN XSetOCValues . -.IN "XSetOCValues" "" "@DEF@" -.sM -.FD 0 -char * XSetOCValues\^(\^\fIoc\fP\^, ...) -.br - XOC \fIoc\fP\^; -.FN -.IP \fIoc\fP 1i -Specifies the output context. -.ds Al \ to set XOC values -.IP ... 1i -Specifies the variable-length argument list\*(Al. -.LP -.eM -The -.PN XSetOCValues -function returns NULL if no error occurred; -otherwise, -it returns the name of the first argument that could not be set. -An argument might not be set for any of the following reasons: -.IP \(bu 5 -The argument is read-only. -.IP \(bu 5 -The argument name is not recognized. -.IP \(bu 5 -An implementation-dependent error occurs. -.LP -Each value to be set must be an appropriate datum, -matching the data type imposed by the semantics of the argument. -.LP -.PN XSetOCValues -can generate a -.PN BadAtom -error. -.LP -.sp -To obtain XOC values, use -.PN XGetOCValues . -.IN "XGetOCValues" "" "@DEF@" -.sM -.FD 0 -char * XGetOCValues\^(\^\fIoc\fP\^, ...) -.br - XOC \fIoc\fP\^; -.FN -.IP \fIoc\fP 1i -Specifies the output context. -.ds Al \ to get XOC values -.IP ... 1i -Specifies the variable-length argument list\*(Al. -.LP -.eM -The -.PN XGetOCValues -function returns NULL if no error occurred; otherwise, -it returns the name of the first argument that could not be obtained. -An argument might not be obtained for any of the following reasons: -.IP \(bu 5 -The argument name is not recognized. -.IP \(bu 5 -An implementation-dependent error occurs. -.LP -Each argument value -following a name must point to a location where the value is to be stored. -.NH 3 -Output Context Values -.XS -\*(SN Output Context Values -.XE -.LP -The following table describes how XOC values are interpreted -by an output method. -The first column lists the XOC values. -The second column indicates the alternative interfaces that function -identically and are provided for compatibility with previous releases. -The third column indicates how each of the XOC values is treated. -.LP -The following keys apply to this table. -.TS H -lw(1i) lw(4.75i). -_ -.sp 6p -.B -Key Explanation -.sp 6p -_ -.TH -.R -C T{ -This value must be set with -.PN XCreateOC . -T} -D T{ -This value may be set using -.PN XCreateOC . -If it is not set, -.br -a default is provided. -T} -G T{ -This value may be read using -.PN XGetOCValues . -T} -S T{ -This value must be set using -.PN XSetOCValues . -T} -.sp 6p -_ -.TE -.LP -.TS H -l c c -l c c. -_ -.sp 6p -.B -XOC Value Alternative Interface Key -.sp 6p -_ -.sp 6p -.TH -.R -T{ -BaseFontName -T} T{ -.PN XCreateFontSet -T} T{ -C-G -T} -T{ -MissingCharSet -T} T{ -.PN XCreateFontSet -T} T{ -G -T} -T{ -DefaultString -T} T{ -.PN XCreateFontSet -T} T{ -G -T} -T{ -Orientation -T} T{ -\- -T} T{ -D-S-G -T} -T{ -ResourceName -T} T{ -\- -T} T{ -S-G -T} -T{ -ResourceClass -T} T{ -\- -T} T{ -S-G -T} -T{ -FontInfo -T} T{ -.PN XFontsOfFontSet -T} T{ -G -T} -T{ -OMAutomatic -T} T{ -\- -T} T{ -G -T} -.sp 6p -_ -.TE -.LP -.NH 4 -Base Font Name -.XS -\*(SN Base Font Name -.XE -.LP -The -.PN XNBaseFontName -argument is a list of base font names that Xlib uses -to load the fonts needed for the locale. -The base font names are a comma-separated list. The string is null-terminated -and is assumed to be in the Host Portable Character Encoding; -otherwise, the result is implementation-dependent. -White space immediately on either side of a separating comma is ignored. -.LP -Use of XLFD font names permits Xlib to obtain the fonts needed for a -variety of locales from a single locale-independent base font name. -The single base font name should name a family of fonts whose members -are encoded in the various charsets needed by the locales of interest. -.LP -An XLFD base font name can explicitly name a charset needed for the locale. -This allows the user to specify an exact font for use with a charset required -by a locale, fully controlling the font selection. -.LP -If a base font name is not an XLFD name, -Xlib will attempt to obtain an XLFD name from the font properties -for the font. -If Xlib is successful, the -.PN XGetOCValues -function will return this XLFD name instead of the client-supplied name. -.LP -This argument must be set at creation time -and cannot be changed. -If no fonts exist for any of the required charsets, -or if the locale definition in Xlib requires that a font exist -for a particular charset and a font is not found for that charset, -.PN XCreateOC -returns NULL. -.LP -When querying for the -.PN XNBaseFontName -XOC value, -.PN XGetOCValues -returns a null-terminated string identifying the base font names that -Xlib used to load the fonts needed for the locale. -This string is owned by Xlib and should not be modified or freed by -the client. -The string will be freed by a call to -.PN XDestroyOC -with the associated -.PN XOC . -Until freed, the string contents will not be modified by Xlib. -.NH 4 -Missing CharSet -.XS -\*(SN Missing CharSet -.XE -.LP -The -.PN XNMissingCharSet -argument returns the list of required charsets that are missing from the -font set. -The value of the argument is a pointer to a structure of type -.PN XOMCharSetList . -.LP -If fonts exist for all of the charsets required by the current locale, -charset_list is set to NULL and charset_count is set to zero. -If no fonts exist for one or more of the required charsets, -charset_list is set to a list of one or more null-terminated charset names -for which no fonts exist, and charset_count is set to the number of -missing charsets. -The charsets are from the list of the required charsets for -the encoding of the locale and do not include any charsets to which Xlib -may be able to remap a required charset. -.LP -The missing charset list is owned by Xlib and should not be modified or -freed by the client. -It will be freed by a call to -.PN XDestroyOC -with the associated -.PN XOC . -Until freed, its contents will not be modified by Xlib. -.NH 4 -Default String -.XS -\*(SN Default String -.XE -.LP -When a drawing or measuring function is called with an -.PN XOC -that has missing charsets, some characters in the locale will not be -drawable. -The -.PN XNDefaultString -argument returns a pointer to a string that represents the glyphs -that are drawn with this -.PN XOC -when the charsets of the available fonts do not include all glyphs -required to draw a character. -The string does not necessarily consist of valid characters -in the current locale and is not necessarily drawn with -the fonts loaded for the font set, -but the client can draw or measure the default glyphs -by including this string in a string being drawn or measured with the -.PN XOC . -.LP -If the -.PN XNDefaultString -argument returned the empty string ("\^"), -no glyphs are drawn and the escapement is zero. -The returned string is null-terminated. -It is owned by Xlib and should not be modified or freed by the client. -It will be freed by a call to -.PN XDestroyOC -with the associated -.PN XOC . -Until freed, its contents will not be modified by Xlib. -.NH 4 -Orientation -.XS -\*(SN Orientation -.XE -.LP -The -.PN XNOrientation -argument specifies the current orientation of text when drawn. The value of -this argument is one of the values returned by the -.PN XGetOMValues -function with the -.PN XNQueryOrientation -argument specified in the -.PN XOrientation -list. -The value of the argument is of type -.PN XOrientation . -When -.PN XNOrientation -is queried, the value specifies the current orientation. -When -.PN XNOrientation -is set, a value is used to set the current orientation. -.LP -When -.PN XOMOrientation_Context -is set, the text orientation of the -text is determined according to an implementation-defined method -(for example, ISO 6429 control sequences), and the initial text orientation for -locale-dependent Xlib functions is assumed to -be -.PN XOMOrientation_LTR_TTB . -.LP -The -.PN XNOrientation -value does not change the prime drawing direction -for Xlib drawing functions. -.NH 4 -Resource Name and Class -.XS -\*(SN Resource Name and Class -.XE -.LP -The -.PN XNResourceName -and -.PN XNResourceClass -arguments are strings that specify the full name and class -used by the client to obtain resources for the display of the output context. -These values should be used as prefixes for name and class -when looking up resources that may vary according to the output context. -If these values are not set, -the resources will not be fully specified. -.LP -It is not intended that values that can be set as XOM values be -set as resources. -.LP -When querying for the -.PN XNResourceName -or -.PN XNResourceClass -XOC value, -.PN XGetOCValues -returns a null-terminated string. -This string is owned by Xlib and should not be modified or freed by -the client. -The string will be freed by a call to -.PN XDestroyOC -with the associated -.PN XOC -or when the associated value is changed via -.PN XSetOCValues . -Until freed, the string contents will not be modified by Xlib. -.NH 4 -Font Info -.XS -\*(SN Font Info -.XE -.LP -The -.PN XNFontInfo -argument specifies a list of one or more -.PN XFontStruct -structures -and font names for the fonts used for drawing by the given output context. -The value of the argument is a pointer to a structure of type -.PN XOMFontInfo . -.LP -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int num_font; - XFontStruct **font_struct_list; - char **font_name_list; -} XOMFontInfo; -.De -.LP -.eM -A list of pointers to the -.PN XFontStruct -structures is returned to font_struct_list. -A list of pointers to null-terminated, fully-specified font name strings -in the locale of the output context is returned to font_name_list. -The font_name_list order corresponds to the font_struct_list order. -The number of -.PN XFontStruct -structures and font names is returned to num_font. -.LP -Because it is not guaranteed that a given character will be imaged using a -single font glyph, -there is no provision for mapping a character or default string -to the font properties, font ID, or direction hint for the font -for the character. -The client may access the -.PN XFontStruct -list to obtain these values for all the fonts currently in use. -.LP -Xlib does not guarantee that fonts are loaded from the server -at the creation of an -.PN XOC . -Xlib may choose to cache font data, loading it only as needed to draw text -or compute text dimensions. -Therefore, existence of the per_char metrics in the -.PN XFontStruct -structures in the -.PN XFontStructSet -is undefined. -Also, note that all properties in the -.PN XFontStruct -structures are in the STRING encoding. -.LP -The client must not free the -.PN XOMFontInfo -struct itself; it will be freed when the -.PN XOC -is closed. -.NH 4 -OM Automatic -.XS -\*(SN OM Automatic -.XE -.LP -The -.PN XNOMAutomatic -argument returns whether the associated output context was created by -.PN XCreateFontSet -or not. Because the -.PN XFreeFontSet -function not only destroys the output context but also closes the implicit -output method associated with it, -.PN XFreeFontSet -should be used with any output context created by -.PN XCreateFontSet . -However, it is possible that a client does not know how the output context -was created. -Before a client destroys the output context, -it can query whether -.PN XNOMAutomatic -is set to determine whether -.PN XFreeFontSet -or -.PN XDestroyOC -should be used to destroy the output context. -.NH 3 -Creating and Freeing a Font Set -.XS -\*(SN Creating and Freeing a Font Set -.XE -.LP -Xlib international text drawing is done using a set of one or more fonts, -as needed for the locale of the text. -Fonts are loaded according to a list of base font names -supplied by the client and the charsets required by the locale. -The -.PN XFontSet -is an opaque type representing the state of a particular output thread -and is equivalent to the type -.PN XOC . -.LP -.sp -The -.PN XCreateFontSet -function is a convenience function for creating an output context using -only default values. The returned -.PN XFontSet -has an implicitly created -.PN XOM . -This -.PN XOM -has an OM value -.PN XNOMAutomatic -automatically set to -.PN True -so that the output context self indicates whether it was created by -.PN XCreateOC -or -.PN XCreateFontSet . -.IN "XCreateFontSet" "" "@DEF@" -.sM -.FD 0 -XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^, -.br - \fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIbase_font_name_list\fP\^; -.br - char ***\fImissing_charset_list_return\fP\^; -.br - int *\fImissing_charset_count_return\fP\^; -.br - char **\fIdef_string_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIbase_font_name_list\fP 1i -Specifies the base font names. -.IP \fImissing_charset_list_return\fP 1i -Returns the missing charsets. -.IP \fImissing_charset_count_return\fP 1i -Returns the number of missing charsets. -.IP \fIdef_string_return\fP 1i -Returns the string drawn for missing charsets. -.LP -.eM -The -.PN XCreateFontSet -function creates a font set for the specified display. -The font set is bound to the current locale when -.PN XCreateFontSet -is called. -The font set may be used in subsequent calls to obtain font -and character information and to image text in the locale of the font set. -.LP -The base_font_name_list argument is a list of base font names -that Xlib uses to load the fonts needed for the locale. -The base font names are a comma-separated list. -The string is null-terminated -and is assumed to be in the Host Portable Character Encoding; -otherwise, the result is implementation-dependent. -White space immediately on either side of a separating comma is ignored. -.LP -Use of XLFD font names permits Xlib to obtain the fonts needed for a -variety of locales from a single locale-independent base font name. -The single base font name should name a family of fonts whose members -are encoded in the various charsets needed by the locales of interest. -.LP -An XLFD base font name can explicitly name a charset needed for the locale. -This allows the user to specify an exact font for use with a charset required -by a locale, fully controlling the font selection. -.LP -If a base font name is not an XLFD name, -Xlib will attempt to obtain an XLFD name from the font properties -for the font. -If this action is successful in obtaining an XLFD name, the -.PN XBaseFontNameListOfFontSet -function will return this XLFD name instead of the client-supplied name. -.LP -Xlib uses the following algorithm to select the fonts -that will be used to display text with the -.PN XFontSet . -.LP -For each font charset required by the locale, -the base font name list is searched for the first appearance of one -of the following cases that names a set of fonts that exist at the server: -.IP \(bu 5 -The first XLFD-conforming base font name that specifies the required -charset or a superset of the required charset in its -.PN CharSetRegistry -and -.PN CharSetEncoding -fields. -The implementation may use a base font name whose specified charset -is a superset of the required charset, for example, -an ISO8859-1 font for an ASCII charset. -.IP \(bu 5 -The first set of one or more XLFD-conforming base font names -that specify one or more charsets that can be remapped to support the -required charset. -The Xlib implementation may recognize various mappings -from a required charset to one or more other charsets -and use the fonts for those charsets. -For example, JIS Roman is ASCII with tilde and backslash replaced -by yen and overbar; -Xlib may load an ISO8859-1 font to support this character set -if a JIS Roman font is not available. -.IP \(bu 5 -The first XLFD-conforming font name or the first non-XLFD font name -for which an XLFD font name can be obtained, combined with the -required charset (replacing the -.PN CharSetRegistry -and -.PN CharSetEncoding -fields in the XLFD font name). -As in case 1, -the implementation may use a charset that is a superset -of the required charset. -.IP \(bu 5 -The first font name that can be mapped in some implementation-dependent -manner to one or more fonts that support imaging text in the charset. -.LP -For example, assume that a locale required the charsets: -.LP -.Ds 0 -ISO8859-1 -JISX0208.1983 -JISX0201.1976 -GB2312-1980.0 -.De -.LP -The user could supply a base_font_name_list that explicitly specifies the -charsets, ensuring that specific fonts are used if they exist. -For example: -.LP -.Ds 0 -"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\ --JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\ --GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\ --Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1" -.De -.LP -Alternatively, the user could supply a base_font_name_list -that omits the charsets, -letting Xlib select font charsets required for the locale. -For example: -.LP -.Ds 0 -"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ --JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\ --GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ --Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150" -.De -.LP -Alternatively, the user could simply supply a single base font name -that allows Xlib to select from all available fonts -that meet certain minimum XLFD property requirements. -For example: -.LP -.Ds 0 -"-*-*-*-R-Normal--*-180-100-100-*-*" -.De -.LP -If -.PN XCreateFontSet -is unable to create the font set, -either because there is insufficient memory or because the current locale -is not supported, -.PN XCreateFontSet -returns NULL, missing_charset_list_return is set to NULL, -and missing_charset_count_return -is set to zero. -If fonts exist for all of the charsets required by the current locale, -.PN XCreateFontSet -returns a valid -.PN XFontSet , -missing_charset_list_return is set to NULL, -and missing_charset_count_return is set to zero. -.LP -If no font exists for one or more of the required charsets, -.PN XCreateFontSet -sets missing_charset_list_return to a -list of one or more null-terminated charset names for which no font exists -and sets missing_charset_count_return to the number of missing fonts. -The charsets are from the list of the required charsets for -the encoding of the locale and do not include any charsets to which Xlib -may be able to remap a required charset. -.LP -If no font exists for any of the required charsets -or if the locale definition in Xlib requires that a font exist -for a particular charset and a font is not found for that charset, -.PN XCreateFontSet -returns NULL. -Otherwise, -.PN XCreateFontSet -returns a valid -.PN XFontSet -to font_set. -.LP -When an Xmb/wc drawing or measuring function is called with an -.PN XFontSet -that has missing charsets, some characters in the locale will not be -drawable. -If def_string_return is non-NULL, -.PN XCreateFontSet -returns a pointer to a string that represents the glyphs -that are drawn with this -.PN XFontSet -when the charsets of the available fonts do not include all font glyphs -required to draw a codepoint. -The string does not necessarily consist of valid characters -in the current locale and is not necessarily drawn with -the fonts loaded for the font set, -but the client can draw and measure the default glyphs -by including this string in a string being drawn or measured with the -.PN XFontSet . -.LP -If the string returned to def_string_return is the empty string ("\^"), -no glyphs are drawn, and the escapement is zero. -The returned string is null-terminated. -It is owned by Xlib and should not be modified or freed by the client. -It will be freed by a call to -.PN XFreeFontSet -with the associated -.PN XFontSet . -Until freed, its contents will not be modified by Xlib. -.LP -The client is responsible for constructing an error message from the -missing charset and default string information and may choose to continue -operation in the case that some fonts did not exist. -.LP -The returned -.PN XFontSet -and missing charset list should be freed with -.PN XFreeFontSet -and -.PN XFreeStringList , -respectively. -The client-supplied base_font_name_list may be freed -by the client after calling -.PN XCreateFontSet . -.LP -.sp -To obtain a list of -.PN XFontStruct -structures and full font names given an -.PN XFontSet , -use -.PN XFontsOfFontSet . -.IN "XFontsOfFontSet" "" "@DEF@" -.sM -.FD 0 -int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - XFontStruct ***\fIfont_struct_list_return\fP\^; -.br - char ***\fIfont_name_list_return\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.IP \fIfont_struct_list_return\fP 1i -Returns the list of font structs. -.IP \fIfont_name_list_return\fP 1i -Returns the list of font names. -.LP -.eM -The -.PN XFontsOfFontSet -function returns a list of one or more -.PN XFontStructs -and font names for the fonts used by the Xmb and Xwc layers -for the given font set. -A list of pointers to the -.PN XFontStruct -structures is returned to font_struct_list_return. -A list of pointers to null-terminated, fully specified font name strings -in the locale of the font set is returned to font_name_list_return. -The font_name_list order corresponds to the font_struct_list order. -The number of -.PN XFontStruct -structures and font names is returned as the value of the function. -.LP -Because it is not guaranteed that a given character will be imaged using a -single font glyph, -there is no provision for mapping a character or default string -to the font properties, font ID, or direction hint for the font -for the character. -The client may access the -.PN XFontStruct -list to obtain these values for all the fonts currently in use. -.LP -Xlib does not guarantee that fonts are loaded from the server -at the creation of an -.PN XFontSet . -Xlib may choose to cache font data, loading it only as needed to draw text -or compute text dimensions. -Therefore, existence of the per_char metrics in the -.PN XFontStruct -structures in the -.PN XFontStructSet -is undefined. -Also, note that all properties in the -.PN XFontStruct -structures are in the STRING encoding. -.LP -The -.PN XFontStruct -and font name lists are owned by Xlib -and should not be modified or freed by the client. -They will be freed by a call to -.PN XFreeFontSet -with the associated -.PN XFontSet . -Until freed, their contents will not be modified by Xlib. -.LP -.sp -To obtain the base font name list and the selected font name list given an -.PN XFontSet , -use -.PN XBaseFontNameListOfFontSet . -.IN "XBaseFontNameListOfFontSet" "" "@DEF@" -.sM -.FD 0 -char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XBaseFontNameListOfFontSet -function returns the original base font name list supplied -by the client when the -.PN XFontSet -was created. -A null-terminated string containing a list of -comma-separated font names is returned -as the value of the function. -White space may appear immediately on either side of separating commas. -.LP -If -.PN XCreateFontSet -obtained an XLFD name from the font properties for the font specified -by a non-XLFD base name, the -.PN XBaseFontNameListOfFontSet -function will return the XLFD name instead of the non-XLFD base name. -.LP -The base font name list is owned by Xlib and should not be modified or -freed by the client. -It will be freed by a call to -.PN XFreeFontSet -with the associated -.PN XFontSet . -Until freed, its contents will not be modified by Xlib. -.LP -.sp -To obtain the locale name given an -.PN XFontSet , -use -.PN XLocaleOfFontSet . -.IN "XLocaleOfFontSet" "" "@DEF@" -.sM -.FD 0 -char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XLocaleOfFontSet -function -returns the name of the locale bound to the specified -.PN XFontSet , -as a null-terminated string. -.LP -The returned locale name string is owned by Xlib -and should not be modified or freed by the client. -It may be freed by a call to -.PN XFreeFontSet -with the associated -.PN XFontSet . -Until freed, it will not be modified by Xlib. -.LP -.sp -The -.PN XFreeFontSet -function is a convenience function for freeing an output context. -.PN XFreeFontSet -also frees its associated -.PN XOM -if the output context was created by -.PN XCreateFontSet . -.IN "XFreeFontSet" "" "@DEF@" -.sM -.FD 0 -void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XFreeFontSet -function frees the specified font set. -The associated base font name list, font name list, -.PN XFontStruct -list, and -.PN XFontSetExtents , -if any, are freed. -.NH 3 -Obtaining Font Set Metrics -.XS -\*(SN Obtaining Font Set Metrics -.XE -.LP -Metrics for the internationalized text drawing functions -are defined in terms of a primary draw direction, -which is the default direction in which the character origin advances -for each succeeding character in the string. -The Xlib interface is currently defined to support only a left-to-right -primary draw direction. -The drawing origin is the position passed to the drawing function -when the text is drawn. -The baseline is a line drawn through the drawing origin parallel -to the primary draw direction. -Character ink is the pixels painted in the foreground color -and does not include interline or intercharacter spacing -or image text background pixels. -.LP -The drawing functions are allowed to implement implicit text -directionality control, reversing the order in which characters are -rendered along the primary draw direction in response to locale-specific -lexical analysis of the string. -.LP -Regardless of the character rendering order, -the origins of all characters are on the primary draw direction side -of the drawing origin. -The screen location of a particular character image may be determined with -.PN XmbTextPerCharExtents -or -.PN XwcTextPerCharExtents . -.LP -The drawing functions are allowed to implement context-dependent -rendering, where the glyphs drawn for a string are not simply a -concatenation of the glyphs that represent each individual character. -A string of two characters drawn with -.PN XmbDrawString -may render differently than if the two characters -were drawn with separate calls to -.PN XmbDrawString . -If the client appends or inserts a character -in a previously drawn string, -the client may need to redraw some adjacent characters -to obtain proper rendering. -.LP -.sp -To find out about direction-dependent rendering, use -.PN XDirectionalDependentDrawing . -.IN "XDirectionalDependentDrawing" "" "@DEF@" -.sM -.FD 0 -Bool XDirectionalDependentDrawing\^(\^\fIfont_set\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XDirectionalDependentDrawing -function returns -.PN True -if the drawing functions implement implicit text directionality; -otherwise, it returns -.PN False . -.LP -.sp -To find out about context-dependent rendering, use -.PN XContextualDrawing . -.IN "XContextualDrawing" "" "@DEF@" -.sM -.FD 0 -Bool XContextualDrawing\^(\^\fIfont_set\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XContextualDrawing -function returns -.PN True -if text drawn with the font set might include context-dependent drawing; -otherwise, it returns -.PN False . -.LP -.sp -To find out about context-dependent or direction-dependent rendering, use -.PN XContextDependentDrawing . -.IN "XContextDependentDrawing" "" "@DEF@" -.sM -.FD 0 -Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XContextDependentDrawing -function returns -.PN True -if the drawing functions implement implicit text directionality or -if text drawn with the font_set might include context-dependent drawing; -otherwise, it returns -.PN False . -.LP -The drawing functions do not interpret newline, tab, or other control -characters. -The behavior when nonprinting characters other than space are drawn -is implementation-dependent. -It is the client's responsibility to interpret control characters -in a text stream. -.LP -The maximum character extents for the fonts that are used by the text -drawing layers can be accessed by the -.PN XFontSetExtents -structure: -.IN "XFontSetExtents" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - XRectangle max_ink_extent; /* over all drawable characters */ - XRectangle max_logical_extent; /* over all drawable characters */ -} XFontSetExtents; -.De -.LP -The -.PN XRectangle -structures used to return font set metrics are the usual Xlib screen-oriented -rectangles -with x, y giving the upper left corner, and width and height always positive. -.LP -The max_ink_extent member gives the maximum extent, over all drawable characters, of -the rectangles that bound the character glyph image drawn in the -foreground color, relative to a constant origin. -See -.PN XmbTextExtents -and -.PN XwcTextExtents -for detailed semantics. -.LP -The max_logical_extent member gives the maximum extent, -over all drawable characters, of the rectangles -that specify minimum spacing to other graphical features, -relative to a constant origin. -Other graphical features drawn by the client, for example, -a border surrounding the text, should not intersect this rectangle. -The max_logical_extent member should be used to compute minimum -interline spacing and the minimum area that must be allowed -in a text field to draw a given number of arbitrary characters. -.LP -Due to context-dependent rendering, -appending a given character to a string may change -the string's extent by an amount other than that character's -individual extent. -.LP -The rectangles for a given character in a string can be obtained from -.PN XmbPerCharExtents -or -.PN XwcPerCharExtents . -.LP -.sp -To obtain the maximum extents structure given an -.PN XFontSet , -use -.PN XExtentsOfFontSet . -.IN "XExtentsOfFontSet" "" "@DEF@" -.sM -.FD 0 -XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.LP -.eM -The -.PN XExtentsOfFontSet -function returns an -.PN XFontSetExtents -structure for the fonts used by the Xmb and Xwc layers -for the given font set. -.LP -The -.PN XFontSetExtents -structure is owned by Xlib and should not be modified -or freed by the client. -It will be freed by a call to -.PN XFreeFontSet -with the associated -.PN XFontSet . -Until freed, its contents will not be modified by Xlib. -.LP -.sp -To obtain the escapement in pixels of the specified text as a value, -use -.PN XmbTextEscapement -or -.PN XwcTextEscapement . -.IN "XmbTextEscapement" "" "@DEF@" -.IN "XwcTextEscapement" "" "@DEF@" -.sM -.FD 0 -int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInum_bytes\fP\^; -.FN -.FD 0 -int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - wchar_t *\fIstring\fP\^; -.br - int \fInum_wchars\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInum_bytes\fP 1i -Specifies the number of bytes in the string argument. -.IP \fInum_wchars\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -The -.PN XmbTextEscapement -and -.PN XwcTextEscapement -functions return the escapement in pixels of the specified string as a value, -using the fonts loaded for the specified font set. -The escapement is the distance in pixels in the primary draw -direction from the drawing origin to the origin of the next character to -be drawn, assuming that the rendering of the next character is not -dependent on the supplied string. -.LP -Regardless of the character rendering order, -the escapement is always positive. -.LP -.sp -To obtain the overall_ink_return and overall_logical_return arguments, -the overall bounding box of the string's image, and a logical bounding box, -use -.PN XmbTextExtents - or -.PN XwcTextExtents . -.IN "XmbTextExtents" "" "@DEF@" -.IN "XwcTextExtents" "" "@DEF@" -.sM -.FD 0 -int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInum_bytes\fP\^; -.br - XRectangle *\fIoverall_ink_return\fP\^; -.br - XRectangle *\fIoverall_logical_return\fP\^; -.FN -.FD 0 -int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, -\fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - wchar_t *\fIstring\fP\^; -.br - int \fInum_wchars\fP\^; -.br - XRectangle *\fIoverall_ink_return\fP\^; -.br - XRectangle *\fIoverall_logical_return\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInum_bytes\fP 1i -Specifies the number of bytes in the string argument. -.IP \fInum_wchars\fP 1i -Specifies the number of characters in the string argument. -.ds Ov dimensions -.IP \fIoverall_ink_return\fP 1i -Returns the overall ink \*(Ov. -.IP \fIoverall_logical_return\fP 1i -Returns the overall logical \*(Ov. -.LP -.eM -The -.PN XmbTextExtents -and -.PN XwcTextExtents -functions set the components of the specified overall_ink_return and -overall_logical_return -arguments to the overall bounding box of the string's image -and a logical bounding box for spacing purposes, respectively. -They return the value returned by -.PN XmbTextEscapement -or -.PN XwcTextEscapement . -These metrics are relative to the drawing origin of the string, -using the fonts loaded for the specified font set. -.LP -If the overall_ink_return argument is non-NULL, -it is set to the bounding box of the string's character ink. -The overall_ink_return for a nondescending, horizontally drawn -Latin character is conventionally entirely above the baseline; -that is, overall_ink_return.height <= \-overall_ink_return.y. -The overall_ink_return for a nonkerned character -is entirely at, and to the right of, the origin; -that is, overall_ink_return.x >= 0. -A character consisting of a single pixel at the origin would set -overall_ink_return fields y = 0, x = 0, width = 1, and height = 1. -.LP -If the overall_logical_return argument is non-NULL, -it is set to the bounding box that provides minimum spacing -to other graphical features for the string. -Other graphical features, for example, a border surrounding the text, -should not intersect this rectangle. -.LP -When the -.PN XFontSet -has missing charsets, -metrics for each unavailable character are taken -from the default string returned by -.PN XCreateFontSet -so that the metrics represent the text as it will actually be drawn. -The behavior for an invalid codepoint is undefined. -.LP -To determine the effective drawing origin for a character in a drawn string, -the client should call -.PN XmbTextPerCharExtents -on the entire string, then on the character, -and subtract the x values of the returned -rectangles for the character. -This is useful to redraw portions of a line of text -or to justify words, but for context-dependent rendering, -the client should not assume that it can redraw the character by itself -and get the same rendering. -.LP -.sp -To obtain per-character information for a text string, -use -.PN XmbTextPerCharExtents -or -.PN XwcTextPerCharExtents . -.IN "XmbTextPerCharExtents" "" "@DEF@" -.IN "XwcTextPerCharExtents" "" "@DEF@" -.sM -.FD 0 -Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^, -.br - \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInum_bytes\fP\^; -.br - XRectangle *\fIink_array_return\fP\^; -.br - XRectangle *\fIlogical_array_return\fP\^; -.br - int \fIarray_size\fP\^; -.br - int *\fInum_chars_return\fP\^; -.br - XRectangle *\fIoverall_ink_return\fP\^; -.br - XRectangle *\fIoverall_logical_return\fP\^; -.FN -.FD 0 -Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^, -.br - \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_ink_return\fP\^) -.br - XFontSet \fIfont_set\fP\^; -.br - wchar_t *\fIstring\fP\^; -.br - int \fInum_wchars\fP\^; -.br - XRectangle *\fIink_array_return\fP\^; -.br - XRectangle *\fIlogical_array_return\fP; -.br - int \fIarray_size\fP\^; -.br - int *\fInum_chars_return\fP\^; -.br - XRectangle *\fIoverall_ink_return\fP\^; -.br - XRectangle *\fIoverall_logical_return\fP\^; -.FN -.IP \fIfont_set\fP 1i -Specifies the font set. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInum_bytes\fP 1i -Specifies the number of bytes in the string argument. -.IP \fInum_wchars\fP 1i -Specifies the number of characters in the string argument. -.IP \fIink_array_return\fP 1i -Returns the ink dimensions for each character. -.IP \fIlogical_array_return\fP 1i -Returns the logical dimensions for each character. -.IP \fIarray_size\fP 1i -Specifies the size of ink_array_return and logical_array_return. -The caller must pass in arrays of this size. -.IP \fInum_chars_return\fP 1i -Returns the number of characters in the string argument. -.ds Ov extents of the entire string -.IP \fIoverall_ink_return\fP 1i -Returns the overall ink \*(Ov. -.IP \fIoverall_logical_return\fP 1i -Returns the overall logical \*(Ov. -.LP -.eM -The -.PN XmbTextPerCharExtents -and -.PN XwcTextPerCharExtents -functions return the text dimensions of each character of the specified text, -using the fonts loaded for the specified font set. -Each successive element of ink_array_return and logical_array_return -is set to the successive character's drawn metrics, -relative to the drawing origin of the string and one -rectangle -for each character in the supplied text string. -The number of elements of ink_array_return and logical_array_return -that have been set is returned to num_chars_return. -.LP -Each element of ink_array_return is set to the bounding box -of the corresponding character's drawn foreground color. -Each element of logical_array_return is set to the bounding box -that provides minimum spacing to other graphical features -for the corresponding character. -Other graphical features should not intersect any of the -logical_array_return rectangles. -.LP -Note that an -.PN XRectangle -represents the effective drawing dimensions of the character, -regardless of the number of font glyphs that are used to draw -the character or the direction in which the character is drawn. -If multiple characters map to a single character glyph, -the dimensions of all the -.PN XRectangles -of those characters are the same. -.LP -When the -.PN XFontSet -has missing charsets, metrics for each unavailable -character are taken from the default string returned by -.PN XCreateFontSet -so that the metrics represent the text as it will actually be drawn. -The behavior for an invalid codepoint is undefined. -.LP -If the array_size is too small for the number of characters in the -supplied text, the functions return zero -and num_chars_return is set to the number of rectangles required. -Otherwise, the functions return a nonzero value. -.LP -If the overall_ink_return or overall_logical_return argument is non-NULL, -.PN XmbTextPerCharExtents -and -.PN XwcTextPerCharExtents -return the maximum extent of the string's metrics to overall_ink_return -or overall_logical_return, as returned by -.PN XmbTextExtents -or -.PN XwcTextExtents . -.NH 3 -Drawing Text Using Font Sets -.XS -\*(SN Drawing Text Using Font Sets -.XE -.LP -The functions defined in this section -draw text at a specified location in a drawable. -They are similar to the functions -.PN XDrawText , -.PN XDrawString , -and -.PN XDrawImageString -except that they work with font sets instead of single fonts -and interpret the text based on the locale of the font set -instead of treating the bytes of the string as direct font indexes. -See section 8.6 for details of the use of Graphics Contexts (GCs) -and possible protocol errors. -If a -.PN BadFont -error is generated, -characters prior to the offending character may have been drawn. -.LP -The text is drawn using the fonts loaded for the specified font set; -the font in the GC is ignored and may be modified by the functions. -No validation that all fonts conform to some width rule is performed. -.LP -The text functions -.PN XmbDrawText -and -.PN XwcDrawText -use the following structures: -.LP -.IN "XmbTextItem" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - char *chars; /* pointer to string */ - int nchars; /* number of bytes */ - int delta; /* pixel delta between strings */ - XFontSet font_set; /* fonts, None means don't change */ -} XmbTextItem; -.De -.LP -.IN "XwcTextItem" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - wchar_t *chars; /* pointer to wide char string */ - int nchars; /* number of wide characters */ - int delta; /* pixel delta between strings */ - XFontSet font_set; /* fonts, None means don't change */ -} XwcTextItem; -.De -.LP -.eM -.sp -To draw text using multiple font sets in a given drawable, use -.PN XmbDrawText -or -.PN XwcDrawText . -.IN "XmbDrawText" "" "@DEF@" -.IN "XwcDrawText" "" "@DEF@" -.sM -.FD 0 -void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - XmbTextItem *\fIitems\fP\^; -.br - int \fInitems\fP\^; -.FN -.FD 0 -void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - XwcTextItem *\fIitems\fP\^; -.br - int \fInitems\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIitems\fP 1i -Specifies an array of text items. -.IP \fInitems\fP 1i -Specifies the number of text items in the array. -.LP -.eM -The -.PN XmbDrawText -and -.PN XwcDrawText -functions allow complex spacing and font set shifts between text strings. -Each text item is processed in turn, with the origin of a text -element advanced in the primary draw direction by the escapement of the -previous text item. -A text item delta specifies an additional escapement of the text item -drawing origin in the primary draw direction. -A font_set member other than -.PN None -in an item causes the font set to be used for this and subsequent text items -in the text_items list. -Leading text items with a font_set member set to -.PN None -will not be drawn. -.LP -.PN XmbDrawText -and -.PN XwcDrawText -do not perform any context-dependent rendering between text segments. -Clients may compute the drawing metrics by passing each text segment to -.PN XmbTextExtents -and -.PN XwcTextExtents -or -.PN XmbTextPerCharExtents -and -.PN XwcTextPerCharExtents . -When the -.PN XFontSet -has missing charsets, each unavailable character is drawn -with the default string returned by -.PN XCreateFontSet . -The behavior for an invalid codepoint is undefined. -.LP -.sp -To draw text using a single font set in a given drawable, use -.PN XmbDrawString -or -.PN XwcDrawString . -.IN "XmbDrawString" "" "@DEF@" -.IN "XwcDrawString" "" "@DEF@" -.sM -.FD 0 -void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - XFontSet \fIfont_set\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInum_bytes\fP\^; -.FN -.FD 0 -void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - XFontSet \fIfont_set\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - wchar_t *\fIstring\fP\^; -.br - int \fInum_wchars\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIfont_set\fP 1i -Specifies the font set. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInum_bytes\fP 1i -Specifies the number of bytes in the string argument. -.IP \fInum_wchars\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -The -.PN XmbDrawString -and -.PN XwcDrawString -functions draw the specified text with the foreground pixel. -When the -.PN XFontSet -has missing charsets, each unavailable character is drawn -with the default string returned by -.PN XCreateFontSet . -The behavior for an invalid codepoint is undefined. -.LP -.sp -To draw image text using a single font set in a given drawable, use -.PN XmbDrawImageString -or -.PN XwcDrawImageString . -.IN "XmbDrawImageString" "" "@DEF@" -.IN "XwcDrawImageString" "" "@DEF@" -.sM -.FD 0 -void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - XFontSet \fIfont_set\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - char *\fIstring\fP\^; -.br - int \fInum_bytes\fP\^; -.FN -.FD 0 -void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - XFontSet \fIfont_set\fP\^; -.br - GC \fIgc\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - wchar_t *\fIstring\fP\^; -.br - int \fInum_wchars\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies the drawable. -.IP \fIfont_set\fP 1i -Specifies the font set. -.IP \fIgc\fP 1i -Specifies the GC. -.ds Xy -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.IP \fIstring\fP 1i -Specifies the character string. -.IP \fInum_bytes\fP 1i -Specifies the number of bytes in the string argument. -.IP \fInum_wchars\fP 1i -Specifies the number of characters in the string argument. -.LP -.eM -The -.PN XmbDrawImageString -and -.PN XwcDrawImageString -functions fill a destination rectangle with the background pixel defined -in the GC and then paint the text with the foreground pixel. -The filled rectangle is the rectangle returned to overall_logical_return by -.PN XmbTextExtents -or -.PN XwcTextExtents -for the same text and -.PN XFontSet . -.LP -When the -.PN XFontSet -has missing charsets, each unavailable character is drawn -with the default string returned by -.PN XCreateFontSet . -The behavior for an invalid codepoint is undefined. -.NH 2 -Input Methods -.XS -\*(SN Input Methods -.XE -.LP -This section provides discussions of the following X Input Method -(XIM) topics: -.IP \(bu 5 -Input method overview -.IP \(bu 5 -Input method management -.IP \(bu 5 -Input method functions -.IP \(bu 5 -Input method values -.IP \(bu 5 -Input context functions -.IP \(bu 5 -Input context values -.IP \(bu 5 -Input method callback semantics -.IP \(bu 5 -Event filtering -.IP \(bu 5 -Getting keyboard input -.IP \(bu 5 -Input method conventions -.NH 3 -Input Method Overview -.XS -\*(SN Input Method Overview -.XE -.LP -This section provides definitions for terms and concepts used -for internationalized text input and a brief overview of the -intended use of the mechanisms provided by Xlib. -.LP -A large number of languages in the world use alphabets -consisting of a small set of symbols (letters) to form words. -To enter text into a computer in an alphabetic language, -a user usually has a keyboard on which there exist key symbols corresponding -to the alphabet. -Sometimes, a few characters of an alphabetic language are missing -on the keyboard. -Many computer users who speak a Latin-alphabet-based language -only have an English-based keyboard. -They need to hit a combination of keystrokes -to enter a character that does not exist directly on the keyboard. -A number of algorithms have been developed for entering such characters. -These are known as European input methods, compose input methods, -or dead-key input methods. -.LP -Japanese is an example of a language with a phonetic symbol set, -where each symbol represents a specific sound. -There are two phonetic symbol sets in Japanese: Katakana and Hiragana. -In general, -Katakana is used for words that are of foreign origin, -and Hiragana is used for writing native Japanese words. -Collectively, the two systems are called Kana. -Each set consists of 48 characters. -.LP -Korean also has a phonetic symbol set, called Hangul. -Each of the 24 basic phonetic symbols (14 consonants and 10 vowels) -represents a specific sound. -A syllable is composed of two or three parts: -the initial consonants, the vowels, and the optional last consonants. -With Hangul, -syllables can be treated as the basic units on which text processing is done. -For example, -a delete operation may work on a phonetic symbol or a syllable. -Korean code sets include several thousands of these syllables. -A user types the phonetic symbols that make up the syllables of the words -to be entered. -The display may change as each phonetic symbol is entered. -For example, -when the second phonetic symbol of a syllable is entered, -the first phonetic symbol may change its shape and size. -Likewise, when the third phonetic symbol is entered, -the first two phonetic symbols may change their shape and size. -.LP -Not all languages rely solely on alphabetic or phonetic systems. -Some languages, including Japanese and Korean, employ an -ideographic writing system. -In an ideographic system, rather than taking a small set of -symbols and combining them in different ways to create words, -each word consists of one unique symbol (or, occasionally, several symbols). -The number of symbols can be very large: -approximately 50,000 have been identified in Hanzi, -the Chinese ideographic system. -.LP -Two major aspects of ideographic systems impact their use with computers. -First, the standard computer character sets in Japan, China, and Korea -include roughly 8,000 characters, -while sets in Taiwan have between 15,000 and 30,000 characters. -This makes it necessary to use more than one byte to represent a character. -Second, it obviously is impractical to have a keyboard that includes -all of a given language's ideographic symbols. -Therefore, a mechanism is required for entering characters -so that a keyboard with a reasonable number of keys can be used. -Those input methods are usually based on phonetics, -but there also exist methods based on the graphical properties of -characters. -.LP -In Japan, both Kana and the ideographic system Kanji are used. -In Korea, Hangul and sometimes the ideographic system Hanja are used. -Now consider entering ideographs in Japan, Korea, China, and Taiwan. -.LP -In Japan, either Kana or English characters are typed and then a region -is selected (sometimes automatically) for conversion to Kanji. -Several Kanji characters may have the same phonetic representation. -If that is the case with the string entered, -a menu of characters is presented and -the user must choose the appropriate one. -If no choice is necessary or a preference has been established, -the input method does the substitution directly. -When Latin characters are converted to Kana or Kanji, -it is called a romaji conversion. -.LP -In Korea, it is usually acceptable to keep Korean text in Hangul form, -but some people may choose to write Hanja-originated words in Hanja -rather than in Hangul. -To change Hangul to Hanja, -the user selects a region for conversion -and then follows the same basic method as that described for Japanese. -.LP -Probably because there are well-accepted phonetic writing systems -for Japanese and Korean, -computer input methods in these countries for entering ideographs -are fairly standard. -Keyboard keys have both English characters and phonetic symbols -engraved on them, and the user can switch between the two sets. -.LP -The situation is different for Chinese. -While there is a phonetic system called Pinyin promoted by authorities, -there is no consensus for entering Chinese text. -Some vendors use a phonetic decomposition (Pinyin or another), -others use ideographic decomposition of Chinese words, -with various implementations and keyboard layouts. -There are about 16 known methods, none of which is a clear standard. -.LP -Also, there are actually two ideographic sets used: -Traditional Chinese (the original written Chinese) -and Simplified Chinese. -Several years ago, -the People's Republic of China launched a campaign to simplify -some ideographic characters and eliminate redundancies altogether. -Under the plan, -characters would be streamlined every five years. -Characters have been revised several times now, -resulting in the smaller, simpler set that makes up Simplified Chinese. -.NH 4 -Input Method Architecture -.XS -\*(SN Input Method Architecture -.XE -.LP -As shown in the previous section, -there are many different input methods in use today, -each varying with language, culture, and history. -A common feature of many input methods is that the user may type -multiple keystrokes to compose a single character (or set -of characters). -The process of composing characters from keystrokes is called -\fIpreediting\fP. -It may require complex algorithms and large dictionaries -involving substantial computer resources. -.LP -Input methods may require one or more areas in which to show the -feedback of the actual keystrokes, to propose disambiguation to the -user, to list dictionaries, and so on. -The input method areas of concern are as follows: -.IP \(bu 5 -The \fIstatus\fP area is a logical extension of the -LEDs that exist on the physical keyboard. -It is a window that is intended to present the internal state -of the input method that is critical to the user. -The status area may consist of text data and bitmaps or some combination. -.IP \(bu 5 -The \fIpreedit\fP area displays the -intermediate text for those languages that are composing prior to -the client handling the data. -.IP \(bu 5 -The \fIauxiliary\fP area is used for pop-up menus and customizing -dialogs that may be required for an input method. -There may be multiple auxiliary areas for an input method. -Auxiliary areas are managed by the input method independent of the client. -Auxiliary areas are assumed to be separate dialogs, -which are maintained by the input method. -.LP -There are various user interaction styles used for preediting. -The ones supported by Xlib are as follows: -.IP \(bu 5 -For \fIon-the-spot\fP input methods, -preediting data will be displayed directly in the application window. -Application data is moved to allow preedit data to appear -at the point of insertion. -.IP \(bu 5 -\fIOver-the-spot\fP preediting means that the data is displayed in -a preedit window that is placed over the point of insertion. -.IP \(bu 5 -\fIOff-the-spot\fP preediting means that the preedit window is -inside the application window but not at the point of insertion. -Often, this type of window is placed at the bottom of the application window. -.IP \(bu 5 -\fIRoot-window\fP preediting refers to input methods that use a preedit -window that is the child of -.PN RootWindow . -.LP -It would require a lot of computing resources if portable applications -had to include input methods for all the languages in the world. -To avoid this, -a goal of the Xlib design is to allow an application -to communicate with an input method placed in a separate process. -Such a process is called an \fIinput server\fP. -The server to which the application should connect is dependent on -the environment when the application is started up, -that is, the user language and the actual encoding to be used for it. -The input method connection is said to be \fIlocale-dependent\fP. -It is also user-dependent. -For a given language, the user can choose, to some extent, -the user interface style of input method (if choice is possible among -several). -.LP -Using an input server implies communication overhead, -but applications can be migrated without relinking. -Input methods can be implemented either as a -stub communicating to an input server or as a local library. -.LP -An input method may be based on a \fIfront-end\fP or a \fIback-end\fP -architecture. -In a front-end architecture, -there are two separate connections to the X server: -keystrokes go directly from the X server to the input method on -one connection and other events to the regular client connection. -The input method is then acting as a filter and sends composed strings -to the client. -A front-end architecture requires synchronization between the -two connections to avoid lost key events or locking issues. -.LP -In a back-end architecture, -a single X server connection is used. -A dispatching mechanism must decide on this channel to delegate appropriate -keystrokes to the input method. -For instance, -it may retain a Help keystroke for its own purpose. -In the case where the input method is a separate process (that is, a server), -there must be a special communication protocol between the back-end client -and the input server. -.LP -A front-end architecture introduces synchronization issues -and a filtering mechanism for noncharacter keystrokes -(Function keys, Help, and so on). -A back-end architecture sometimes implies more communication overhead -and more process switching. -If all three processes (X server, input server, client) -are running on a single workstation, -there are two process switches for each keystroke in a back-end -architecture, -but there is only one in a front-end architecture. -.LP -The abstraction used by a client to communicate with an input method -is an opaque data structure represented by the -.PN XIM -data type. -This data structure is returned by the -.PN XOpenIM -function, which opens an input method on a given display. -Subsequent operations on this data structure encapsulate all communication -between client and input method. -There is no need for an X client to use any networking library -or natural language package to use an input method. -.LP -A single input server may be used for one or more languages, -supporting one or more encoding schemes. -But the strings returned from an input method will always be encoded -in the (single) locale associated with the -.PN XIM -object. -.NH 4 -Input Contexts -.XS -\*(SN Input Contexts -.XE -.LP -Xlib provides the ability to manage a multi-threaded state for text input. -A client may be using multiple windows, -each window with multiple text entry areas, -and the user possibly switching among them at any time. -The abstraction for representing the state of a particular input thread -is called an \fIinput context\fP. -The Xlib representation of an input context is an -.PN XIC . -.LP -An input context is the abstraction retaining the state, properties, -and semantics of communication between a client and an input method. -An input context is a combination of an input method, a locale -specifying the encoding of the character strings to be returned, -a client window, internal state information, -and various layout or appearance characteristics. -The input context concept somewhat matches for input the graphics context -abstraction defined for graphics output. -.LP -One input context belongs to exactly one input method. -Different input contexts may be associated with the same input method, -possibly with the same client window. -An -.PN XIC -is created with the -.PN XCreateIC -function, providing an -.PN XIM -argument and affiliating the input context to the input method -for its lifetime. -When an input method is closed with -.PN XCloseIM , -all of its affiliated input contexts should not be used any more -(and should preferably be destroyed before closing the input method). -.LP -Considering the example of a client window with multiple text entry areas, -the application programmer could, for example, choose to implement as follows: -.IP \(bu 5 -As many input contexts are created as text entry areas, and the client -will get the input accumulated on each context each time it looks up -in that context. -.IP \(bu 5 -A single context is created for a top-level window in the application. -If such a window contains several text entry areas, -each time the user moves to another text entry area, -the client has to indicate changes in the context. -.LP -A range of choices can be made by application designers to use -either a single or multiple input contexts, -according to the needs of their application. -.NH 4 -Getting Keyboard Input -.XS -\*(SN Getting Keyboard Input -.XE -.LP -To obtain characters from an input method, -a client must call the function -.PN XmbLookupString -or -.PN XwcLookupString -with an input context created from that input method. -Both a locale and display are bound to an input method when it is opened, -and an input context inherits this locale and display. -Any strings returned by -.PN XmbLookupString -or -.PN XwcLookupString -will be encoded in that locale. -.NH 4 -Focus Management -.XS -\*(SN Focus Management -.XE -.LP -For each text entry area in which the -.PN XmbLookupString -or -.PN XwcLookupString -functions are used, -there will be an associated input context. -.LP -When the application focus moves to a text entry area, -the application must set the input context focus to the -input context associated with that area. -The input context focus is set by calling -.PN XSetICFocus -with the appropriate input context. -.LP -Also, when the application focus moves out of a text entry area, the -application should unset the focus for the associated input context -by calling -.PN XUnsetICFocus . -As an optimization, if -.PN XSetICFocus -is called successively on two different input contexts, -setting the focus on the second -will automatically unset the focus on the first. -.LP -To set and unset the input context focus correctly, -it is necessary to track application-level focus changes. -Such focus changes do not necessarily correspond to X server focus changes. -.LP -If a single input context -is being used to do input for -multiple text entry areas, it will also be necessary -to set the focus window of the -input context whenever the focus window changes -(see section 13.5.6.3). -.NH 4 -Geometry Management -.XS -\*(SN Geometry Management -.XE -.LP -In most input method architectures -(on-the-spot being the notable exception), -the input method will perform the display of its own data. -To provide better visual locality, -it is often desirable to have the input method areas embedded within a client. -To do this, -the client may need to allocate space for an input method. -Xlib provides support that allows the size and position of input method -areas to be provided by a client. -The input method areas that are supported for geometry management -are the status area and the preedit area. -.LP -The fundamental concept on which geometry management for input method windows -is based is the proper division of responsibilities between the -client (or toolkit) and the input method. -The division of responsibilities is as follows: -.IP \(bu 5 -The client is responsible for the geometry of the input method window. -.IP \(bu 5 -The input method is responsible for the contents of the input method window. -.LP -An input method is able to suggest a size to the client, -but it cannot suggest a placement. -Also the input method can only suggest a size. -It does not determine the size, -and it must accept the size it is given. -.LP -Before a client provides geometry management for an input method, -it must determine if geometry management is needed. -The input method indicates the need for geometry management -by setting -.PN XIMPreeditArea -or -.PN XIMStatusArea -in its -.PN XIMStyles -value returned by -.PN XGetIMValues . -When a client has decided that it will provide geometry management -for an input method, -it indicates that decision by setting the -.PN XNInputStyle -value in the -.PN XIC . -.LP -After a client has established with the input method -that it will do geometry management, -the client must negotiate the geometry with the input method. -The geometry is negotiated by the following steps: -.IP \(bu 5 -The client suggests an area to the input method by setting the -.PN XNAreaNeeded -value for that area. -If the client has no constraints for the input method, -it either will not suggest an area or will set the width and height to zero. -Otherwise, it will set one of the values. -.IP \(bu 5 -The client will get the XIC value -.PN XNAreaNeeded . -The input method will return its suggested size in this value. -The input method should pay attention to any constraints suggested -by the client. -.IP \(bu 5 -The client sets the XIC value -.PN XNArea -to inform the input method of the geometry of its window. -The client should try to honor the geometry requested by the input method. -The input method must accept this geometry. -.LP -Clients doing geometry management must be aware that setting other -XIC values may affect the geometry desired by an input method. -For example, -.PN XNFontSet -and -.PN XNLineSpacing -may change the geometry desired by the input method. -.LP -The table of XIC values (see section 13.5.6) -indicates the values that can cause the desired geometry to change -when they are set. -It is the responsibility of the client to renegotiate the geometry -of the input method window when it is needed. -.LP -In addition, -a geometry management callback is provided -by which an input method can initiate a geometry change. -.NH 4 -Event Filtering -.XS -\*(SN Event Filtering -.XE -.LP -A filtering mechanism is provided to allow input methods -to capture X events transparently to clients. -It is expected that toolkits (or clients) using -.PN XmbLookupString -or -.PN XwcLookupString -will call this filter at some point in the event processing mechanism -to make sure that events needed by an input method can be filtered -by that input method. -.LP -If there were no filter, -a client could receive and discard events that are necessary -for the proper functioning of an input method. -The following provides a few examples of such events: -.IP \(bu 5 -Expose events on preedit window in local mode. -.IP \(bu 5 -Events may be used by an input method to communicate with an input server. -Such input server protocol-related events have to be intercepted -if one does not want to disturb client code. -.IP \(bu 5 -Key events can be sent to a filter before they are bound -to translations such as those the X Toolkit Intrinsics library provides. -.LP -Clients are expected to get the XIC value -.PN XNFilterEvents -and augment the event mask for the client window with that event mask. -This mask may be zero. -.NH 4 -Callbacks -.XS -\*(SN Callbacks -.XE -.LP -When an on-the-spot input method is implemented, -only the client can insert or delete preedit data in place -and possibly scroll existing text. -This means that the echo of the keystrokes has to be achieved -by the client itself, tightly coupled with the input method logic. -.LP -When the user enters a keystroke, -the client calls -.PN XmbLookupString -or -.PN XwcLookupString . -At this point, in the on-the-spot case, -the echo of the keystroke in the preedit has not yet been done. -Before returning to the client logic that handles the input characters, -the look-up function -must call the echoing logic to insert the new keystroke. -If the keystrokes entered so far make up a character, -the keystrokes entered need to be deleted, -and the composed character will be returned. -Hence, what happens is that, while being called by client code, -the input method logic has to call back to the client before it returns. -The client code, that is, a callback procedure, -is called from the input method logic. -.LP -There are a number of cases where the input method logic has to -call back the client. -Each of those cases is associated with a well-defined callback action. -It is possible for the client to specify, for each input context, -what callback is to be called for each action. -.LP -There are also callbacks provided for feedback of status information -and a callback to initiate a geometry request for an input method. -.NH 4 -Visible Position Feedback Masks -.XS -\*(SN Visible Position Feedback Masks -.XE -.LP -In the on-the-spot input style, there is a problem when -attempting to draw preedit strings that are longer than the -available space. Once the display area is exceeded, it is not -clear how best to display the preedit string. -The visible position feedback masks of -.PN XIMText -help resolve this problem by allowing the input method to specify hints that -indicate the essential portions of the preedit string. -For example, such hints can help developers implement -scrolling of a long preedit string within a short preedit display area. -.NH 4 -Preedit String Management -.XS -\*(SN Preedit String Management -.XE -.LP -As highlighted before, the input method architecture provides -preediting, which supports a type of preprocessor input composition. -In this case, composition consists of interpreting a sequence -of key events and returning a committed string via -.PN XmbLookupString -or -.PN XwcLookupString . -This provides the basics for input methods. -.LP -In addition to preediting based on key events, a general framework -is provided to give a client that desires it more advanced preediting based -on the text within the client. This framework is called -\fIstring conversion\fP and is provided using XIC values. -The fundamental concept of string conversion -is to allow the input method to manipulate the client's -text independent of any user preediting operation. -.LP -The need for string conversion is based on -language needs and input method capabilities. -The following are some examples of string conversion: -.IP \(bu 5 -Transliteration conversion provides language-specific conversions -within the input method. -In the case of Korean input, users wish to convert a Hangul string -into a Hanja string while in preediting, after preediting, -or in other situations (for example, on a selected string). -The conversion is triggered when the user -presses a Hangul-to-Hanja key sequence (which may be input method specific). -Sometimes the user may want to invoke the conversion after finishing -preediting or on a user-selected string. -Thus, the string to be converted is in an application buffer, not in -the preedit area of the input method. The string conversion services -allow the client to request this transliteration conversion from the -input method. -There are many other transliteration conversions defined for -various languages, for example, Kana-to-Kanji conversion in Japanese. -.sp -The key to remember is that transliteration conversions are triggered -at the request of the user and returned to the client -immediately without affecting the preedit area of the input method. -.IP \(bu 5 -Reconversion of a previously committed string or -a selected string is supported by many input methods as a -convenience to the user. -For example, a user tends to mistype the commit key while -preediting. In that case, some input methods provide a special -key sequence to request a ``reconvert'' operation on the -committed string, similiar to the undo facility provided by most -text editors. -Another example is where the user is proofreading a document -that has some misconversions from preediting and wants to correct -the misconverted text. Such reconversion is again triggered -by the user invoking some special action, but reconversions should -not affect the state of the preedit area. -.IP \(bu 5 -Context-sensitive conversion is required for some languages -and input methods that need to retrieve text that surrounds the -current spot location (cursor position) of the client's buffer. -Such text is needed when the preediting operation depends on -some surrounding characters (usually preceding the spot location). -For example, -in Thai language input, certain character sequences may be invalid and -the input method may want to check whether characters constitute a -valid word. Input methods that do such context-dependent -checking need to retrieve the characters surrounding the current -cursor position to obtain complete words. -.sp -Unlike other conversions, this conversion is not explicitly -requested by the user. -Input methods that provide such context-sensitive conversion -continuously need to request context from the client, and any change -in the context of the spot location may affect such conversions. -The client's context would be needed if the user moves the cursor -and starts editing again. -.sp -For this reason, an input method supporting this type of conversion -should take notice of when the client calls -.PN XmbResetIC -or -.PN XwcResetIC , -which is usually an indication of a context change. -.LP -Context-sensitive conversions just need a copy of the client's text, -while other conversions replace the client's text with new text -to achieve the reconversion or transliteration. Yet in all -cases the result of a conversion, either immediately or via preediting, -is returned by the -.PN XmbLookupString -and -.PN XwcLookupString -functions. -.LP -String conversion support is dependent on the availability of the -.PN XNStringConversion -or -.PN XNStringConversionCallback -XIC values. -Because the input method may not support string conversions, -clients have to query the availability of string conversion -operations by checking the supported XIC values list by calling -.PN XGetIMValues -with the -.PN XNQueryICValuesList -IM value. -.LP -The difference between these two values is whether the -conversion is invoked by the client or the input method. -The -.PN XNStringConversion -XIC value is used by clients to request -a string conversion from the input method. The client -is responsible for determining which events are used -to trigger the string conversion and whether the string to be -converted should be copied or deleted. The type of conversion -is determined by the input method; the client can only -pass the string to be converted. The client is guaranteed that -no -.PN XNStringConversionCallback -will be issued when this value is set; thus, the client need -only set one of these values. -.LP -The -.PN XNStringConversionCallback -XIC value is used by the client to notify the input method that -it will accept requests from the input method for string conversion. -If this value is set, -it is the input method's responsibility to determine which -events are used to trigger the string conversion. -When such events occur, the input method issues a call to the -client-supplied procedure to retrieve the string to be converted. The client's -callback procedure is notified whether to copy or delete the string and -is provided with hints as to the amount of text needed. -The -.PN XIMStringConversionCallbackStruct -specifies which text should be passed back to the input method. -.LP -Finally, the input method may call the client's -.PN XNStringConversionCallback -procedure multiple times if the string returned from the callback is -not sufficient to perform a successful conversion. The arguments -to the client's procedure allow the input method to define a -position (in character units) relative to the client's cursor position -and the size of the text needed. By varying the position and size of -the desired text in subsequent callbacks, the input method can retrieve -additional text. -.LP -.NH 3 -Input Method Management -.XS -\*(SN Input Method Management -.XE -.LP -The interface to input methods might appear to be simply creating -an input method -.Pn ( XOpenIM ) -and freeing an input method -.Pn ( XCloseIM ). -However, input methods may -require complex communication with input method servers (IM servers), -for example: -.IP \(bu 5 -If the X server, IM server, and X clients are started asynchronously, -some clients may attempt to connect to the IM server before it is -fully operational, and fail. -Therefore, some mechanism is needed to allow clients to detect when an IM -server has started. -.LP -It is up to clients to decide what should be done when an IM server is -not available (for example, wait, or use some other IM server). -.LP -.IP \(bu 5 -Some input methods may allow the underlying IM server to be switched. -Such customization may be desired without restarting the entire client. -.LP -To support management of input methods in these cases, the following -functions are provided: -.TS -lw(2.4i) lw(3.3i). -T{ -.PN XRegisterIMInstantiateCallback -T} T{ -This function allows clients to register a callback procedure -to be called when Xlib detects that an IM server is up and available. -T} -T{ -.PN XOpenIM -T} T{ -A client calls this function as a result of the callback procedure -being called. -T} -T{ -.PN XSetIMValue , -.PN XSetICValue -T} T{ -These functions use the XIM and XIC values, -.PN XNDestroyCallback , -to allow a client -to register a callback procedure to be called when Xlib detects that -an IM server that was associated with an opened -input method is no longer available. -.sp 4p -In addition, this function can be used to switch IM servers for those input -methods that support such functionality. The IM value for switching IM -servers is implementation-dependent; see the description below about -switching IM servers. -T} -T{ -.PN XUnregisterIMInstantiateCallback -T} T{ -This function removes a callback procedure registered by the client. -T} -.TE -.LP -Input methods that support switching of IM servers may exhibit some -side-effects: -.IP \(bu 5 -The input method will ensure that any new IM server supports any of the -input styles being used by input contexts already associated with the -input method. -However, the list of supported input styles may be different. -.LP -.IP \(bu 5 -Geometry management requests on previously created input contexts -may be initiated by the new IM server. -.LP -.NH 4 -Hot Keys -.XS -\*(SN Hot Keys -.XE -.LP -Some clients need to guarantee which keys can be used to escape from the -input method, regardless of the input method state; -for example, the client-specific Help key or the keys to move the -input focus. -The HotKey mechanism allows clients -to specify a set of keys for this purpose. However, the input -method might not allow clients to specify hot keys. -Therefore, clients have to query support of hot keys by checking the -supported XIC values list by calling -.PN XGetIMValues -with the -.PN XNQueryICValuesList -IM value. -When the hot keys specified conflict with the key bindings of the -input method, hot keys take precedence over the key bindings of the input -method. -.LP -.NH 4 -Preedit State Operation -.XS -\*(SN Preedit State Operation -.XE -.LP -An input method may have several internal states, depending on its -implementation and the locale. However, one state that is -independent of locale and implementation is whether the input method -is currently performing a preediting operation. -Xlib provides the ability for an application to manage the preedit state -programmatically. Two methods are provided for -retrieving the preedit state of an input context. -One method is to query the state by calling -.PN XGetICValues -with the -.PN XNPreeditState -XIC value. -Another method is to receive notification whenever -the preedit state is changed. To receive such notification, -an application needs to register a callback by calling -.PN XSetICValues -with the -.PN XNPreeditStateNotifyCallback -XIC value. -In order to change the preedit state programmatically, an application -needs to call -.PN XSetICValues -with -.PN XNPreeditState. -.LP -Availability of the preedit state is input method dependent. The input -method may not provide the ability to set the state or to -retrieve the state programmatically. Therefore, clients have to -query availability of preedit state operations by checking the -supported XIC values list by calling -.PN XGetIMValues -with the -.PN XNQueryICValuesList -IM value. -.NH 3 -Input Method Functions -.XS -\*(SN Input Method Functions -.XE -.LP -To open a connection, use -.PN XOpenIM . -.IN "XOpenIM" "" "@DEF@" -.sM -.FD 0 -XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XrmDatabase \fIdb\fP\^; -.br - char *\fIres_name\fP\^; -.br - char *\fIres_class\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdb\fP 1i -Specifies a pointer to the resource database. -.IP \fIres_name\fP 1i -Specifies the full resource name of the application. -.IP \fIres_class\fP 1i -Specifies the full class name of the application. -.LP -.eM -The -.PN XOpenIM -function opens an input method, -matching the current locale and modifiers specification. -Current locale and modifiers are bound to the input method at opening time. -The locale associated with an input method cannot be changed dynamically. -This implies that the strings returned by -.PN XmbLookupString -or -.PN XwcLookupString , -for any input context affiliated with a given input method, -will be encoded in the locale current at the time the input method is opened. -.LP -The specific input method to which this call will be routed -is identified on the basis of the current locale. -.PN XOpenIM -will identify a default input method corresponding to the -current locale. -That default can be modified using -.PN XSetLocaleModifiers -for the input method modifier. -.LP -The db argument is the resource database to be used by the input method -for looking up resources that are private to the input method. -It is not intended that this database be used to look -up values that can be set as IC values in an input context. -If db is NULL, -no database is passed to the input method. -.LP -The res_name and res_class arguments specify the resource name -and class of the application. -They are intended to be used as prefixes by the input method -when looking up resources that are common to all input contexts -that may be created for this input method. -The characters used for resource names and classes must be in the -X Portable Character Set. -The resources looked up are not fully specified -if res_name or res_class is NULL. -.LP -The res_name and res_class arguments are not assumed to exist beyond -the call to -.PN XOpenIM . -The specified resource database is assumed to exist for the lifetime -of the input method. -.LP -.PN XOpenIM -returns NULL if no input method could be opened. -.LP -.sp -To close a connection, use -.PN XCloseIM . -.IN "XCloseIM" "" "@DEF@" -.sM -.FD 0 -Status XCloseIM\^(\^\fIim\fP\^) -.br - XIM \fIim\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.LP -.eM -The -.PN XCloseIM -function closes the specified input method. -.LP -.sp -To set input method attributes, use -.PN XSetIMValues . -.IN "XSetIMValues" "" "@DEF@" -.sM -.FD 0 -char * XSetIMValues\^(\^\fIim\fP\^, ...) -.br - XIM \fIim\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.ds Al \ to set XIM values -.IP ... 1i -Specifies the variable-length argument list\*(Al. -.LP -.eM -The -.PN XSetIMValues -function presents a variable argument list programming interface -for setting attributes of the specified input method. -It returns NULL if it succeeds; -otherwise, -it returns the name of the first argument that could not be set. -Xlib does not attempt to set arguments from the supplied list that -follow the failed argument; -all arguments in the list preceding the failed argument have been set -correctly. -.LP -.sp -To query an input method, use -.PN XGetIMValues . -.IN "XGetIMValues" "" "@DEF@" -.sM -.FD 0 -char * XGetIMValues\^(\^\fIim\fP\^, ...) -.br - XIM \fIim\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.ds Al \ to get XIM values -.IP ... 1i -Specifies the variable length argument list\*(Al. -.LP -.eM -The -.PN XGetIMValues -function presents a variable argument list programming interface -for querying properties or features of the specified input method. -This function returns NULL if it succeeds; -otherwise, -it returns the name of the first argument that could not be obtained. -.LP -Each XIM value argument (following a name) must point to -a location where the XIM value is to be stored. -That is, if the XIM value is of type T, -the argument must be of type T*. -If T itself is a pointer type, -then -.PN XGetIMValues -allocates memory to store the actual data, -and the client is responsible for freeing this data by calling -.PN XFree -with the returned pointer. -.LP -.sp -To obtain the display associated with an input method, use -.PN XDisplayOfIM . -.IN "XDisplayOfIM" "" "@DEF@" -.sM -.FD 0 -Display * XDisplayOfIM\^(\^\fIim\fP\^) -.br - XIM \fIim\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.LP -.eM -The -.PN XDisplayOfIM -function returns the display associated with the specified input method. -.LP -.sp -To get the locale associated with an input method, use -.PN XLocaleOfIM . -.IN "XLocaleOfIM" "" "@DEF@" -.sM -.FD 0 -char * XLocaleOfIM\^(\^\fIim\fP\^) -.br - XIM \fIim\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.LP -.eM -The -.PN XLocaleOfIM -function returns the locale associated with the specified input method. -.LP -.sp -To register an input method instantiate callback, use -.PN XRegisterIMInstantiateCallback . -.IN "XRegisterIMInstantiateCallback" "" "@DEF@" -.sM -.FD 0 -Bool XRegisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XrmDatabase \fIdb\fP\^; -.br - char *\fIres_name\fP\^; -.br - char *\fIres_class\fP\^; -.br - XIMProc \fIcallback\fP\^; -.br - XPointer *\fIclient_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdb\fP 1i -Specifies a pointer to the resource database. -.IP \fIres_name\fP 1i -Specifies the full resource name of the application. -.IP \fIres_class\fP 1i -Specifies the full class name of the application. -.IP \fIcallback\fP 1i -Specifies a pointer to the input method instantiate callback. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.LP -.eM -The -.PN XRegisterIMInstantiateCallback -function registers a callback to be invoked whenever a new input method -becomes available for the specified display that matches the current -locale and modifiers. -.LP -The function returns -.PN True - if it succeeds; otherwise, it returns -.PN False . -.LP -The generic prototype is as follows: -.IN "IMInstantiateCallback" "" "@DEF@" -.sM -.FD 0 -void IMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -To unregister an input method instantiation callback, use -.PN XUnregisterIMInstantiateCallback . -.IN "XUnregisterIMInstantiateCallback" "" "@DEF@" -.sM -.FD 0 -Bool XUnregisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XrmDatabase \fIdb\fP\^; -.br - char *\fIres_name\fP\^; -.br - char *\fIres_class\fP\^; -.br - XIMProc \fIcallback\fP\^; -.br - XPointer *\fIclient_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdb\fP 1i -Specifies a pointer to the resource database. -.IP \fIres_name\fP 1i -Specifies the full resource name of the application. -.IP \fIres_class\fP 1i -Specifies the full class name of the application. -.IP \fIcallback\fP 1i -Specifies a pointer to the input method instantiate callback. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.LP -.eM -The -.PN XUnregisterIMInstantiateCallback -function removes an input method instantiation callback previously -registered. -The function returns -.PN True -if it succeeds; otherwise, it returns -.PN False . -.NH 3 -Input Method Values -.XS -\*(SN Input Method Values -.XE -.LP -The following table describes how XIM values are interpreted -by an input method. -The first column lists the XIM values. -The second column indicates how each of the XIM values -are treated by that input style. -.LP -.LP -The following keys apply to this table. -.TS H -lw(1i) lw(4.75i). -_ -.sp 6p -.B -Key Explanation -.sp 6p -_ -.TH -.R -D T{ -This value may be set using -.PN XSetIMValues . -If it is not set, -.br -a default is provided. -T} -S T{ -This value may be set using -.PN XSetIMValues . -T} -G T{ -This value may be read using -.PN XGetIMValues . -T} -.sp 6p -_ -.TE -.LP -.TS H -lw(2.25i) c -lw(2.25i) c. -_ -.sp 6p -.B -XIM Value Key -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN XNQueryInputStyle -T} T{ -G -T} -T{ -.PN XNResourceName -T} T{ -D-S-G -T} -T{ -.PN XNResourceClass -T} T{ -D-S-G -T} -T{ -.PN XNDestroyCallback -T} T{ -D-S-G -T} -T{ -.PN XNQueryIMValuesList -T} T{ -G -T} -T{ -.PN XNQueryICValuesList -T} T{ -G -T} -T{ -.PN XNVisiblePosition -T} T{ -G -T} -T{ -.PN XNR6PreeditCallbackBehavior -T} T{ -D-S-G -T} -.sp 6p -_ -.TE -.LP -.PN XNR6PreeditCallbackBehavior -is obsolete and its use is not recommended (see section 13.5.4.6). -.LP -.NH 4 -Query Input Style -.XS -\*(SN Query Input Style -.XE -.LP -A client should always query the input method to determine which input -styles are supported. -The client should then find an input style it is capable of supporting. -.LP -If the client cannot find an input style that it can support, -it should negotiate with the user the continuation of the program -(exit, choose another input method, and so on). -.LP -The argument value must be a pointer to a location -where the returned value will be stored. -The returned value is a pointer to a structure of type -.PN XIMStyles . -Clients are responsible for freeing the -.PN XIMStyles -structure. -To do so, use -.PN XFree . -.LP -The -.PN XIMStyles -structure is defined as follows: -.LP -.IN "XIMStyle" "" "@DEF@" -.IN "XIMPreeditArea" "" "@DEF@" -.IN "XIMPreeditCallbacks" "" "@DEF@" -.IN "XIMPreeditPosition" "" "@DEF@" -.IN "XIMPreeditNothing" "" "@DEF@" -.IN "XIMPreeditNone" "" "@DEF@" -.IN "XIMStatusArea" "" "@DEF@" -.IN "XIMStatusCallbacks" "" "@DEF@" -.IN "XIMStatusNothing" "" "@DEF@" -.IN "XIMStatusNone" "" "@DEF@" -.IN "XIMStyles" "" "@DEF@" -.sM -.Ds 0 -typedef unsigned long XIMStyle; -.De -.TS -lw(.5i) lw(2i) lw(2.5i). -T{ -#define -T} T{ -.PN XIMPreeditArea -T} T{ -0x0001L -T} -T{ -#define -T} T{ -.PN XIMPreeditCallbacks -T} T{ -0x0002L -T} -T{ -#define -T} T{ -.PN XIMPreeditPosition -T} T{ -0x0004L -T} -T{ -#define -T} T{ -.PN XIMPreeditNothing -T} T{ -0x0008L -T} -T{ -#define -T} T{ -.PN XIMPreeditNone -T} T{ -0x0010L -T} -.sp -T{ -#define -T} T{ -.PN XIMStatusArea -T} T{ -0x0100L -T} -T{ -#define -T} T{ -.PN XIMStatusCallbacks -T} T{ -0x0200L -T} -T{ -#define -T} T{ -.PN XIMStatusNothing -T} T{ -0x0400L -T} -T{ -#define -T} T{ -.PN XIMStatusNone -T} T{ -0x0800L -T} -.TE -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - unsigned short count_styles; - XIMStyle * supported_styles; -} XIMStyles; -.De -.LP -.eM -An -.PN XIMStyles -structure contains the number of input styles supported -in its count_styles field. -This is also the size of the supported_styles array. -.LP -The supported styles is a list of bitmask combinations, -which indicate the combination of styles for each of the areas supported. -These areas are described later. -Each element in the list should select one of the bitmask values for -each area. -The list describes the complete set of combinations supported. -Only these combinations are supported by the input method. -.LP -The preedit category defines what type of support is provided -by the input method for preedit information. -.IN "XIMPreeditArea" "" "@DEF@" -.IN "XIMPreeditPosition" "" "@DEF@" -.IN "XIMPreeditCallbacks" "" "@DEF@" -.IN "XIMPreeditNothing" "" "@DEF@" -.IN "XIMPreeditNone" "" "@DEF@" -.TS -lw(1.5i) lw(4.25i). -T{ -.PN XIMPreeditArea -T} T{ -If chosen, -the input method would require the client to provide some area values -for it to do its preediting. -Refer to XIC values -.PN XNArea -and -.PN XNAreaNeeded . -T} -T{ -.PN XIMPreeditPosition -T} T{ -If chosen, -the input method would require the client to provide positional values. -Refer to XIC values -.PN XNSpotLocation -and -.PN XNFocusWindow . -T} -T{ -.PN XIMPreeditCallbacks -T} T{ -If chosen, -the input method would require the client to define the set of preedit callbacks. -Refer to XIC values -.PN XNPreeditStartCallback , -.PN XNPreeditDoneCallback , -.PN XNPreeditDrawCallback , -and -.PN XNPreeditCaretCallback . -T} -T{ -.PN XIMPreeditNothing -T} T{ -If chosen, the input method can function without any preedit values. -T} -T{ -.PN XIMPreeditNone -T} T{ -The input method does not provide any preedit feedback. -Any preedit value is ignored. -This style is mutually exclusive with the other preedit styles. -T} -.TE -.LP -The status category defines what type of support is provided -by the input method for status information. -.IN "XIMStatusArea" "" "@DEF@" -.IN "XIMStatusCallbacks" "" "@DEF@" -.IN "XIMStatusNothing" "" "@DEF@" -.IN "XIMStatusNone" "" "@DEF@" -.TS -lw(1.5i) lw(4.25i). -T{ -.PN XIMStatusArea -T} T{ -The input method requires the client to provide -some area values for it to do its status feedback. -See -.PN XNArea -and -.PN XNAreaNeeded . -T} -T{ -.PN XIMStatusCallbacks -T} T{ -The input method requires the client to define the set of status callbacks, -.PN XNStatusStartCallback , -.PN XNStatusDoneCallback , -and -.PN XNStatusDrawCallback . -T} -T{ -.PN XIMStatusNothing -T} T{ -The input method can function without any status values. -T} -T{ -.PN XIMStatusNone -T} T{ -The input method does not provide any status feedback. -If chosen, any status value is ignored. -This style is mutually exclusive with the other status styles. -T} -.TE -.NH 4 -Resource Name and Class -.XS -\*(SN Resource Name and Class -.XE -.LP -The -.PN XNResourceName -and -.PN XNResourceClass -arguments are strings that specify the full name and class -used by the input method. -These values should be used as prefixes for the name and class -when looking up resources that may vary according to the input method. -If these values are not set, -the resources will not be fully specified. -.LP -It is not intended that values that can be set as XIM values be -set as resources. -.LP -.NH 4 -Destroy Callback -.XS -\*(SN Destroy Callback -.XE -.LP -The -.PN XNDestroyCallback -argument is a pointer to a structure of type -.PN XIMCallback . -.PN XNDestroyCallback -is triggered when an input method stops its service for any reason. -After the callback is invoked, the input method is closed and the -associated input context(s) are destroyed by Xlib. -Therefore, the client should not call -.PN XCloseIM -or -.PN XDestroyIC . -.LP -The generic prototype of this callback function is as follows: -.IN "DestroyCallback" "" "@DEF@" -.sM -.FD 0 -void DestroyCallback\^(\^\fIim\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIM \fIim\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -A DestroyCallback is always called with a NULL call_data argument. -.LP -.NH 4 -Query IM/IC Values List -.XS -\*(SN Query IM/IC Values List -.XE -.LP -.PN XNQueryIMValuesList -and -.PN XNQueryICValuesList -are used to query about XIM and XIC values supported by the input method. -.LP -The argument value must be a pointer to a location where the returned -value will be stored. The returned value is a pointer to a structure -of type -.PN XIMValuesList . -Clients are responsible for freeing the -.PN XIMValuesList -structure. -To do so, use -.PN XFree . -.LP -The -.PN XIMValuesList -structure is defined as follows: -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - unsigned short count_values; - char **supported_values; -} XIMValuesList; -.De -.LP -.eM -.NH 4 -Visible Position -.XS -\*(SN Visible Position -.XE -.LP -The -.PN XNVisiblePosition -argument indicates whether the visible position masks of -.PN XIMFeedback -in -.PN XIMText -are available. -.LP -The argument value must be a pointer to a location where the returned -value will be stored. The returned value is of type -.PN Bool . -If the returned value is -.PN True , -the input method uses the visible position masks of -.PN XIMFeedback -in -.PN XIMText ; -otherwise, the input method does not use the masks. -.LP -Because this XIM value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryIMValues -before using this argument. -If the -.PN XNVisiblePosition -does not exist in the IM values list returned from -.PN XNQueryIMValues , -the visible position masks of -.PN XIMFeedback -in -.PN XIMText -are not used to indicate the visible position. -.LP -.NH 4 -Preedit Callback Behavior -.XS -\*(SN Preedit Callback Behavior -.XE -.LP -The -.PN XNR6PreeditCallbackBehavior -argument originally included in the X11R6 specification has been -deprecated.\(dg -.\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -.\" should be changed from *Bool to Bool. -.FS \(dg -During formulation of the X11R6 specification, the behavior of -the R6 PreeditDrawCallbacks was going to differ significantly from -that of the R5 callbacks. -Late changes to the specification converged the R5 and R6 behaviors, -eliminating the need for -.PN XNR6PreeditCallbackBehavior . -Unfortunately, this argument was not removed from the R6 specification -before it was published. -.FE -.LP -The -.PN XNR6PreeditCallbackBehavior -argument indicates whether the behavior of preedit callbacks regarding -.PN XIMPreeditDrawCallbackStruct -values follows Release 5 or Release 6 semantics. -.LP -The value is of type -.PN Bool . -When querying for -.PN XNR6PreeditCallbackBehavior , -if the returned value is -.PN True , -the input method uses the Release 6 behavior; -otherwise, it uses the Release 5 behavior. -The default value is -.PN False . -In order to use Release 6 semantics, the value of -.PN XNR6PreeditCallbackBehavior -must be set to -.PN True . -.LP -Because this XIM value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryIMValues -before using this argument. -If the -.PN XNR6PreeditCallbackBehavior -does not exist in the IM values list returned from -.PN XNQueryIMValues , -the PreeditCallback behavior is Release 5 semantics. -.LP -.NH 3 -Input Context Functions -.XS -\*(SN Input Context Functions -.XE -.LP -An input context is an abstraction that is used to contain both the data -required (if any) by an input method and the information required -to display that data. -There may be multiple input contexts for one input method. -The programming interfaces for creating, reading, or modifying -an input context use a variable argument list. -The name elements of the argument lists are referred to as XIC values. -It is intended that input methods be controlled by these XIC values. -As new XIC values are created, -they should be registered with the X Consortium. -.LP -.sp -To create an input context, use -.PN XCreateIC . -.IN "XCreateIC" "" "@DEF@" -.sM -.FD 0 -XIC XCreateIC\^(\^\fIim\fP\^, ...) -.br - XIM \fIim\fP\^; -.FN -.IP \fIim\fP 1i -Specifies the input method. -.ds Al \ to set XIC values -.IP ... 1i -Specifies the variable length argument list\*(Al. -.LP -.eM -The -.PN XCreateIC -function creates a context within the specified input method. -.LP -Some of the arguments are mandatory at creation time, and -the input context will not be created if those arguments are not provided. -The mandatory arguments are the input style and the set of text callbacks -(if the input style selected requires callbacks). -All other input context values can be set later. -.LP -.PN XCreateIC -returns a NULL value if no input context could be created. -A NULL value could be returned for any of the following reasons: -.IP \(bu 5 -A required argument was not set. -.IP \(bu 5 -A read-only argument was set (for example, -.PN XNFilterEvents ). -.IP \(bu 5 -The argument name is not recognized. -.IP \(bu 5 -The input method encountered an input method implementation-dependent error. -.LP -.PN XCreateIC -can generate -.PN BadAtom , -.PN BadColor , -.PN BadPixmap , -and -.PN BadWindow -errors. -.LP -.sp -To destroy an input context, use -.PN XDestroyIC . -.IN "XDestroyIC" "" "@DEF@" -.sM -.FD 0 -void XDestroyIC\^(\^\fIic\fP\^) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.LP -.eM -.PN XDestroyIC -destroys the specified input context. -.LP -.sp -To communicate to and synchronize with input method -for any changes in keyboard focus from the client side, -use -.PN XSetICFocus -and -.PN XUnsetICFocus . -.IN "XSetICFocus" "" "@DEF@" -.sM -.FD 0 -void XSetICFocus\^(\^\fIic\fP\^) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.LP -.eM -The -.PN XSetICFocus -function allows a client to notify an input method that the focus window -attached to the specified input context has received keyboard focus. -The input method should take action to provide appropriate feedback. -Complete feedback specification is a matter of user interface policy. -.LP -Calling -.PN XSetICFocus -does not affect the focus window value. -.LP -.sp -.IN "XUnsetICFocus" "" "@DEF@" -.sM -.FD 0 -void XUnsetICFocus\^(\^\fIic\fP\^) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.LP -.eM -The -.PN XUnsetICFocus -function allows a client to notify an input method that the specified input context -has lost the keyboard focus and that no more input is expected on the focus window -attached to that input context. -The input method should take action to provide appropriate feedback. -Complete feedback specification is a matter of user interface policy. -.LP -Calling -.PN XUnsetICFocus -does not affect the focus window value; -the client may still receive -events from the input method that are directed to the focus window. -.LP -.sp -To reset the state of an input context to its initial state, use -.PN XmbResetIC -or -.PN XwcResetIC . -.IN "XmbResetIC" "" "@DEF@" -.IN "XwcResetIC" "" "@DE@" -.sM -.FD 0 -char * XmbResetIC\^(\^\fIic\fP\^) -.br - XIC \fIic\fP\^; -.FN -.FD 0 -wchar_t * XwcResetIC\^(\^\fIic\fP\^) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.LP -.eM -When -.PN XNResetState -is set to -.PN XIMInitialState , -.PN XmbResetIC -and -.PN XwcResetIC -reset an input context to its initial state; -when -.PN XNResetState -is set to -.PN XIMPreserveState , -the current input context state is preserved. -In both cases, any input pending on that context is deleted. -The input method is required to clear the preedit area, if any, -and update the status accordingly. -Calling -.PN XmbResetIC -or -.PN XwcResetIC -does not change the focus. -.LP -The return value of -.PN XmbResetIC -is its current preedit string as a multibyte string. -If there is any preedit text drawn or visible to the user, -then these procedures must return a non-NULL string. -If there is no visible preedit text, -then it is input method implementation-dependent -whether these procedures return a non-NULL string or NULL. -.LP -The client should free the returned string by calling -.PN XFree . -.LP -.sp -To get the input method associated with an input context, use -.PN XIMOfIC . -.IN "XIMOfIC" "" "@DEF@" -.sM -.FD 0 -XIM XIMOfIC\^(\^\fIic\fP\^) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.LP -.eM -The -.PN XIMOfIC -function returns the input method associated with the specified input context. -.LP -.sp -Xlib provides two functions for setting and reading XIC values, respectively, -.PN XSetICValues -and -.PN XGetICValues . -Both functions have a variable-length argument list. -In that argument list, any XIC value's name must be denoted -with a character string using the X Portable Character Set. -.LP -.sp -To set XIC values, use -.PN XSetICValues . -.IN "XSetICValues" "" "@DEF@" -.sM -.FD 0 -char * XSetICValues\^(\^\fIic\fP\^, ...) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.ds Al \ to set XIC values -.IP ... 1i -Specifies the variable length argument list\*(Al. -.LP -.eM -The -.PN XSetICValues -function returns NULL if no error occurred; -otherwise, -it returns the name of the first argument that could not be set. -An argument might not be set for any of the following reasons: -.IP \(bu 5 -The argument is read-only (for example, -.PN XNFilterEvents ). -.IP \(bu 5 -The argument name is not recognized. -.IP \(bu 5 -An implementation-dependent error occurs. -.LP -Each value to be set must be an appropriate datum, -matching the data type imposed by the semantics of the argument. -.LP -.PN XSetICValues -can generate -.PN BadAtom , -.PN BadColor , -.PN BadCursor , -.PN BadPixmap , -and -.PN BadWindow -errors. -.LP -.sp -To obtain XIC values, use -.PN XGetICValues . -.IN "XGetICValues" "" "@DEF@" -.sM -.FD 0 -char * XGetICValues\^(\^\fIic\fP\^, ...) -.br - XIC \fIic\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.ds Al \ to get XIC values -.IP ... 1i -Specifies the variable length argument list\*(Al. -.LP -.eM -The -.PN XGetICValues -function returns NULL if no error occurred; otherwise, -it returns the name of the first argument that could not be obtained. -An argument could not be obtained for any of the following reasons: -.IP \(bu 5 -The argument name is not recognized. -.IP \(bu 5 -The input method encountered an implementation-dependent error. -.LP -Each IC attribute value argument (following a name) must point to -a location where the IC value is to be stored. -That is, if the IC value is of type T, -the argument must be of type T*. -If T itself is a pointer type, -then -.PN XGetICValues -allocates memory to store the actual data, -and the client is responsible for freeing this data by calling -.PN XFree -with the returned pointer. -The exception to this rule is for an IC value of type -.PN XVaNestedList -(for preedit and status attributes). -In this case, the argument must also be of type -.PN XVaNestedList . -Then, the rule of changing type T to T* and freeing the allocated data -applies to each element of the nested list. -.NH 3 -Input Context Values -.XS -\*(SN Input Context Values -.XE -.LP -The following tables describe how XIC values are interpreted -by an input method depending on the input style chosen by the -user. -.LP -The first column lists the XIC values. -The second column indicates which values are involved in affecting, -negotiating, and setting the geometry of the input method windows. -The subentries under the third column indicate the different -input styles that are supported. -Each of these columns indicates how each of the XIC values -are treated by that input style. -.LP -The following keys apply to these tables. -.TS H -lw(1i) lw(4.75i). -_ -.sp 6p -.B -Key Explanation -.sp 6p -_ -.TH -.R -C T{ -This value must be set with -.PN XCreateIC . -T} -D T{ -This value may be set using -.PN XCreateIC . -If it is not set, -a default is provided. -T} -G T{ -This value may be read using -.PN XGetICValues . -T} -GN T{ -This value may cause geometry negotiation when its value is set by means of -.PN XCreateIC -or -.PN XSetICValues . -T} -GR T{ -This value will be the response of the input method when any -GN value is changed. -T} -GS T{ -This value will cause the geometry of the input method window to be set. -T} -O T{ -This value must be set once and only once. -It need not be set at create time. -T} -S T{ -This value may be set with -.PN XSetICValues . -T} -Ignored T{ -This value is ignored by the input method for the given input style. -T} -.sp 6p -_ -.TE -.LP -.TS H -c c c s s s s -l c c c c c c -c c c c c c c -l c c c c c c. -_ -.sp 6p -.B - Input Style -XIC Value Geometry Preedit Preedit Preedit Preedit Preedit - Management Callback Position Area Nothing None -.sp 6p -_ -.sp 6p -.TH -.R -Input Style C-G C-G C-G C-G C-G -Client Window O-G O-G O-G O-G Ignored -Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored -Resource Name Ignored D-S-G D-S-G D-S-G Ignored -Resource Class Ignored D-S-G D-S-G D-S-G Ignored -Geometry Callback Ignored Ignored D-S-G Ignored Ignored -Filter Events G G G G Ignored -Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G -String Conversion Callback S-G S-G S-G S-G S-G -String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G -Reset State D-S-G D-S-G D-S-G D-S-G Ignored -HotKey S-G S-G S-G S-G Ignored -HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored -.sp 6p -\fBPreedit\fP -Area GS Ignored D-S-G D-S-G Ignored Ignored -Area Needed GN-GR Ignored Ignored S-G Ignored Ignored -Spot Location Ignored D-S-G Ignored Ignored Ignored -Colormap Ignored D-S-G D-S-G D-S-G Ignored -Foreground Ignored D-S-G D-S-G D-S-G Ignored -Background Ignored D-S-G D-S-G D-S-G Ignored -Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored -Font Set GN Ignored D-S-G D-S-G D-S-G Ignored -Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored -Cursor Ignored D-S-G D-S-G D-S-G Ignored -Preedit State D-S-G D-S-G D-S-G D-S-G Ignored -Preedit State Notify Callback S-G S-G S-G S-G Ignored -Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored -.sp 6p -_ -.TE -.LP -.TS H -c c c s s s -l c c c c c -c c c c c c -l c c c c c. -_ -.sp 6p -.B - Input Style -XIC Value Geometry Status Status Status Status - Management Callback Area Nothing None -.sp 6p -_ -.sp 6p -.TH -.R -Input Style C-G C-G C-G C-G -Client Window O-G O-G O-G Ignored -Focus Window GN D-S-G D-S-G D-S-G Ignored -Resource Name Ignored D-S-G D-S-G Ignored -Resource Class Ignored D-S-G D-S-G Ignored -Geometry Callback Ignored D-S-G Ignored Ignored -Filter Events G G G G -.sp 6p -\fBStatus\fP -Area GS Ignored D-S-G Ignored Ignored -Area Needed GN-GR Ignored S-G Ignored Ignored -Colormap Ignored D-S-G D-S-G Ignored -Foreground Ignored D-S-G D-S-G Ignored -Background Ignored D-S-G D-S-G Ignored -Background Pixmap Ignored D-S-G D-S-G Ignored -Font Set GN Ignored D-S-G D-S-G Ignored -Line Spacing GN Ignored D-S-G D-S-G Ignored -Cursor Ignored D-S-G D-S-G Ignored -Status Callbacks C-S-G Ignored Ignored Ignored -.sp 6p -_ -.TE -.NH 4 -Input Style -.XS -\*(SN Input Style -.XE -.LP -The -.PN XNInputStyle -argument specifies the input style to be used. -The value of this argument must be one of the values returned by the -.PN XGetIMValues -function with the -.PN XNQueryInputStyle -argument specified in the supported_styles list. -.LP -Note that this argument must be set at creation time -and cannot be changed. -.NH 4 -Client Window -.XS -\*(SN Client Window -.XE -.LP -.IN "XNClientWindow" "" "@DEF@" -The -.PN XNClientWindow -argument specifies to the input method the client window in -which the input method -can display data or create subwindows. -Geometry values for input method areas are given with respect to the client -window. -Dynamic change of client window is not supported. -This argument may be set only once and -should be set before any input is done using this input context. -If it is not set, -the input method may not operate correctly. -.LP -If an attempt is made to set this value a second time with -.PN XSetICValues , -the string -.PN XNClientWindow -will be returned by -.PN XSetICValues , -and the client window will not be changed. -.LP -If the client window is not a valid window ID on the display -attached to the input method, -a -.PN BadWindow -error can be generated when this value is used by the input method. -.NH 4 -Focus Window -.XS -\*(SN Focus Window -.XE -.LP -.IN "XNFocusWindow" "" "@DEF@" -The -.PN XNFocusWindow -argument specifies the focus window. -The primary purpose of the -.PN XNFocusWindow -is to identify the window that will receive the key event when input -is composed. -In addition, the input method may possibly affect the focus window -as follows: -.IP \(bu 5 -Select events on it -.IP \(bu 5 -Send events to it -.IP \(bu 5 -Modify its properties -.IP \(bu 5 -Grab the keyboard within that window -.LP -The associated value must be of type -.PN Window . -If the focus window is not a valid window ID on the display -attached to the input method, -a -.PN BadWindow -error can be generated when this value is used by the input method. -.LP -When this XIC value is left unspecified, -the input method will use the client window as the default focus window. -.NH 4 -Resource Name and Class -.XS -\*(SN Resource Name and Class -.XE -.LP -.IN "XNResourceName" "" "@DEF@" -.IN "XNResourceClass" "" "@DEF@" -The -.PN XNResourceName -and -.PN XNResourceClass -arguments are strings that specify the full name and class -used by the client to obtain resources for the client window. -These values should be used as prefixes for name and class -when looking up resources that may vary according to the input context. -If these values are not set, -the resources will not be fully specified. -.LP -It is not intended that values that can be set as XIC values be -set as resources. -.NH 4 -Geometry Callback -.XS -\*(SN Geometry Callback -.XE -.LP -.IN "XNGeometryCallback" "" "@DEF@" -The -.PN XNGeometryCallback -argument is a structure of type -.PN XIMCallback -(see section 13.5.6.13.12). -.LP -The -.PN XNGeometryCallback -argument specifies the geometry callback that a client can set. -This callback is not required for correct operation of either -an input method or a client. -It can be set for a client whose user interface policy permits -an input method to request the dynamic change of that input -method's window. -An input method that does dynamic change will need to filter any -events that it uses to initiate the change. -.NH 4 -Filter Events -.XS -\*(SN Filter Events -.XE -.LP -.IN "XNFilterEvents" "" "@DEF@" -The -.PN XNFilterEvents -argument returns the event mask that an input method needs -to have selected for. -The client is expected to augment its own event mask -for the client window with this one. -.LP -This argument is read-only, is set by the input method at create time, -and is never changed. -.LP -The type of this argument is -.PN unsigned -.PN long . -Setting this value will cause an error. -.NH 4 -Destroy Callback -.XS -\*(SN Destroy Callback -.XE -.LP -The -.PN XNDestroyCallback -argument is a pointer to a structure of type -.PN XIMCallback -(see section 13.5.6.13.12). This callback is triggered when the input method -stops its service for any reason; for example, when a connection to an IM -server is broken. After the destroy callback is called, -the input context is destroyed and the input method is closed. -Therefore, the client should not call -.PN XDestroyIC -and -.PN XCloseIM . -.LP -.NH 4 -String Conversion Callback -.XS -\*(SN String Conversion Callback -.XE -.LP -The -.PN XNStringConversionCallback -argument is a structure of type -.PN XIMCallback -(see section 13.5.6.13.12). -.LP -The -.PN XNStringConversionCallback -argument specifies a string conversion callback. This callback -is not required for correct operation of -either the input method or the client. It can be set by a client -to support string conversions that may be requested -by the input method. An input method that does string conversions -will filter any events that it uses to initiate the conversion. -.LP -Because this XIC value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryICValuesList -before using this argument. -.LP -.NH 4 -String Conversion -.XS -\*(SN String Conversion -.XE -.LP -The -.PN XNStringConversion -argument is a structure of type -.PN XIMStringConversionText . -.LP -The -.PN XNStringConversion -argument specifies the string to be converted by an input method. -This argument is not required for correct operation of either -the input method or the client. -.LP -String conversion facilitates the manipulation of text independent -of preediting. -It is essential for some input methods and clients to manipulate -text by performing context-sensitive conversion, -reconversion, or transliteration conversion on it. -.LP -Because this XIC value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryICValuesList -before using this argument. -.LP -The -.PN XIMStringConversionText -structure is defined as follows: -.LP -.sM -.Ds 0 - -typedef struct _XIMStringConversionText { - unsigned short length; - XIMStringConversionFeedback *feedback; - Bool encoding_is_wchar; - union { - char *mbs; - wchar_t *wcs; - } string; -} XIMStringConversionText; - -typedef unsigned long XIMStringConversionFeedback; -.De -.LP -.eM -The feedback member is reserved for future use. The text to be -converted is defined by the string and length members. The length -is indicated in characters. To prevent the library from freeing memory -pointed to by an uninitialized pointer, the client should set the feedback -element to NULL. -.LP -.NH 4 -Reset State -.XS -\*(SN Reset State -.XE -.LP -The -.PN XNResetState -argument specifies the state the input context will return to after calling -.PN XmbResetIC -or -.PN XwcResetIC . -.LP -The XIC state may be set to its initial state, as specified by the -.PN XNPreeditState -value when -.PN XCreateIC -was called, or it may be set to preserve the current state. -.LP -The valid masks for -.PN XIMResetState -are as follows: -.LP -.IN "XIMInitialState" "" "@DEF@" -.IN "XINPreserveState" "" "@DEF@" -.sM -.LP -.Ds 0 -typedef unsigned long XIMResetState; -.De -.TS -lw(.5i) lw(2i) lw(2i). -T{ -#define -T} T{ -.PN XIMInitialState -T} T{ -(1L) -T} -T{ -#define -T} T{ -.PN XIMPreserveState -T} T{ -(1L<<1) -T} -.TE -.LP -.eM -If -.PN XIMInitialState -is set, then -.PN XmbResetIC -and -.PN XwcResetIC -will return to the initial -.PN XNPreeditState -state of the XIC. -.LP -If -.PN XIMPreserveState -is set, then -.PN XmbResetIC -and -.PN XwcResetIC -will preserve the current state of the XIC. -.LP -If -.PN XNResetState -is left unspecified, the default is -.PN XIMInitialState . -.LP -.PN XIMResetState -values other than those specified above will default to -.PN XIMInitialState . -.LP -Because this XIC value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryICValuesList -before using this argument. -.LP -.NH 4 -Hot Keys -.XS -\*(SN Hot Keys -.XE -.LP -The -.PN XNHotKey -argument specifies the hot key list to the XIC. -The hot key list is a pointer to the structure of type -.PN XIMHotKeyTriggers , -which specifies the key events that must be received -without any interruption of the input method. -For the hot key list set with this argument to be utilized, the client -must also set -.PN XNHotKeyState -to -.PN XIMHotKeyStateON . -.LP -Because this XIC value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryICValuesList -before using this functionality. -.LP -The value of the argument is a pointer to a structure of type -.PN XIMHotKeyTriggers . -.LP -If an event for a key in the hot key list is found, then the process will -receive the event and it will be processed inside the client. -.LP -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - KeySym keysym; - unsigned int modifier; - unsigned int modifier_mask; -} XIMHotKeyTrigger; - -typedef struct { - int num_hot_key; - XIMHotKeyTrigger *key; -} XIMHotKeyTriggers; -.De -.LP -.eM -.LP -The combination of modifier and modifier_mask are used to represent one of -three states for each modifier: -either the modifier must be on, or the modifier must be off, or the modifier -is a ``don't care'' \- it may be on or off. -When a modifier_mask bit is set to 0, the state of the associated modifier -is ignored when evaluating whether the key is hot or not. -.TS H -lw(1i) lw(1i) lw(3i). -_ -.sp 6p -.B -Modifier Bit Mask Bit Meaning -.sp 6p -_ -.sp 6p -.TH -.R -T{ -0 -T} T{ -1 -T} T{ -The modifier must be off. -T} -T{ -1 -T} T{ -1 -T} T{ -The modifier must be on. -T} -T{ -n/a -T} T{ -0 -T} T{ -Do not care if the modifier is on or off. -T} -.sp 6p -_ -.TE -.NH 4 -Hot Key State -.XS -\*(SN Hot Key State -.XE -.LP -The -.PN XNHotKeyState -argument specifies the hot key state of the input method. -This is usually used to switch the input method between hot key -operation and normal input processing. -.LP -The value of the argument is a pointer to a structure of type -XIMHotKeyState . -.LP -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef unsigned long XIMHotKeyState; -.De -.TS -lw(.5i) lw(3i) lw(2i). -T{ -#define -T} T{ -.PN XIMHotKeyStateON -T} T{ -(0x0001L) -T} -T{ -#define -T} T{ -.PN XIMHotKeyStateOFF -T} T{ -(0x0002L) -T} -.TE -.LP -.eM -.LP -If not specified, the default is -.PN XIMHotKeyStateOFF . -.LP -.NH 4 -Preedit and Status Attributes -.XS -\*(SN Preedit and Status Attributes -.XE -.LP -.IN "XNPreeditAttributes" "" "@DEF@" -.IN "XNStatusAttributes" "" "@DEF@" -The -.PN XNPreeditAttributes -and -.PN XNStatusAttributes -arguments specify to an input method the attributes to be used for the -preedit and status areas, -if any. -Those attributes are passed to -.PN XSetICValues -or -.PN XGetICValues -as a nested variable-length list. -The names to be used in these lists are described in the following sections. -.NH 5 -Area -.XS -\*(SN Area -.XE -.LP -.IN "XNArea" "" "@DEF@" -The value of the -.PN XNArea -argument must be a pointer to a structure of type -.PN XRectangle. -The interpretation of the -.PN XNArea -argument is dependent on the input method style that has been set. -.LP -If the input method style is -.PN XIMPreeditPosition , -.PN XNArea -specifies the clipping region within which preediting will take place. -If the focus window has been set, -the coordinates are assumed to be relative to the focus window. -Otherwise, the coordinates are assumed to be relative to the client window. -If neither has been set, -the results are undefined. -.LP -If -.PN XNArea -is not specified, is set to NULL, or is invalid, -the input method will default the clipping region -to the geometry of the -.PN XNFocusWindow . -If the area specified is NULL or invalid, -the results are undefined. -.LP -If the input style is -.PN XIMPreeditArea -or -.PN XIMStatusArea , -.PN XNArea -specifies the geometry provided by the client to the input method. -The input method may use this area to display its data, -either preedit or status depending on the area designated. -The input method may create a window as a child of the client window -with dimensions that fit the -.PN XNArea . -The coordinates are relative to the client window. -If the client window has not been set yet, -the input method should save these values -and apply them when the client window is set. -If -.PN XNArea -is not specified, is set to NULL, or is invalid, -the results are undefined. -.NH 5 -Area Needed -.XS -\*(SN Area Needed -.XE -.LP -.IN "XNAreaNeeded" "" "@DEF@" -When set, the -.PN XNAreaNeeded -argument specifies the geometry suggested by the client for this area -(preedit or status). -The value associated with the argument must be a pointer to a -structure of type -.PN XRectangle . -Note that the x, y values are not used -and that nonzero values for width or height are the constraints -that the client wishes the input method to respect. -.LP -When read, the -.PN XNAreaNeeded -argument specifies the preferred geometry desired by the input method -for the area. -.LP -This argument is only valid if the input style is -.PN XIMPreeditArea -or -.PN XIMStatusArea . -It is used for geometry negotiation between the client and the input method -and has no other effect on the input method -(see section 13.5.1.5). -.NH 5 -Spot Location -.XS -\*(SN Spot Location -.XE -.LP -.IN "XNSpotLocation" "" "@DEF@" -The -.PN XNSpotLocation -argument specifies to the input method the coordinates of the spot -to be used by an input method executing with -.PN XNInputStyle -set to -.PN XIMPreeditPosition . -When specified to any input method other than -.PN XIMPreeditPosition , -this XIC value is ignored. -.LP -The x coordinate specifies the position where the next character -would be inserted. -The y coordinate is the position of the baseline used -by the current text line in the focus window. -The x and y coordinates are relative to the focus window, if it has been set; -otherwise, they are relative to the client window. -If neither the focus window nor the client window has been set, -the results are undefined. -.LP -The value of the argument is a pointer to a structure of type -.PN XPoint . -.NH 5 -Colormap -.XS -\*(SN Colormap -.XE -.LP -Two different arguments can be used to indicate what colormap the input method -should use to allocate colors, a colormap ID, or a standard colormap name. -.LP -.IN "XNColormap" "" "@DEF@" -The -.PN XNColormap -argument is used to specify a colormap ID. -The argument value is of type -.PN Colormap . -An invalid argument may generate a -.PN BadColor -error when it is used by the input method. -.LP -.IN "XNStdColormap" "" "@DEF@" -The -.PN XNStdColormap -argument is used to indicate the name of the standard colormap -in which the input method should allocate colors. -The argument value is an -.PN Atom -that should be a valid atom for calling -.PN XGetRGBColormaps . -An invalid argument may generate a -.PN BadAtom -error when it is used by the input method. -.LP -If the colormap is left unspecified, -the client window colormap becomes the default. -.NH 5 -Foreground and Background -.XS -\*(SN Foreground and Background -.XE -.LP -.IN "XNForeground" "" "@DEF@" -.IN "XNBackground" "" "@DEF@" -The -.PN XNForeground -and -.PN XNBackground -arguments specify the foreground and background pixel, respectively. -The argument value is of type -.PN unsigned -.PN long . -It must be a valid pixel in the input method colormap. -.LP -If these values are left unspecified, -the default is determined by the input method. -.NH 5 -Background Pixmap -.XS -\*(SN Background Pixmap -.XE -.LP -The -.PN XNBackgroundPixmap -argument specifies a background pixmap to be used as the background of the -window. -The value must be of type -.PN Pixmap . -An invalid argument may generate a -.PN BadPixmap -error when it is used by the input method. -.LP -If this value is left unspecified, -the default is determined by the input method. -.NH 5 -Font Set -.XS -\*(SN Font Set -.XE -.LP -.IN "XNFontSet" "" "@DEF@" -The -.PN XNFontSet -argument specifies to the input method what font set is to be used. -The argument value is of type -.PN XFontSet . -.LP -If this value is left unspecified, -the default is determined by the input method. -.NH 5 -Line Spacing -.XS -\*(SN Line Spacing -.XE -.LP -The -.PN XNLineSpace -argument specifies to the input method what line spacing is to be used -in the preedit window if more than one line is to be used. -This argument is of type -.PN int . -.LP -If this value is left unspecified, -the default is determined by the input method. -.NH 5 -Cursor -.XS -\*(SN Cursor -.XE -.LP -.IN "XNCursor" "" "DEF@" -The -.PN XNCursor -argument specifies to the input method what cursor is to be used -in the specified window. -This argument is of type -.PN Cursor . -.LP -An invalid argument may generate a -.PN BadCursor -error when it is used by the input method. -If this value is left unspecified, -the default is determined by the input method. -.NH 5 -Preedit State -.XS -\*(SN Preedit State -.XE -.LP -The -.PN XNPreeditState -argument specifies the state of input preediting for the input method. -Input preediting can be on or off. -.LP -The valid mask names for -.PN XNPreeditState -are as follows: -.LP -.IN "XIMPreeditUnknown" "" "@DEV@" -.IN "XIMPreeditEnable" "" "@DEF@" -.IN "XIMPreeditDisable" "" "@DEV@" -.sM -.LP -.Ds 0 -typedef unsigned long XIMPreeditState; -.De -.TS -lw(.5i) lw(2i) lw(2i). -T{ -#define -T} T{ -.PN XIMPreeditUnknown -T} T{ -0L -T} -T{ -#define -T} T{ -.PN XIMPreeditEnable -T} T{ -1L -T} -T{ -#define -T} T{ -.PN XIMPreeditDisable -T} T{ -(1L<<1) -T} -.TE -.LP -.eM -If a value of -.PN XIMPreeditEnable -is set, then input preediting is turned on by the input method. -.LP -If a value of -.PN XIMPreeditDisable -is set, then input preediting is turned off by the input method. -.LP -If -.PN XNPreeditState -is left unspecified, then the state will be implementation-dependent. -.LP -When -.PN XNResetState -is set to -.PN XIMInitialState , -the -.PN XNPreeditState -value specified at the creation time will be reflected as the initial state for -.PN XmbResetIC -and -.PN XwcResetIC . -.LP -Because this XIC value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryICValuesList -before using this argument. -.NH 5 -Preedit State Notify Callback -.XS -\*(SN Preedit State Notify Callback -.XE -.LP -The preedit state notify callback is triggered by the input method -when the preediting state has changed. -The value of the -.PN XNPreeditStateNotifyCallback -argument is a pointer to a structure of type -.PN XIMCallback . -The generic prototype is as follows: -.IN "PreeditStateNotifyCallback" "" "@DEF@" -.sM -.FD 0 -void PreeditStateNotifyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XIMPreeditStateNotifyCallbackStruct *\fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Specifies the current preedit state. -.LP -.eM -The -.PN XIMPreeditStateNotifyCallbackStruct -structure is defined as follows: -.LP -.IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XIMPreeditStateNotifyCallbackStruct { - XIMPreeditState state; -} XIMPreeditStateNotifyCallbackStruct; -.De -.LP -.eM -.LP -Because this XIC value is optional, a client should call -.PN XGetIMValues -with argument -.PN XNQueryICValuesList -before using this argument. -.NH 5 -Preedit and Status Callbacks -.XS -\*(SN Preedit and Status Callbacks -.XE -.LP -A client that wants to support the input style -.PN XIMPreeditCallbacks -must provide a set of preedit callbacks to the input method. -The set of preedit callbacks is as follows: -.IN "XNPreeditStartCallback" "" "@DEF@" -.IN "XNPreeditDoneCallback" "" "@DEF@" -.IN "XNPreeditDrawCallback" "" "@DEF@" -.IN "XNPreeditCaretCallback" "" "@DEF@" -.TS -lw(1.75i) lw(4i). -T{ -.PN XNPreeditStartCallback -T} T{ -This is called when the input method starts preedit. -T} -T{ -.PN XNPreeditDoneCallback -T} T{ -This is called when the input method stops preedit. -T} -T{ -.PN XNPreeditDrawCallback -T} T{ -This is called when a number of preedit keystrokes should be echoed. -T} -T{ -.PN XNPreeditCaretCallback -T} T{ -This is called to move the text insertion point within the preedit string. -T} -.TE -.LP -A client that wants to support the input style -.PN XIMStatusCallbacks -must provide a set of status callbacks to the input method. -The set of status callbacks is as follows: -.IN "XNStatusStartCallback" "" "@DEF@" -.IN "XNStatusDoneCallback" "" "@DEF@" -.IN "XNStatusDrawCallback" "" "@DEF@" -.TS -lw(1.75i) lw(4i). -T{ -.PN XNStatusStartCallback -T} T{ -This is called when the input method initializes the status area. -T} -T{ -.PN XNStatusDoneCallback -T} T{ -This is called when the input method no longer needs the status area. -T} -T{ -.PN XNStatusDrawCallback -T} T{ -This is called when updating of the status area is required. -T} -.TE -.LP -The value of any status or preedit argument is a pointer -to a structure of type -.PN XIMCallback . -.IN "XIMProc" "" "@DEF@" -.IN "XIMCallback" "" "@DEF@" -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef void (*XIMProc)(); - -typedef struct { - XPointer client_data; - XIMProc callback; -} XIMCallback; -.De -.LP -.eM -Each callback has some particular semantics and will carry the data -that expresses the environment necessary to the client -into a specific data structure. -This paragraph only describes the arguments to be used to set -the callback. -.LP -Setting any of these values while doing preedit -may cause unexpected results. -.NH 3 -Input Method Callback Semantics -.XS -\*(SN Input Method Callback Semantics -.XE -.LP -XIM callbacks are procedures defined by clients or text drawing packages -that are to be called from the input method when selected events occur. -Most clients will use a text editing package or a toolkit -and, hence, will not need to define such callbacks. -This section defines the callback semantics, when they are triggered, -and what their arguments are. -This information is mostly useful for X toolkit implementors. -.LP -Callbacks are mostly provided so that clients (or text editing -packages) can implement on-the-spot preediting in their own window. -In that case, -the input method needs to communicate and synchronize with the client. -The input method needs to communicate changes in the preedit window -when it is under control of the client. -Those callbacks allow the client to initialize the preedit area, -display a new preedit string, -move the text insertion point during preedit, -terminate preedit, or update the status area. -.LP -All callback procedures follow the generic prototype: -.IN "CallbackPrototype" "" "@DEF@" -.sM -.FD 0 -void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - SomeType \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Specifies data specific to the callback. -.LP -.eM -The call_data argument is a structure that expresses the arguments needed -to achieve the semantics; -that is, -it is a specific data structure appropriate to the callback. -In cases where no data is needed in the callback, -this call_data argument is NULL. -The client_data argument is a closure that has been initially specified -by the client when specifying the callback and passed back. -It may serve, for example, to inherit application context in the callback. -.LP -The following paragraphs describe the programming semantics -and specific data structure associated with the different reasons. -.NH 4 -Geometry Callback -.XS -\*(SN Geometry Callback -.XE -.LP -The geometry callback is triggered by the input method -to indicate that it wants the client to negotiate geometry. -The generic prototype is as follows: -.IN "GeometryCallback" "" "@DEF@" -.sM -.FD 0 -void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -The callback is called with a NULL call_data argument. -.NH 4 -Destroy Callback -.XS -\*(SN Destroy Callback -.XE -.LP -The destroy callback is triggered by the input method -when it stops service for any reason. -After the callback is invoked, the input context will be freed by Xlib. -The generic prototype is as follows: -.IN "DestroyCallback" "" "@DEF@" -.sM -.FD 0 -void DestroyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -The callback is called with a NULL call_data argument. -.NH 4 -String Conversion Callback -.XS -\*(SN String Conversion Callback -.XE -.LP -The string conversion callback is triggered by the input method -to request the client to return the string to be converted. The -returned string may be either a multibyte or wide character string, -with an encoding matching the locale bound to the input context. -The callback prototype is as follows: -.IN "StringConversionCallback" "" "@DEF@" -.sM -.FD 0 -void StringConversionCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XIMStringConversionCallbackStruct *\fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input method. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Specifies the amount of the string to be converted. -.LP -.eM -The callback is passed an -.PN XIMStringConversionCallbackStruct -structure in the call_data argument. -The text member is an -.PN XIMStringConversionText -structure (see section 13.5.6.9) to be filled in by the client -and describes the text to be sent to the input method. -The data pointed to by the -string and feedback elements of the -.PN XIMStringConversionText -structure will be freed using -.PN XFree -by the input method -after the callback returns. So the client should not point to -internal buffers that are critical to the client. -Similarly, because the feedback element is currently reserved for future -use, the client should set feedback to NULL to prevent the library from -freeing memory at some random location due to an uninitialized pointer. -.LP -The -.PN XIMStringConversionCallbackStruct -structure is defined as follows: -.LP -.IN "XIMStringConversionCallbackStruct" "" "@DEF@" -.sM -.LP -.Ds 0 -typedef struct _XIMStringConversionCallbackStruct { - XIMStringConversionPosition position; - XIMCaretDirection direction; - short factor; - XIMStringConversionOperation operation; - XIMStringConversionText *text; -} XIMStringConversionCallbackStruct; - -typedef short XIMStringConversionPosition; - -typedef unsigned short XIMStringConversionOperation; - -.De -.LP -.TS -lw(.5i) lw(3i) lw(2i). -T{ -#define -T} T{ -.PN XIMStringConversionSubstitution -T} T{ -(0x0001) -T} -T{ -#define -T} T{ -.PN XIMStringConversionRetrieval -T} T{ -(0x0002) -T} -.TE -.LP -.eM -.PN XIMStringConversionPosition -specifies the starting position of the string to be returned -in the -.PN XIMStringConversionText -structure. The value identifies a position, in units of characters, -relative to the client's cursor position in the client's buffer. -.LP -The ending position of the text buffer is determined by -the direction and factor members. Specifically, it is the character position -relative to the starting point as defined by the -.PN XIMCaretDirection . -The factor member of -.PN XIMStringConversionCallbackStruct -specifies the number of -.PN XIMCaretDirection -positions to be applied. For example, if the direction specifies -.PN XIMLineEnd -and factor is 1, then all characters from the starting position to -the end of the current display line are returned. If the direction -specifies -.PN XIMForwardChar -or -.PN XIMBackwardChar , -then the factor specifies a relative position, indicated in characters, -from the starting position. -.LP -.PN XIMStringConversionOperation -specifies whether the string to be converted should be -deleted (substitution) or copied (retrieval) from the client's -buffer. When the -.PN XIMStringConversionOperation -is -.PN XIMStringConversionSubstitution , -the client must delete the string to be converted from its own buffer. -When the -.PN XIMStringConversionOperation -is -.PN XIMStringConversionRetrieval , -the client must not delete the string to be converted from its buffer. -The substitute operation is typically used for reconversion and -transliteration conversion, -while the retrieval operation is typically used for context-sensitive -conversion. -.NH 4 -Preedit State Callbacks -.XS -\*(SN Preedit State Callbacks -.XE -.LP -When the input method turns preediting on or off, a -.PN PreeditStartCallback -or -.PN PreeditDoneCallback -callback is triggered to let the toolkit do the setup -or the cleanup for the preedit region. -.IN "PreeditStartCallback" "" "@DEF@" -.sM -.FD 0 -int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -When preedit starts on the specified input context, -the callback is called with a NULL call_data argument. -.PN PreeditStartCallback -will return the maximum size of the preedit string. -A positive number indicates the maximum number of bytes allowed -in the preedit string, -and a value of \-1 indicates there is no limit. -.IN "PreeditDoneCallback" "" "@DEF@" -.sM -.FD 0 -void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -When preedit stops on the specified input context, -the callback is called with a NULL call_data argument. -The client can release the data allocated by -.PN PreeditStartCallback . -.LP -.PN PreeditStartCallback -should initialize appropriate data needed for -displaying preedit information and for handling further -.PN PreeditDrawCallback -calls. -Once -.PN PreeditStartCallback -is called, it will not be called again before -.PN PreeditDoneCallback -has been called. -.NH 4 -Preedit Draw Callback -.XS -\*(SN Preedit Draw Callback -.XE -.LP -This callback is triggered to draw and insert, delete or replace, -preedit text in the preedit region. -The preedit text may include unconverted input text such as Japanese Kana, -converted text such as Japanese Kanji characters, or characters of both kinds. -That string is either a multibyte or wide character string, -whose encoding matches the locale bound to the input context. -The callback prototype -is as follows: -.IN "PreeditDrawCallback" "" "@DEF@" -.sM -.FD 0 -void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Specifies the preedit drawing information. -.LP -.eM -The callback is passed an -.PN XIMPreeditDrawCallbackStruct -structure in the call_data argument. -The text member of this structure contains the text to be drawn. -After the string has been drawn, -the caret should be moved to the specified location. -.LP -The -.PN XIMPreeditDrawCallbackStruct -structure is defined as follows: -.LP -.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XIMPreeditDrawCallbackStruct { - int caret; /* Cursor offset within preedit string */ - int chg_first; /* Starting change position */ - int chg_length; /* Length of the change in character count */ - XIMText *text; -} XIMPreeditDrawCallbackStruct; -.De -.LP -.eM -The client must keep updating a buffer of the preedit text -and the callback arguments referring to indexes in that buffer. -The call_data fields have specific meanings according to the operation, -as follows: -.IP \(bu 5 -To indicate text deletion, -the call_data member specifies a NULL text field. -The text to be deleted is then the current text in the buffer -from position chg_first (starting at zero) on a character length -of chg_length. -.IP \(bu 5 -When text is non-NULL, -it indicates insertion or replacement of text in the buffer. -.IP -The chg_length member -identifies the number of characters in the current preedit buffer -that are affected by this call. -A positive chg_length indicates that chg_length number of characters, starting -at chg_first, must be deleted or must be replaced by text, whose length is -specified in the -.PN XIMText -structure. -.IP -A chg_length value of zero indicates that text must be inserted -right at the position specified by chg_first. -A value of zero for chg_first specifies the first character in the buffer. -.IP -chg_length and chg_first combine to identify the modification required to -the preedit buffer; beginning at chg_first, replace chg_length number of -characters with the text in the supplied -.PN XIMText -structure. For example, suppose the preedit buffer contains the string "ABCDE". -.IP -.DS I -.ft C -Text: A B C D E - ^ ^ ^ ^ ^ ^ -CharPos: 0 1 2 3 4 5 -.sp -.ft P -.DE -The CharPos in the diagram shows the location of the character position -relative to the character. -.IP -If the value of chg_first is 1 and the value of chg_length is 3, this -says to replace 3 characters beginning at character position 1 with the -string in the -.PN XIMText -structure. -Hence, BCD would be replaced by the value in the structure. -.IP -Though chg_length and chg_first are both signed integers they will -never have a negative value. -.IP \(bu 5 -The caret member -identifies the character position before which the cursor should -be placed \- after modification to the preedit buffer has been completed. -For example, if caret is zero, the cursor is at -the beginning of the buffer. If the caret is one, the cursor is between -the first and second character. -.LP -.IN "XIMText" "" @DEF@" -.sM -.Ds -.TA .5i 1.5i 3i -typedef struct _XIMText { - unsigned short length; - XIMFeedback * feedback; - Bool encoding_is_wchar; - union { - char * multi_byte; - wchar_t * wide_char; - } string; -} XIMText; -.De -.LP -.eM -The text string passed is actually a structure specifying as follows: -.IP \(bu 5 -The length member is the text length in characters. -.IP \(bu 5 -The encoding_is_wchar member is a value that indicates -if the text string is encoded in wide character or multibyte format. -The text string may be passed either as multibyte or as wide character; -the input method controls in which form data is passed. -The client's -callback routine must be able to handle data passed in either form. -.IP \(bu 5 -The string member is the text string. -.IP \(bu 5 -The feedback member indicates rendering type for each character in the -string member. -If string is NULL (indicating that only highlighting of the existing -preedit buffer should be updated), feedback points to length highlight -elements that should be applied to the existing preedit buffer, beginning -at chg_first. -.LP -The feedback member expresses the types of rendering feedback -the callback should apply when drawing text. -Rendering of the text to be drawn is specified either in generic ways -(for example, primary, secondary) or in specific ways (reverse, underline). -When generic indications are given, -the client is free to choose the rendering style. -It is necessary, however, that primary and secondary be mapped -to two distinct rendering styles. -.LP -If an input method wants to control display of the preedit string, an -input method can indicate the visibility hints using feedbacks in -a specific way. -The -.PN XIMVisibleToForward , -.PN XIMVisibleToBackward , -and -.PN XIMVisibleCenter -masks are exclusively used for these visibility hints. -The -.PN XIMVisibleToForward -mask -indicates that the preedit text is preferably displayed in the -primary draw direction from the -caret position in the preedit area forward. -The -.PN XIMVisibleToBackward -mask -indicates that the preedit text is preferably displayed from -the caret position in the preedit area backward, relative to the primary -draw direction. -The -.PN XIMVisibleCenter -mask -indicates that the preedit text is preferably displayed with -the caret position in the preedit area centered. -.LP -The insertion point of the preedit string could exist outside of -the visible area when visibility hints are used. -Only one of the -masks -is valid for the entire preedit string, and only one character -can hold one of these feedbacks for a given input context at one time. -This feedback may be OR'ed together with another highlight (such as -.PN XIMReverse ). -Only the most recently set feedback is valid, and any previous -feedback is automatically canceled. This is a hint to the client, and -the client is free to choose how to display the preedit string. -.LP -The feedback member also specifies how rendering of the text argument -should be performed. -If the feedback is NULL, -the callback should apply the same feedback as is used for the surrounding -characters in the preedit buffer; if chg_first is at a highlight boundary, -the client can choose which of the two highlights to use. -If feedback is not NULL, feedback specifies an array defining the -rendering for each -character of the string, and the length of the array is thus length. -.LP -If an input method wants to indicate that it is only updating the feedback of -the preedit text without changing the content of it, -the -.PN XIMText -structure will contain a NULL value for the string field, -the number of characters affected (relative to chg_first) -will be in the length field, -and the feedback field will point to an array of -.PN XIMFeedback . -.LP -Each element in the feedback array is a bitmask represented by a value of type -.PN XIMFeedback . -The valid mask names are as follows: -.LP -.IN "XIMReverse" "" "@DEF@" -.IN "XIMUnderline" "" "@DEF@" -.IN "XIMHighlight" "" "@DEF@" -.IN "XIMPrimary" "" "@DEF@" -.IN "XIMSecondary" "" "@DEF@" -.IN "XIMTertiary" "" "@DEF@" -.IN "XIMVisibleToForward" "" "@DEF@" -.IN "XIMVisibleToBackward" "" "@DEF@" -.IN "XIMVisibleCenter" "" "@DEF@" -.sM -.LP -.Ds 0 -typedef unsigned long XIMFeedback; -.De -.TS -lw(.5i) lw(2i) lw(2i). -T{ -#define -T} T{ -.PN XIMReverse -T} T{ -1L -T} -T{ -#define -T} T{ -.PN XIMUnderline -T} T{ -(1L<<1) -T} -T{ -#define -T} T{ -.PN XIMHighlight -T} T{ -(1L<<2) -T} -T{ -#define -T} T{ -.PN XIMPrimary -T} T{ -(1L<<5)\(dg -T} -T{ -#define -T} T{ -.PN XIMSecondary -T} T{ -(1L<<6)\(dg -T} -T{ -#define -T} T{ -.PN XIMTertiary -T} T{ -(1L<<7)\(dg -T} -T{ -#define -T} T{ -.PN XIMVisibleToForward -T} T{ -(1L<<8) -T} -T{ -#define -T} T{ -.PN XIMVisibleToBackward -T} T{ -(1L<<9) -T} -T{ -#define -T} T{ -.PN XIMVisibleCenter -T} T{ -(1L<<10) -T} -.TE -.LP -.eM -.LP -Characters drawn with the -.PN XIMReverse -highlight should be drawn by swapping the foreground and background colors -used to draw normal, unhighlighted characters. -Characters drawn with the -.PN XIMUnderline -highlight should be underlined. -Characters drawn with the -.PN XIMHighlight , -.PN XIMPrimary , -.PN XIMSecondary , -and -.PN XIMTertiary -highlights should be drawn in some unique manner that must be different -from -.PN XIMReverse -and -.PN XIMUnderline . -.FS \(dg -The values for -.PN XIMPrimary , -.PN XIMSecondary , -and -.PN XIMTertiary -were incorrectly defined in the R5 specification. -The X Consortium's X11R5 -implementation correctly implemented the values for these highlights. -The value of these highlights has been corrected in this specification -to agree with the values in the Consortium's X11R5 and X11R6 implementations. -.FE -.NH 4 -Preedit Caret Callback -.XS -\*(SN Preedit Caret Callback -.XE -.LP -An input method may have its own navigation keys to allow the user -to move the text insertion point in the preedit area -(for example, to move backward or forward). -Consequently, input method needs to indicate to the client that it -should move the text insertion point. -It then calls the PreeditCaretCallback. -.IN "PreeditCaretCallback" "" "@DEF@" -.sM -.FD 0 -void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Specifies the preedit caret information. -.LP -.eM -The input method will trigger PreeditCaretCallback -to move the text insertion point during preedit. -The call_data argument contains a pointer to an -.PN XIMPreeditCaretCallbackStruct -structure, -which indicates where the caret should be moved. -The callback must move the insertion point to its new location -and return, in field position, the new offset value from the initial position. -.LP -The -.PN XIMPreeditCaretCallbackStruct -structure is defined as follows: -.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@" -.LP -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XIMPreeditCaretCallbackStruct { - int position; /* Caret offset within preedit string */ - XIMCaretDirection direction; /* Caret moves direction */ - XIMCaretStyle style; /* Feedback of the caret */ -} XIMPreeditCaretCallbackStruct; -.De -.LP -.eM -The -.PN XIMCaretStyle -structure is defined as follows: -.LP -.IN "XIMCaretStyle" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef enum { - XIMIsInvisible, /* Disable caret feedback */ - XIMIsPrimary, /* UI defined caret feedback */ - XIMIsSecondary, /* UI defined caret feedback */ -} XIMCaretStyle; -.De -.LP -.eM -The -.PN XIMCaretDirection -structure is defined as follows: -.IN "XIMCaretDirection" "" "@DEF@" -.LP -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef enum { - XIMForwardChar, XIMBackwardChar, - XIMForwardWord, XIMBackwardWord, - XIMCaretUp, XIMCaretDown, - XIMNextLine, XIMPreviousLine, - XIMLineStart, XIMLineEnd, - XIMAbsolutePosition, - XIMDontChange, - } XIMCaretDirection; -.De -.LP -.eM -These values are defined as follows: -.IN "XIMForwardChar" "" "@DEF@" -.IN "XIMBackwardChar" "" "@DEF@" -.IN "XIMForwardWord" "" "@DEF@" -.IN "XIMBackwardWord" "" "@DEF@" -.IN "XIMCaretUp" "" "@DEF@" -.IN "XIMCaretDown" "" "@DEF@" -.TS -lw(1.5i) lw(4.25i). -T{ -.PN XIMForwardChar -T} T{ -Move the caret forward one character position. -T} -T{ -.PN XIMBackwardChar -T} T{ -Move the caret backward one character position. -T} -T{ -.PN XIMForwardWord -T} T{ -Move the caret forward one word. -T} -T{ -.PN XIMBackwardWord -T} T{ -Move the caret backward one word. -T} -T{ -.PN XIMCaretUp -T} T{ -Move the caret up one line keeping the current horizontal offset. -T} -T{ -.PN XIMCaretDown -T} T{ -Move the caret down one line keeping the current horizontal offset. -T} -T{ -.PN XIMPreviousLine -T} T{ -Move the caret to the beginning of the previous line. -T} -T{ -.PN XIMNextLine -T} T{ -Move the caret to the beginning of the next line. -T} -T{ -.PN XIMLineStart -T} T{ -Move the caret to the beginning of the current display line -that contains the caret. -T} -T{ -.PN XIMLineEnd -T} T{ -Move the caret to the end of the current display line -that contains the caret. -T} -T{ -.PN XIMAbsolutePosition -T} T{ -The callback must move to the location specified by the position field -of the callback data, indicated in characters, starting from the beginning -of the preedit text. -Hence, a value of zero means move back to the beginning of the preedit text. -T} -T{ -.PN XIMDontChange -T} T{ -The caret position does not change. -T} -.TE -.IN "XIMNextLine" "" "@DEF@" -.IN "XIMPreviousLine" "" "@DEF@" -.IN "XIMLineStart" "" "@DEF@" -.IN "XIMLineEnd" "" "@DEF@" -.IN "XIMAbsolutePosition" "" "@DEF@" -.IN "XIMDontChange" "" "@DEF@" -.NH 4 -Status Callbacks -.XS -\*(SN Status Callbacks -.XE -.LP -An input method may communicate changes in the status of an input context -(for example, created, destroyed, or focus changes) with three status -callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback. -.LP -.sp -When the input context is created or gains focus, -the input method calls the StatusStartCallback callback. -.IN "StatusStartCallback" "" "@DEF@" -.sM -.FD 0 -void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -The callback should initialize appropriate data for displaying status -and for responding to StatusDrawCallback calls. -Once StatusStartCallback is called, -it will not be called again before StatusDoneCallback has been called. -.LP -.sp -When an input context -is destroyed or when it loses focus, the input method calls StatusDoneCallback. -.IN "StatusDoneCallback" "" "@DEF@" -.sM -.FD 0 -void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XPointer \fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Not used for this callback and always passed as NULL. -.LP -.eM -The callback may release any data allocated on -.PN StatusStart . -.LP -.sp -When an input context status has to be updated, the input method calls -StatusDrawCallback. -.IN "StatusDrawCallback" "" "@DEF@" -.sM -.FD 0 -void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) -.br - XIC \fIic\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - XIMStatusDrawCallbackStruct *\fIcall_data\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.IP \fIcall_data\fP 1i -Specifies the status drawing information. -.LP -.eM -The callback should update the status area by either drawing a string -or imaging a bitmap in the status area. -.LP -The -.PN XIMStatusDataType -and -.PN XIMStatusDrawCallbackStruct -structures are defined as follows: -.IN "XIMStatusDataType" "" "@DEF@" -.IN "XIMStatusDrawCallbackStruct" "" "@DEF@" -.LP -.sM -.Ds 0 -.TA .5i 1i 3i -.ta .5i 1i 3i -typedef enum { - XIMTextType, - XIMBitmapType, -} XIMStatusDataType; - -typedef struct _XIMStatusDrawCallbackStruct { - XIMStatusDataType type; - union { - XIMText *text; - Pixmap bitmap; - } data; -} XIMStatusDrawCallbackStruct; -.De -.LP -.eM -.LP -The feedback styles -.PN XIMVisibleToForward , -.PN XIMVisibleToBackward , -and -.PN XIMVisibleToCenter -are not relevant and will not appear in the -.PN XIMFeedback -element of the -.PN XIMText -structure. -.LP -.NH 3 -Event Filtering -.XS -\*(SN Event Filtering -.XE -.LP -Xlib provides the ability for an input method -to register a filter internal to Xlib. -This filter is called by a client (or toolkit) by calling -.PN XFilterEvent -after calling -.PN XNextEvent . -Any client that uses the -.PN XIM -interface should call -.PN XFilterEvent -to allow input methods to process their events without knowledge -of the client's dispatching mechanism. -A client's user interface policy may determine the priority -of event filters with respect to other event-handling mechanisms -(for example, modal grabs). -.LP -Clients may not know how many filters there are, if any, -and what they do. -They may only know if an event has been filtered on return of -.PN XFilterEvent . -Clients should discard filtered events. -.sp -.LP -To filter an event, use -.PN XFilterEvent . -.IN "XFilterEvent" "" "@DEF@" -.sM -.FD 0 -Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^) -.br - XEvent *\fIevent\fP\^; -.br - Window \fIw\fP\^; -.FN -.ds Ev event to filter -.IP \fIevent\fP 1i -Specifies the \*(Ev. -.ds Wi for which the filter is to be applied -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.LP -.eM -If the window argument is -.PN None , -.PN XFilterEvent -applies the filter to the window specified in the -.PN XEvent -structure. -The window argument is provided so that layers above Xlib -that do event redirection can indicate to which window an event -has been redirected. -.LP -If -.PN XFilterEvent -returns -.PN True , -then some input method has filtered the event, -and the client should discard the event. -If -.PN XFilterEvent -returns -.PN False , -then the client should continue processing the event. -.LP -If a grab has occurred in the client and -.PN XFilterEvent -returns -.PN True , -the client should ungrab the keyboard. -.NH 3 -Getting Keyboard Input -.XS -\*(SN Getting Keyboard Input -.XE -.LP -To get composed input from an input method, -use -.PN XmbLookupString -or -.PN XwcLookupString . -.IN "XmbLookupString" "" "@DEF@" -.IN "XwcLookupString" "" "@DEF@" -.sM -.FD 0 -int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) -.br - XIC \fIic\fP\^; -.br - XKeyPressedEvent *\fIevent\fP; -.br - char *\fIbuffer_return\fP\^; -.br - int \fIbytes_buffer\fP\^; -.br - KeySym *\fIkeysym_return\fP\^; -.br - Status *\fIstatus_return\fP\^; -.FN -.FD 0 -int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) -.br - XIC \fIic\fP\^; -.br - XKeyPressedEvent *\fIevent\fP\^; -.br - wchar_t *\fIbuffer_return\fP\^; -.br - int \fIwchars_buffer\fP\^; -.br - KeySym *\fIkeysym_return\fP\^; -.br - Status *\fIstatus_return\fP\^; -.FN -.IP \fIic\fP 1i -Specifies the input context. -.ds Ev key event to be used -.IP \fIevent\fP 1i -Specifies the \*(Ev. -.IP \fIbuffer_return\fP 1i -Returns a multibyte string or wide character string (if any) -from the input method. -.IP \fIbytes_buffer\fP 1i -.br -.ns -.IP \fIwchars_buffer\fP 1i -Specifies space available in the return buffer. -.IP \fIkeysym_return\fP 1i -Returns the KeySym computed from the event if this argument is not NULL. -.IP \fIstatus_return\fP 1i -Returns a value indicating what kind of data is returned. -.LP -.eM -The -.PN XmbLookupString -and -.PN XwcLookupString -functions return the string from the input method specified -in the buffer_return argument. -If no string is returned, -the buffer_return argument is unchanged. -.LP -The KeySym into which the KeyCode from the event was mapped is returned -in the keysym_return argument if it is non-NULL and the status_return -argument indicates that a KeySym was returned. -If both a string and a KeySym are returned, -the KeySym value does not necessarily correspond to the string returned. -.LP -.PN XmbLookupString -returns the length of the string in bytes, and -.PN XwcLookupString -returns the length of the string in characters. -Both -.PN XmbLookupString -and -.PN XwcLookupString -return text in the encoding of the locale bound to the input method -of the specified input context. -.LP -Each string returned by -.PN XmbLookupString -and -.PN XwcLookupString -begins in the initial state of the encoding of the locale -(if the encoding of the locale is state-dependent). -.NT -To insure proper input processing, -it is essential that the client pass only -.PN KeyPress -events to -.PN XmbLookupString -and -.PN XwcLookupString . -Their behavior when a client passes a -.PN KeyRelease -event is undefined. -.NE -.LP -Clients should check the status_return argument before -using the other returned values. -These two functions both return a value to status_return -that indicates what has been returned in the other arguments. -The possible values returned are: -.TS -lw(1.5i) lw(4.3i). -T{ -.PN XBufferOverflow -T} T{ -The input string to be returned is too large for the supplied buffer_return. -The required size -.Pn ( XmbLookupString -in bytes; -.PN XwcLookupString -in characters) is returned as the value of the function, -and the contents of buffer_return and keysym_return are not modified. -The client should recall the function with the same event -and a buffer of adequate size to obtain the string. -T} -T{ -.PN XLookupNone -T} T{ -No consistent input has been composed so far. -The contents of buffer_return and keysym_return are not modified, -and the function returns zero. -T} -T{ -.PN XLookupChars -T} T{ -Some input characters have been composed. -They are placed in the buffer_return argument, -and the string length is returned as the value of the function. -The string is encoded in the locale bound to the input context. -The content of the keysym_return argument is not modified. -T} -T{ -.PN XLookupKeySym -T} T{ -A KeySym has been returned instead of a string -and is returned in keysym_return. -The content of the buffer_return argument is not modified, -and the function returns zero. -T} -T{ -.PN XLookupBoth -T} T{ -Both a KeySym and a string are returned; -.PN XLookupChars -and -.PN XLookupKeySym -occur simultaneously. -T} -.TE -.LP -It does not make any difference if the input context passed as an argument to -.PN XmbLookupString -and -.PN XwcLookupString -is the one currently in possession of the focus or not. -Input may have been composed within an input context before it lost the focus, -and that input may be returned on subsequent calls to -.PN XmbLookupString -or -.PN XwcLookupString -even though it does not have any more keyboard focus. -.NH 3 -Input Method Conventions -.XS -\*(SN Input Method Conventions -.XE -.LP -The input method architecture is transparent to the client. -However, clients should respect a number of conventions in order -to work properly. -Clients must also be aware of possible effects of synchronization -between input method and library in the case of a remote input server. -.NH 4 -Client Conventions -.XS -\*(SN Client Conventions -.XE -.LP -A well-behaved client (or toolkit) should first query the input method style. -If the client cannot satisfy the requirements of the supported styles -(in terms of geometry management or callbacks), -it should negotiate with the user continuation of the program -or raise an exception or error of some sort. -.NH 4 -Synchronization Conventions -.XS -\*(SN Synchronization Conventions -.XE -.LP -A -.PN KeyPress -event with a KeyCode of zero is used exclusively as a -signal that an input method has composed input that can be returned by -.PN XmbLookupString -or -.PN XwcLookupString . -No other use is made of a -.PN KeyPress -event with KeyCode of zero. -.LP -Such an event may be generated by either a front-end -or a back-end input method in an implementation-dependent manner. -Some possible ways to generate this event include: -.IP \(bu 5 -A synthetic event sent by an input method server -.IP \(bu 5 -An artificial event created by a input method filter and pushed -onto a client's event queue -.IP \(bu 5 -A -.PN KeyPress -event whose KeyCode value is modified by an input method filter -.LP -When callback support is specified by the client, -input methods will not take action unless they explicitly -called back the client and obtained no response -(the callback is not specified or returned invalid data). -.NH 2 -String Constants -.XS -\*(SN String Constants -.XE -.LP -The following symbols for string constants are defined in -.hN X11/Xlib.h . -Although they are shown here with particular macro definitions, -they may be implemented as macros, as global symbols, or as a -mixture of the two. The string pointer value itself -is not significant; clients must not assume that inequality of two -values implies inequality of the actual string data. -.IN "XNVaNestedList" "" "@DEF@" -.IN "XNSeparatorofNestedList "" "@DEF@" -.IN "XNQueryInputStyle" "" "@DEF@" -.IN "XNClientWindow" "" "@DEF@" -.IN "XNInputStyle" "" "@DEF@" -.IN "XNFocusWindow" "" "@DEF@" -.IN "XNResourceName" "" "@DEF@" -.IN "XNResourceClass" "" "@DEF@" -.IN "XNGeometryCallback" "" "@DEF@" -.IN "XNDestroyCallback" "" "@DEF@" -.IN "XNFilterEvents" "" "@DEF@" -.IN "XNPreeditStartCallback" "" "@DEF@" -.IN "XNPreeditDoneCallback" "" "@DEF@" -.IN "XNPreeditDrawCallback" "" "@DEF@" -.IN "XNPreeditCaretCallback" "" "@DEF@" -.IN "XNPreeditStateNotifyCallback" "" "@DEF@" -.IN "XNPreeditAttributes" "" "@DEF@" -.IN "XNStatusStartCallback" "" "@DEF@" -.IN "XNStatusDoneCallback" "" "@DEF@" -.IN "XNStatusDrawCallback" "" "@DEF@" -.IN "XNStatusAttributes" "" "@DEF@" -.IN "XNArea" "" "@DEF@" -.IN "XNAreaNeeded" "" "@DEF@" -.IN "XNSpotLocation" "" "@DEF@" -.IN "XNColormap" "" "@DEF@" -.IN "XNStdColormap" "" "@DEF@" -.IN "XNForeground" "" "@DEF@" -.IN "XNBackground" "" "@DEF@" -.IN "XNBackgroundPixmap" "" "@DEF@" -.IN "XNFontSet" "" "@DEF@" -.IN "XNLineSpace" "" "@DEF@" -.IN "XNCursor" "" "@DEF@" -.TS -lw(.5i) lw(2.75i) lw(2.5i). -T{ -#define -T} T{ -.PN XNVaNestedList -T} T{ -"XNVaNestedList" -T} -T{ -#define -T} T{ -.PN XNSeparatorofNestedList -T} T{ -"separatorofNestedList" -T} -T{ -#define -T} T{ -.PN XNQueryInputStyle -T} T{ -"queryInputStyle" -T} -T{ -#define -T} T{ -.PN XNClientWindow -T} T{ -"clientWindow" -T} -T{ -#define -T} T{ -.PN XNInputStyle -T} T{ -"inputStyle" -T} -T{ -#define -T} T{ -.PN XNFocusWindow -T} T{ -"focusWindow" -T} -T{ -#define -T} T{ -.PN XNResourceName -T} T{ -"resourceName" -T} -T{ -#define -T} T{ -.PN XNResourceClass -T} T{ -"resourceClass" -T} -T{ -#define -T} T{ -.PN XNGeometryCallback -T} T{ -"geometryCallback" -T} -T{ -#define -T} T{ -.PN XNDestroyCallback -T} T{ -"destroyCallback" -T} -T{ -#define -T} T{ -.PN XNFilterEvents -T} T{ -"filterEvents" -T} -T{ -#define -T} T{ -.PN XNPreeditStartCallback -T} T{ -"preeditStartCallback" -T} -T{ -#define -T} T{ -.PN XNPreeditDoneCallback -T} T{ -"preeditDoneCallback" -T} -T{ -#define -T} T{ -.PN XNPreeditDrawCallback -T} T{ -"preeditDrawCallback" -T} -T{ -#define -T} T{ -.PN XNPreeditCaretCallback -T} T{ -"preeditCaretCallback" -T} -T{ -#define -T} T{ -.PN XNPreeditStateNotifyCallback -T} T{ -"preeditStateNotifyCallback" -T} -T{ -#define -T} T{ -.PN XNPreeditAttributes -T} T{ -"preeditAttributes" -T} -.TE -.sp -1 -.TS -lw(.5i) lw(2.75i) lw(2.5i). -T{ -#define -T} T{ -.PN XNStatusStartCallback -T} T{ -"statusStartCallback" -T} -T{ -#define -T} T{ -.PN XNStatusDoneCallback -T} T{ -"statusDoneCallback" -T} -T{ -#define -T} T{ -.PN XNStatusDrawCallback -T} T{ -"statusDrawCallback" -T} -T{ -#define -T} T{ -.PN XNStatusAttributes -T} T{ -"statusAttributes" -T} -T{ -#define -T} T{ -.PN XNArea -T} T{ -"area" -T} -T{ -#define -T} T{ -.PN XNAreaNeeded -T} T{ -"areaNeeded" -T} -T{ -#define -T} T{ -.PN XNSpotLocation -T} T{ -"spotLocation" -T} -T{ -#define -T} T{ -.PN XNColormap -T} T{ -"colorMap" -T} -T{ -#define -T} T{ -.PN XNStdColormap -T} T{ -"stdColorMap" -T} -T{ -#define -T} T{ -.PN XNForeground -T} T{ -"foreground" -T} -T{ -#define -T} T{ -.PN XNBackground -T} T{ -"background" -T} -T{ -#define -T} T{ -.PN XNBackgroundPixmap -T} T{ -"backgroundPixmap" -T} -T{ -#define -T} T{ -.PN XNFontSet -T} T{ -"fontSet" -T} -T{ -#define -T} T{ -.PN XNLineSpace -T} T{ -"lineSpace" -T} -T{ -#define -T} T{ -.PN XNCursor -T} T{ -"cursor" -T} -.TE -.sp -1 -.TS -lw(.5i) lw(2.75i) lw(2.5i). -T{ -#define -T} T{ -.PN XNQueryIMValuesList -T} T{ -"queryIMValuesList" -T} -T{ -#define -T} T{ -.PN XNQueryICValuesList -T} T{ -"queryICValuesList" -T} -T{ -#define -T} T{ -.PN XNStringConversionCallback -T} T{ -"stringConversionCallback" -T} -T{ -#define -T} T{ -.PN XNStringConversion -T} T{ -"stringConversion" -T} -T{ -#define -T} T{ -.PN XNResetState -T} T{ -"resetState" -T} -T{ -#define -T} T{ -.PN XNHotKey -T} T{ -"hotkey" -T} -T{ -#define -T} T{ -.PN XNHotKeyState -T} T{ -"hotkeyState" -T} -T{ -#define -T} T{ -.PN XNPreeditState -T} T{ -"preeditState" -T} -T{ -#define -T} T{ -.PN XNVisiblePosition -T} T{ -"visiblePosition" -T} -T{ -#define -T} T{ -.PN XNR6PreeditCallbackBehavior -T} T{ -"r6PreeditCallback" -T} -.TE -.sp -1 -.IN "XNQueryIMValuesList" "" "@DEF@" -.IN "XNQueryICValuesList" "" "@DEF@" -.IN "XNStringConversionCallback" "" "@DEF@" -.IN "XNStringConversion" "" "@DEF@" -.IN "XNResetState" "" "@DEF@" -.IN "XNHotKey" "" "@DEF@" -.IN "XNHotKeyState" "" "@DEF@" -.IN "XNPreeditState" "" "@DEF@" -.IN "XNVisiblePosition" "" "@DEF@" -.IN "XNR6PreeditCallbackBehavior" "" "@DEF@" -.TS -lw(.5i) lw(2.75i) lw(2.5i). -T{ -#define -T} T{ -.PN XNRequiredCharSet -T} T{ -"requiredCharSet" -T} -T{ -#define -T} T{ -.PN XNQueryOrientation -T} T{ -"queryOrientation" -T} -T{ -#define -T} T{ -.PN XNDirectionalDependentDrawing -T} T{ -"directionalDependentDrawing" -T} -T{ -#define -T} T{ -.PN XNContextualDrawing -T} T{ -"contextualDrawing" -T} -T{ -#define -T} T{ -.PN XNBaseFontName -T} T{ -"baseFontName" -T} -T{ -#define -T} T{ -.PN XNMissingCharSet -T} T{ -"missingCharSet" -T} -T{ -#define -T} T{ -.PN XNDefaultString -T} T{ -"defaultString" -T} -T{ -#define -T} T{ -.PN XNOrientation -T} T{ -"orientation" -T} -T{ -#define -T} T{ -.PN XNFontInfo -T} T{ -"fontInfo" -T} -T{ -#define -T} T{ -.PN XNOMAutomatic -T} T{ -"omAutomatic" -T} -.TE -.IN "XNRequiredCharSet" "" "@DEF@" -.IN "XNQueryOrientation" "" "@DEF@" -.IN "XNDirectionalDependentDrawing" "" "@DEF@" -.IN "XNContextualDrawing" "" "@DEF@" -.IN "XNBaseFontName" "" "@DEF@" -.IN "XNMissingCharSet" "" "@DEF@" -.IN "XNDefaultString" "" "@DEF@" -.IN "XNOrientation" "" "@DEF@" -.IN "XNFontInfo" "" "@DEF@" -.IN "XNOMAutomatic" "" "@DEF@" -.bp diff --git a/libX11/specs/libX11/CH13.xml b/libX11/specs/libX11/CH13.xml new file mode 100644 index 000000000..06564c3da --- /dev/null +++ b/libX11/specs/libX11/CH13.xml @@ -0,0 +1,10350 @@ +<chapter id="locales_and_internationalized_text_functions">
+<title>Locales and Internationalized Text Functions</title>
+
+<para>
+An internationalized application is one that is adaptable to the requirements of different native
+languages, local customs, and character string encodings. The process of adapting the operation
+to a particular native language, local custom, or string encoding is called localization. A goal of
+internationalization is to permit localization without program source modifications or recompila-
+tion.
+</para>
+<para>
+As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>) functional inter-
+face for internationalized text input and an X Output Method (<acronym>XOM</acronym>) functional interface for
+internationalized text output.
+</para>
+<para>
+Internationalization in X is based on the concept of a locale. A locale defines the localized
+behavior of a program at run time. Locales affect Xlib in its:
+</para>
+
+<itemizedlist>
+ <listitem><para>Encoding and processing of input method text</para></listitem>
+ <listitem><para>Encoding of resource files and values</para></listitem>
+ <listitem><para>Encoding and imaging of text strings</para></listitem>
+ <listitem><para>Encoding and decoding for inter-client text communication</para></listitem>
+</itemizedlist>
+
+
+<para>
+•
+Encoding and decoding for inter-client text communication
+Characters from various languages are represented in a computer using an encoding. Different
+languages have different encodings, and there are even different encodings for the same charac-
+ters in the same language.
+</para>
+<para>
+This chapter defines support for localized text imaging and text input and describes the locale
+mechanism that controls all locale-dependent Xlib functions. Sets of functions are provided for
+multibyte (char *) text as well as wide character (wchar_t) text in the form supported by the host
+C language environment. The multibyte and wide character functions are equivalent except for
+the form of the text argument.
+</para>
+<para>
+The Xlib internationalization functions are not meant to provide support for multilingual applica-
+tions (mixing multiple languages within a single piece of text), but they make it possible to imple-
+ment applications that work in limited fashion with more than one language in independent con-
+texts.
+</para>
+<para>
+The remainder of this chapter discusses:
+</para>
+
+<itemizedlist>
+ <listitem><para>X locale management</para></listitem>
+ <listitem><para>Locale and modifier dependencies</para></listitem>
+ <listitem><para>Variable argument lists</para></listitem>
+ <listitem><para>Output methods</para></listitem>
+ <listitem><para>Input methods</para></listitem>
+ <listitem><para>String constants</para></listitem>
+</itemizedlist>
+
+
+<sect1 id="X_Locale_Management">
+<title>X Locale Management</title>
+<!-- .XS -->
+<!-- (SN X Locale Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+X supports one or more of the locales defined by the host environment.
+On implementations that conform to the ANSI C library,
+the locale announcement method is
+<function>setlocale</function>.
+This function configures the locale operation of both
+the host C library and Xlib.
+The operation of Xlib is governed by the LC_CTYPE category;
+this is called the <emphasis remap='I'>current locale</emphasis>.
+An implementation is permitted to provide implementation-dependent
+mechanisms for announcing the locale in addition to
+<function>setlocale</function>.
+</para>
+<para>
+<!-- .LP -->
+On implementations that do not conform to the ANSI C library,
+the locale announcement method is Xlib implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The mechanism by which the semantic operation of Xlib is defined
+for a specific locale is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+X is not required to support all the locales supported by the host.
+To determine if the current locale is supported by X, use
+<function>XSupportsLocale</function>.
+</para>
+
+<para>Bool XSupportsLocale()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSupportsLocale</function>
+function returns
+<function>True</function>
+if Xlib functions are capable of operating under the current locale.
+If it returns
+<function>False</function>,
+Xlib locale-dependent functions for which the
+<function>XLocaleNotSupported </function>
+return status is defined will return
+<function>XLocaleNotSupported</function>.
+Other Xlib locale-dependent routines will operate in the ``C'' locale.
+</para>
+<para>
+<!-- .LP -->
+The client is responsible for selecting its locale and X modifiers.
+Clients should provide a means for the user to override the clients'
+locale selection at client invocation.
+Most single-display X clients operate in a single locale
+for both X and the host processing environment.
+They will configure the locale by calling three functions:
+the host locale configuration function,
+<function>XSupportsLocale</function>,
+and
+<function>XSetLocaleModifiers</function>.
+</para>
+<para>
+<!-- .LP -->
+The semantics of certain categories of X internationalization capabilities
+can be configured by setting modifiers.
+Modifiers are named by implementation-dependent and locale-specific strings.
+The only standard use for this capability at present
+is selecting one of several styles of keyboard input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To configure Xlib locale modifiers for the current locale, use
+<function>XSetLocaleModifiers</function>.
+<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XSetLocaleModifiers</function></funcdef>
+ <paramdef>char<parameter> *modifier_list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifier_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifiers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetLocaleModifiers</function>
+function sets the X modifiers for the current locale setting.
+The modifier_list argument is a null-terminated string of the form
+``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is,
+having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>''
+entries, where <emphasis remap='I'>category</emphasis> is a category name
+and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category.
+The values are encoded in the current locale.
+Category names are restricted to the <acronym>POSIX</acronym> Portable Filename Character Set.
+</para>
+<para>
+<!-- .LP -->
+The local host X locale modifiers announcer (on <acronym>POSIX</acronym>-compliant systems,
+the XMODIFIERS environment variable) is appended to the modifier_list to
+provide default values on the local host.
+If a given category appears more than once in the list,
+the first setting in the list is used.
+If a given category is not included in the full modifier list,
+the category is set to an implementation-dependent default
+for the current locale.
+An empty value for a category explicitly specifies the
+implementation-dependent default.
+</para>
+<para>
+<!-- .LP -->
+If the function is successful, it returns a pointer to a string.
+The contents of the string are such that a subsequent call with that string
+(in the same locale) will restore the modifiers to the same settings.
+If modifier_list is a NULL pointer,
+<function>XSetLocaleModifiers</function>
+also returns a pointer to such a string,
+and the current locale modifiers are not changed.
+</para>
+<para>
+<!-- .LP -->
+If invalid values are given for one or more modifier categories supported by
+the locale, a NULL pointer is returned, and none of the
+current modifiers are changed.
+</para>
+<para>
+<!-- .LP -->
+At program startup,
+the modifiers that are in effect are unspecified until
+the first successful call to set them. Whenever the locale is changed, the
+modifiers that are in effect become unspecified until the next successful call
+to set them.
+Clients should always call
+<function>XSetLocaleModifiers</function>
+with a non-NULL modifier_list after setting the locale
+before they call any locale-dependent Xlib routine.
+</para>
+<para>
+<!-- .LP -->
+The only standard modifier category currently defined is ``im'',
+which identifies the desired input method.
+The values for input method are not standardized.
+A single locale may use multiple input methods,
+switching input method under user control.
+The modifier may specify the initial input method in effect
+or an ordered list of input methods.
+Multiple input methods may be specified in a single im value string
+in an implementation-dependent manner.
+</para>
+<para>
+<!-- .LP -->
+The returned modifiers string is owned by Xlib and should not be modified or
+freed by the client.
+It may be freed by Xlib after the current locale or modifiers are changed.
+Until freed, it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+The recommended procedure for clients initializing their locale and modifiers
+is to obtain locale and modifier announcers separately from
+one of the following prioritized sources:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A command line option
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A resource
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The empty string ("")
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The first of these that is defined should be used.
+Note that when a locale command line option or locale resource is defined,
+the effect should be to set all categories to the specified locale,
+overriding any category-specific settings in the local host environment.
+</para>
+</sect1>
+<sect1 id="Locale_and_Modifier_Dependencies">
+<title>Locale and Modifier Dependencies</title>
+<!-- .XS -->
+<!-- (SN Locale and Modifier Dependencies -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The internationalized Xlib functions operate in the current locale
+configured by the host environment and X locale modifiers set by
+<function>XSetLocaleModifiers</function>
+or in the locale and modifiers configured at the time
+some object supplied to the function was created.
+For each locale-dependent function,
+the following table describes the locale (and modifiers) dependency:
+</para>
+
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Locale from</entry>
+ <entry>Affects the Function</entry>
+ <entry>In</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry></entry>
+ <entry>Locale Query/Configuration:</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XSupportsLocale</function></entry>
+ <entry>Locale queried</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XSetLocaleModifiers</function></entry>
+ <entry>Locale modified</entry>
+ </row>
+ <row>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Resources:</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XrmGetFileDatabase</function></entry>
+ <entry>Locale of <function>XrmDatabase</function></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XrmGetStringDatabase</function></entry>
+ </row>
+ <row>
+ <entry><function>XrmDatabase</function></entry>
+ <entry><function>XrmPutFileDatabase</function></entry>
+ <entry>Locale of <function>XrmDatabase</function></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XrmLocaleOfDatabase</function></entry>
+ </row>
+ <row>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Setting Standard Properties:</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XmbSetWMProperties</function></entry>
+ <entry>Encoding of supplied/returned
+ text (some WM_ property
+ text in environment locale)</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XmbTextPropertyToTextList</function></entry>
+ <entry>Encoding of supplied/returned text</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XwcTextPropertyToTextList</function></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XmbTextListToTextProperty</function></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XwcTextListToTextProperty</function></entry>
+ </row>
+ <row>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Text Input:</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XOpenIM</function></entry>
+ <entry><acronym>XIM</acronym> input method selection</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XRegisterIMInstantiateCallback</function></entry>
+ <entry><acronym>XIM</acronym> selection</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XUnregisterIMInstantiateCallback</function></entry>
+ <entry><acronym>XIM</acronym> selection</entry>
+ </row>
+ <row>
+ <entry><function>XIM</function></entry>
+ <entry><function>XCreateIC</function></entry>
+ <entry><acronym>XIC</acronym> input method configuration</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XLocaleOfIM</function>, and so on</entry>
+ <entry>Queried locale</entry>
+ </row>
+ <row>
+ <entry><function>XIC</function></entry>
+ <entry><function>XmbLookupString</function></entry>
+ <entry>Keyboard layout</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XwcLookupString</function></entry>
+ <entry>Encoding of returned text</entry>
+ </row>
+ <row>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Text Drawing:</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XOpenOM</function></entry>
+ <entry><acronym>XOM</acronym> output method selection</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XCreateFontSet</function></entry>
+ <entry>Charsets of fonts in XFontSet</entry>
+ </row>
+ <row>
+ <entry><function>XOM</function></entry>
+ <entry><function>XCreateOC</function></entry>
+ <entry><acronym>XOC</acronym> output method configuration</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XLocaleOfOM</function>, and so on</entry>
+ <entry>Queried locale</entry>
+ </row>
+ <row>
+ <entry><function>XFontSet</function></entry>
+ <entry><function>XmbDrawText</function>,</entry>
+ <entry>Locale of supplied text</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XwcDrawText</function>, and so on</entry>
+ <entry>Locale of supplied text</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XExtentsOfFontSet</function>, and so on</entry>
+ <entry>Locale-dependent metrics</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XmbTextExtents</function>,</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XwcTextExtents</function>, and so on</entry>
+ </row>
+ <row>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Xlib Errors:</entry>
+ </row>
+ <row>
+ <entry><function>setlocale</function></entry>
+ <entry><function>XGetErrorDatabaseText</function></entry>
+ <entry>Locale of error message</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><function>XGetErrorText</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Clients may assume that a locale-encoded text string returned
+by an X function can be passed to a C library routine, or vice versa,
+if the locale is the same at the two calls.
+</para>
+<para>
+<!-- .LP -->
+All text strings processed by internationalized Xlib functions are assumed
+to begin in the initial state of the encoding of the locale, if the encoding
+is state-dependent.
+</para>
+<para>
+<!-- .LP -->
+All Xlib functions behave as if they do not change the current locale
+or X modifier setting.
+(This means that if they do change locale or call
+<function>XSetLocaleModifiers</function>
+with a non-NULL argument, they must save and restore the current state on
+entry and exit.)
+Also, Xlib functions on implementations that conform to the ANSI C library do
+not alter the global state associated with the ANSI C functions
+<function>mblen</function>,
+<function>mbtowc</function>,
+<function>wctomb</function>,
+and
+<function>strtok</function>.
+</para>
+</sect1>
+<sect1 id="Variable_Argument_Lists">
+<title>Variable Argument Lists</title>
+<!-- .XS -->
+<!-- (SN Variable Argument Lists -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Various functions in this chapter have arguments that conform
+to the ANSI C variable argument list calling convention.
+Each function denoted with an argument of the form ``...'' takes
+a variable-length list of name and value pairs,
+where each name is a string and each value is of type
+<function>XPointer</function>.
+A name argument that is NULL identifies the end of the list.
+</para>
+<para>
+<!-- .LP -->
+A variable-length argument list may contain a nested list.
+If the name
+<function>XNVaNestedList</function>
+is specified in place of an argument name,
+then the following value is interpreted as an
+<function>XVaNestedList</function>
+value that specifies a list of values logically inserted into the
+original list at the point of declaration.
+A NULL identifies the end of a nested list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a nested variable argument list dynamically, use
+<function>XVaCreateNestedList</function>.
+<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XVaNestedList<function> XVaCreateNestedList</function></funcdef>
+ <paramdef>int<parameter> dummy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dummy</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an unused argument (required by ANSI C).
+<!-- .ds Al -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XVaCreateNestedList</function>
+function allocates memory and copies its arguments into
+a single list pointer,
+which may be used as a value for arguments requiring a list value.
+Any entries are copied as specified.
+Data passed by reference is not copied;
+the caller must ensure data remains valid for the lifetime
+of the nested list.
+The list should be freed using
+<function>XFree</function>
+when it is no longer needed.
+</para>
+</sect1>
+<sect1 id="Output_Methods">
+<title>Output Methods</title>
+<!-- .XS -->
+<!-- (SN Output Methods -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section provides discussions of the following X Output Method
+(<acronym>XOM</acronym>) topics:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Output method overview
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Output method functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Output method values
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Output context functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Output context values
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Creating and freeing a font set
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtaining font set metrics
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Drawing text using font sets
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Output_Method_Overview">
+<title>Output Method Overview</title>
+<!-- .XS -->
+<!-- (SN Output Method Overview -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Locale-dependent text may include one or more text components, each of
+which may require different fonts and character set encodings.
+In some languages, each component might have a different
+drawing direction, and some components might contain
+context-dependent characters that change shape based on
+relationships with neighboring characters.
+</para>
+<para>
+<!-- .LP -->
+When drawing such locale-dependent text, some locale-specific
+knowledge is required;
+for example, what fonts are required to draw the text,
+how the text can be separated into components, and which
+fonts are selected to draw each component.
+Further, when bidirectional text must be drawn,
+the internal representation order of the text must be changed
+into the visual representation order to be drawn.
+</para>
+<para>
+<!-- .LP -->
+An X Output Method provides a functional interface so that clients
+do not have to deal directly with such locale-dependent details.
+Output methods provide the following capabilities:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Creating a set of fonts required to draw locale-dependent text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Drawing locale-dependent text with a font set without the caller
+needing to be aware of locale dependencies.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtaining the escapement and extents in pixels of locale-dependent text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Determining if bidirectional or context-dependent drawing is required
+in a specific locale with a specific font set.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Two different abstractions are used in the representation of
+the output method for clients.
+</para>
+<para>
+<!-- .LP -->
+The abstraction used to communicate with an output method
+is an opaque data structure represented by the
+<function>XOM</function>
+data type.
+The abstraction for representing the state of a particular output thread
+is called an <emphasis remap='I'>output context</emphasis>.
+The Xlib representation of an output context is an
+<function>XOC</function>,
+which is compatible with
+<function>XFontSet</function>
+in terms of its functional interface, but is
+a broader, more generalized abstraction.
+</para>
+</sect2>
+<sect2 id="Output_Method_Functions">
+<title>Output Method Functions</title>
+<!-- .XS -->
+<!-- (SN Output Method Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open an output method, use
+<function>XOpenOM</function>.
+<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XOM<function> XOpenOM</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+ <paramdef>char<parameter> *res_name</parameter></paramdef>
+ <paramdef>char<parameter> *res_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full resource name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XOpenOM</function>
+function opens an output method
+matching the current locale and modifiers specification.
+The current locale and modifiers are bound to the output method
+when
+<function>XOpenOM</function>
+is called.
+The locale associated with an output method cannot be changed.
+</para>
+<para>
+<!-- .LP -->
+The specific output method to which this call will be routed
+is identified on the basis of the current locale and modifiers.
+<function>XOpenOM</function>
+will identify a default output method corresponding to the
+current locale.
+That default can be modified using
+<function>XSetLocaleModifiers</function>
+to set the output method modifier.
+</para>
+<para>
+<!-- .LP -->
+The db argument is the resource database to be used by the output method
+for looking up resources that are private to the output method.
+It is not intended that this database be used to look
+up values that can be set as OC values in an output context.
+If db is NULL,
+no database is passed to the output method.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments specify the resource name
+and class of the application.
+They are intended to be used as prefixes by the output method
+when looking up resources that are common to all output contexts
+that may be created for this output method.
+The characters used for resource names and classes must be in the
+X Portable Character Set.
+The resources looked up are not fully specified
+if res_name or res_class is NULL.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments are not assumed to exist beyond
+the call to
+<function>XOpenOM</function>.
+The specified resource database is assumed to exist for the lifetime
+of the output method.
+</para>
+<para>
+<!-- .LP -->
+<function>XOpenOM</function>
+returns NULL if no output method could be opened.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To close an output method, use
+<function>XCloseOM</function>.
+<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XCloseOM</function></funcdef>
+ <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>om</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseOM</function>
+function closes the specified output method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set output method attributes, use
+<function>XSetOMValues</function>.
+<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>om</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output method.
+<!-- .ds Al \ to set <acronym>XOM</acronym> values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable-length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetOMValues</function>
+function presents a variable argument list programming interface
+for setting properties or features of the specified output method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+</para>
+<para>
+<!-- .LP -->
+No standard arguments are currently defined by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query an output method, use
+<function>XGetOMValues</function>.
+<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>om</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output method.
+<!-- .ds Al \ to get XOM values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable-length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetOMValues</function>
+function presents a variable argument list programming interface
+for querying properties or features of the specified output method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+</para>
+<para>
+<!-- .LP -->
+To obtain the display associated with an output method, use
+<function>XDisplayOfOM</function>.
+<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display<function> *</function></funcdef>
+ <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>om</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayOfOM</function>
+function returns the display associated with the specified output method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the locale associated with an output method, use
+<function>XLocaleOfOM</function>.
+<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>om</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLocaleOfOM</function>
+returns the locale associated with the specified output method.
+</para>
+</sect2>
+<sect2 id="X_Output_Method_Values">
+<title>X Output Method Values</title>
+<!-- .XS -->
+<!-- (SN X Output Method Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following table describes how <acronym>XOM</acronym> values are interpreted by an
+output method.
+The first column lists the <acronym>XOM</acronym> values. The second column indicates
+how each of the <acronym>XOM</acronym> values are treated by a particular output style.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The following key applies to this table.
+</para>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Explanation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>G</entry>
+ <entry>This value may be read using <function>XGetOMValues</function>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry><acronym>XOM</acronym> Value</entry>
+ <entry>Key</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XNRequiredCharSet</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNQueryOrientation</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNDirectionalDependentDrawing</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNContextualDrawing</function></entry>
+ <entry>G</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Required_Char_Set">
+<title>Required Char Set</title>
+<!-- .XS -->
+<!-- (SN Required Char Set -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNRequiredCharSet</function>
+argument returns the list of charsets that are required for loading the fonts
+needed for the locale.
+The value of the argument is a pointer to a structure of type
+<function>XOMCharSetList</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XOMCharSetList</function>
+structure is defined as follows:
+<indexterm significance="preferred"><primary>XOMCharSetList</primary></indexterm>
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int charset_count;
+ char **charset_list;
+} XOMCharSetList;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The charset_list member is a list of one or more null-terminated
+charset names, and the charset_count member is the number of
+charset names.
+</para>
+<para>
+<!-- .LP -->
+The required charset list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to
+<function>XCloseOM</function>
+with the associated
+<function>XOM</function>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Query_Orientation">
+<title>Query Orientation</title>
+<!-- .XS -->
+<!-- (SN Query Orientation -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNQueryOrientation</function>
+argument returns the global orientation of text when drawn.
+Other than
+<function>XOMOrientation_LTR_TTB</function>,
+the set of orientations supported is locale-dependent.
+The value of the argument is a pointer to a structure of type
+<function>XOMOrientation</function>.
+Clients are responsible for freeing the
+<function>XOMOrientation</function>
+structure by using
+<function>XFree</function>;
+this also frees the contents of the structure.
+</para>
+
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int num_orientation;
+ XOrientation *orientation; /* Input Text description */
+} XOMOrientation;
+
+typedef enum {
+ XOMOrientation_LTR_TTB,
+ XOMOrientation_RTL_TTB,
+ XOMOrientation_TTB_LTR,
+ XOMOrientation_TTB_RTL,
+ XOMOrientation_Context
+} XOrientation;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The possible value for XOrientation may be:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<function>XOMOrientation_LTR_TTB </function>
+left-to-right, top-to-bottom global orientation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XOMOrientation_RTL_TTB </function>
+right-to-left, top-to-bottom global orientation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XOMOrientation_TTB_LTR </function>
+top-to-bottom, left-to-right global orientation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XOMOrientation_TTB_RTL </function>
+top-to-bottom, right-to-left global orientation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XOMOrientation_Context </function>
+contextual global orientation
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Directional_Dependent_Drawing">
+<title>Directional Dependent Drawing</title>
+<!-- .XS -->
+<!-- (SN Directional Dependent Drawing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNDirectionalDependentDrawing</function>
+argument indicates whether the text rendering functions
+implement implicit handling of directional text. If this value
+is
+<function>True</function>,
+the output method has knowledge of directional
+dependencies and reorders text as necessary when
+rendering text. If this value is
+<function>False</function>,
+the output method does not implement any directional text
+handling, and all character directions are assumed to be left-to-right.
+</para>
+<para>
+<!-- .LP -->
+Regardless of the rendering order of characters,
+the origins of all characters are on the primary draw direction side
+of the drawing origin.
+</para>
+<para>
+<!-- .LP -->
+This OM value presents functionality identical to the
+<function>XDirectionalDependentDrawing</function>
+function.
+</para>
+</sect3>
+<sect3 id="Context_Dependent_Drawing">
+<title>Context Dependent Drawing</title>
+<!-- .XS -->
+<!-- (SN Context Dependent Drawing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNContextualDrawing</function>
+argument indicates whether the text rendering functions
+implement implicit context-dependent drawing. If this value is
+<function>True</function>,
+the output method has knowledge of context dependencies and
+performs character shape editing, combining glyphs to present
+a single character as necessary. The actual shape editing is
+dependent on the locale implementation and the font set used.
+</para>
+<para>
+<!-- .LP -->
+This OM value presents functionality identical to the
+<function>XContextualDrawing</function>
+function.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Output_Context_Functions">
+<title>Output Context Functions</title>
+<!-- .XS -->
+<!-- (SN Output Context Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An output context is an abstraction that contains both the data
+required by an output method and the information required
+to display that data.
+There can be multiple output contexts for one output method.
+The programming interfaces for creating, reading, or modifying
+an output context use a variable argument list.
+The name elements of the argument lists are referred to as <acronym>XOC</acronym> values.
+It is intended that output methods be controlled by these <acronym>XOC</acronym> values.
+As new <acronym>XOC</acronym> values are created,
+they should be registered with the X Consortium.
+An
+<function>XOC</function>
+can be used anywhere an
+<function>XFontSet</function>
+can be used, and vice versa;
+<function>XFontSet</function>
+is retained for compatibility with previous releases.
+The concepts of output methods and output contexts include broader,
+more generalized abstraction than font set,
+supporting complex and more intelligent text display, and dealing not only
+with multiple fonts but also with context dependencies.
+However,
+<function>XFontSet</function>
+is widely used in several interfaces, so
+<function>XOC</function>
+is defined as an upward compatible type of
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an output context, use
+<function>XCreateOC</function>.
+<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XOC<function> XCreateOC</function></funcdef>
+ <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>om</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output method.
+<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable-length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateOC </function>
+function creates an output context within the specified output method.
+</para>
+<para>
+<!-- .LP -->
+The base font names argument is mandatory at creation time, and
+the output context will not be created unless it is provided.
+All other output context values can be set later.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateOC</function>
+returns NULL if no output context could be created.
+NULL can be returned for any of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A required argument was not set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A read-only argument was set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An argument name is not recognized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The output method encountered an output method implementation-dependent error.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XCreateOC</function>
+can generate a
+<function>BadAtom</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an output context, use
+<function>XDestroyOC</function>.
+<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XDestroyOC</function></funcdef>
+ <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>oc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroyOC</function>
+function destroys the specified output context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the output method associated with an output context, use
+<function>XOMOfOC</function>.
+<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XOM<function> XOMOfOC</function></funcdef>
+ <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>oc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XOMOfOC</function>
+function returns the output method associated with the
+specified output context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Xlib provides two functions for setting and reading output context values,
+respectively,
+<function>XSetOCValues</function>
+and
+<function>XGetOCValues</function>.
+Both functions have a variable-length argument list.
+In that argument list, any <acronym>XOC</acronym> value's name must be denoted
+with a character string using the X Portable Character Set.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set <acronym>XOC</acronym> values, use
+<function>XSetOCValues</function>.
+<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>oc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output context.
+<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable-length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetOCValues</function>
+function returns NULL if no error occurred;
+otherwise,
+it returns the name of the first argument that could not be set.
+An argument might not be set for any of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The argument is read-only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The argument name is not recognized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An implementation-dependent error occurs.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each value to be set must be an appropriate datum,
+matching the data type imposed by the semantics of the argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetOCValues</function>
+can generate a
+<function>BadAtom </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain <acronym>XOC</acronym> values, use
+<function>XGetOCValues</function>.
+<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>oc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the output context.
+<!-- .ds Al \ to get XOC values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable-length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetOCValues</function>
+function returns NULL if no error occurred; otherwise,
+it returns the name of the first argument that could not be obtained.
+An argument might not be obtained for any of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The argument name is not recognized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An implementation-dependent error occurs.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each argument value
+following a name must point to a location where the value is to be stored.
+</para>
+</sect2>
+
+<sect2 id="Output_Context_Values">
+<title>Output Context Values</title>
+<!-- .XS -->
+<!-- (SN Output Context Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following table describes how <acronym>XOC</acronym> values are interpreted
+by an output method.
+The first column lists the <acronym>XOC</acronym> values.
+The second column indicates the alternative interfaces that function
+identically and are provided for compatibility with previous releases.
+The third column indicates how each of the <acronym>XOC</acronym> values is treated.
+</para>
+<!-- .LP -->
+<para>
+The following keys apply to this table.
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Explanation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>C</entry>
+ <entry>This value must be set with <function>XCreateOC</function>.</entry>
+ </row>
+ <row>
+ <entry>D</entry>
+ <entry>This value may be set using <function>XCreateOC</function>.
+ If it is not set,a default is provided.</entry>
+ </row>
+ <row>
+ <entry>G</entry>
+ <entry>This value may be read using <function>XGetOCValues</function>.</entry>
+ </row>
+ <row>
+ <entry>S</entry>
+ <entry>This value must be set using <function>XSetOCValues</function>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry><acronym>XOC</acronym> Value</entry>
+ <entry>Alternative Interface</entry>
+ <entry>Key</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>BaseFontName</entry>
+ <entry><function>XCreateFontSet</function></entry>
+ <entry>C-G</entry>
+ </row>
+ <row>
+ <entry>MissingCharSet</entry>
+ <entry><function>XCreateFontSet</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry>DefaultString</entry>
+ <entry><function>XCreateFontSet</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry>Orientation</entry>
+ <entry>-</entry>
+ <entry>D-S-G</entry>
+ </row>
+ <row>
+ <entry>ResourceName</entry>
+ <entry>-</entry>
+ <entry>S-G</entry>
+ </row>
+ <row>
+ <entry>ResourceClass</entry>
+ <entry>-</entry>
+ <entry>S-G</entry>
+ </row>
+ <row>
+ <entry>FontInfo</entry>
+ <entry><function>XFontsOfFontSet</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry>OMAutomatic</entry>
+ <entry>-</entry>
+ <entry>G</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Base_Font_Name">
+<title>Base Font Name</title>
+<!-- .XS -->
+<!-- (SN Base Font Name -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNBaseFontName</function>
+argument is a list of base font names that Xlib uses
+to load the fonts needed for the locale.
+The base font names are a comma-separated list. The string is null-terminated
+and is assumed to be in the Host Portable Character Encoding;
+otherwise, the result is implementation-dependent.
+White space immediately on either side of a separating comma is ignored.
+</para>
+<para>
+<!-- .LP -->
+Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a
+variety of locales from a single locale-independent base font name.
+The single base font name should name a family of fonts whose members
+are encoded in the various charsets needed by the locales of interest.
+</para>
+<para>
+<!-- .LP -->
+An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.
+This allows the user to specify an exact font for use with a charset required
+by a locale, fully controlling the font selection.
+</para>
+<para>
+<!-- .LP -->
+If a base font name is not an <acronym>XLFD</acronym> name,
+Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
+for the font.
+If Xlib is successful, the
+<function>XGetOCValues</function>
+function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
+</para>
+<para>
+<!-- .LP -->
+This argument must be set at creation time
+and cannot be changed.
+If no fonts exist for any of the required charsets,
+or if the locale definition in Xlib requires that a font exist
+for a particular charset and a font is not found for that charset,
+<function>XCreateOC</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+When querying for the
+<function>XNBaseFontName</function>
+<acronym>XOC</acronym> value,
+<function>XGetOCValues</function>
+returns a null-terminated string identifying the base font names that
+Xlib used to load the fonts needed for the locale.
+This string is owned by Xlib and should not be modified or freed by
+the client.
+The string will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<function>XOC</function>.
+Until freed, the string contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Missing_CharSet">
+<title>Missing CharSet</title>
+<!-- .XS -->
+<!-- (SN Missing CharSet -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNMissingCharSet</function>
+argument returns the list of required charsets that are missing from the
+font set.
+The value of the argument is a pointer to a structure of type
+<function>XOMCharSetList</function>.
+</para>
+<para>
+<!-- .LP -->
+If fonts exist for all of the charsets required by the current locale,
+charset_list is set to NULL and charset_count is set to zero.
+If no fonts exist for one or more of the required charsets,
+charset_list is set to a list of one or more null-terminated charset names
+for which no fonts exist, and charset_count is set to the number of
+missing charsets.
+The charsets are from the list of the required charsets for
+the encoding of the locale and do not include any charsets to which Xlib
+may be able to remap a required charset.
+</para>
+<para>
+<!-- .LP -->
+The missing charset list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<function>XOC</function>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Default_String">
+<title>Default String</title>
+<!-- .XS -->
+<!-- (SN Default String -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When a drawing or measuring function is called with an
+<function>XOC</function>
+that has missing charsets, some characters in the locale will not be
+drawable.
+The
+<function>XNDefaultString</function>
+argument returns a pointer to a string that represents the glyphs
+that are drawn with this
+<function>XOC</function>
+when the charsets of the available fonts do not include all glyphs
+required to draw a character.
+The string does not necessarily consist of valid characters
+in the current locale and is not necessarily drawn with
+the fonts loaded for the font set,
+but the client can draw or measure the default glyphs
+by including this string in a string being drawn or measured with the
+<function>XOC</function>.
+</para>
+<para>
+<!-- .LP -->
+If the
+<function>XNDefaultString</function>
+argument returned the empty string (""),
+no glyphs are drawn and the escapement is zero.
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<function>XOC</function>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Orientation">
+<title>Orientation</title>
+<!-- .XS -->
+<!-- (SN Orientation -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNOrientation</function>
+argument specifies the current orientation of text when drawn. The value of
+this argument is one of the values returned by the
+<function>XGetOMValues</function>
+function with the
+<function>XNQueryOrientation</function>
+argument specified in the
+<function>XOrientation</function>
+list.
+The value of the argument is of type
+<function>XOrientation</function>.
+When
+<function>XNOrientation</function>
+is queried, the value specifies the current orientation.
+When
+<function>XNOrientation</function>
+is set, a value is used to set the current orientation.
+</para>
+<para>
+<!-- .LP -->
+When
+<function>XOMOrientation_Context</function>
+is set, the text orientation of the
+text is determined according to an implementation-defined method
+(for example, ISO 6429 control sequences), and the initial text orientation for
+locale-dependent Xlib functions is assumed to
+be
+<function>XOMOrientation_LTR_TTB</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XNOrientation</function>
+value does not change the prime drawing direction
+for Xlib drawing functions.
+</para>
+</sect3>
+<sect3 id="Resource_Name_and_Class">
+<title>Resource Name and Class</title>
+<!-- .XS -->
+<!-- (SN Resource Name and Class -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNResourceName</function>
+and
+<function>XNResourceClass</function>
+arguments are strings that specify the full name and class
+used by the client to obtain resources for the display of the output context.
+These values should be used as prefixes for name and class
+when looking up resources that may vary according to the output context.
+If these values are not set,
+the resources will not be fully specified.
+</para>
+<para>
+<!-- .LP -->
+It is not intended that values that can be set as <acronym>XOM</acronym> values be
+set as resources.
+</para>
+<para>
+<!-- .LP -->
+When querying for the
+<function>XNResourceName</function>
+or
+<function>XNResourceClass</function>
+<acronym>XOC</acronym> value,
+<function>XGetOCValues</function>
+returns a null-terminated string.
+This string is owned by Xlib and should not be modified or freed by
+the client.
+The string will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<function>XOC</function>
+or when the associated value is changed via
+<function>XSetOCValues</function>.
+Until freed, the string contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Font_Info">
+<title>Font Info</title>
+<!-- .XS -->
+<!-- (SN Font Info -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNFontInfo</function>
+argument specifies a list of one or more
+<function>XFontStruct</function>
+structures
+and font names for the fonts used for drawing by the given output context.
+The value of the argument is a pointer to a structure of type
+<function>XOMFontInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int num_font;
+ XFontStruct **font_struct_list;
+ char **font_name_list;
+} XOMFontInfo;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+A list of pointers to the
+<function>XFontStruct</function>
+structures is returned to font_struct_list.
+A list of pointers to null-terminated, fully-specified font name strings
+in the locale of the output context is returned to font_name_list.
+The font_name_list order corresponds to the font_struct_list order.
+The number of
+<function>XFontStruct</function>
+structures and font names is returned to num_font.
+</para>
+<para>
+<!-- .LP -->
+Because it is not guaranteed that a given character will be imaged using a
+single font glyph,
+there is no provision for mapping a character or default string
+to the font properties, font ID, or direction hint for the font
+for the character.
+The client may access the
+<function>XFontStruct</function>
+list to obtain these values for all the fonts currently in use.
+</para>
+<para>
+<!-- .LP -->
+Xlib does not guarantee that fonts are loaded from the server
+at the creation of an
+<function>XOC</function>.
+Xlib may choose to cache font data, loading it only as needed to draw text
+or compute text dimensions.
+Therefore, existence of the per_char metrics in the
+<function>XFontStruct</function>
+structures in the
+<function>XFontStructSet</function>
+is undefined.
+Also, note that all properties in the
+<function>XFontStruct</function>
+structures are in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The client must not free the
+<function>XOMFontInfo</function>
+struct itself; it will be freed when the
+<function>XOC</function>
+is closed.
+</para>
+</sect3>
+<sect3 id="OM_Automatic">
+<title>OM Automatic</title>
+<!-- .XS -->
+<!-- (SN OM Automatic -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNOMAutomatic</function>
+argument returns whether the associated output context was created by
+<function>XCreateFontSet</function>
+or not. Because the
+<function>XFreeFontSet</function>
+function not only destroys the output context but also closes the implicit
+output method associated with it,
+<function>XFreeFontSet</function>
+should be used with any output context created by
+<function>XCreateFontSet</function>.
+However, it is possible that a client does not know how the output context
+was created.
+Before a client destroys the output context,
+it can query whether
+<function>XNOMAutomatic</function>
+is set to determine whether
+<function>XFreeFontSet </function>
+or
+<function>XDestroyOC</function>
+should be used to destroy the output context.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Creating_and_Freeing_a_Font_Set">
+<title>Creating and Freeing a Font Set</title>
+<!-- .XS -->
+<!-- (SN Creating and Freeing a Font Set -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib international text drawing is done using a set of one or more fonts,
+as needed for the locale of the text.
+Fonts are loaded according to a list of base font names
+supplied by the client and the charsets required by the locale.
+The
+<function>XFontSet</function>
+is an opaque type representing the state of a particular output thread
+and is equivalent to the type
+<function>XOC</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The
+<function>XCreateFontSet</function>
+function is a convenience function for creating an output context using
+only default values. The returned
+<function>XFontSet</function>
+has an implicitly created
+<function>XOM</function>.
+This
+<function>XOM</function>
+has an OM value
+<function>XNOMAutomatic</function>
+automatically set to
+<function>True</function>
+so that the output context self indicates whether it was created by
+<function>XCreateOC</function>
+or
+<function>XCreateFontSet</function>.
+<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XFontSet<function> XCreateFontSet</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *base_font_name_list</parameter></paramdef>
+ <paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef>
+ <paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef>
+ <paramdef>char<parameter> **def_string_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base_font_name_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base font names.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>missing_charset_list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the missing charsets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>missing_charset_count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of missing charsets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>def_string_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the string drawn for missing charsets.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateFontSet</function>
+function creates a font set for the specified display.
+The font set is bound to the current locale when
+<function>XCreateFontSet</function>
+is called.
+The font set may be used in subsequent calls to obtain font
+and character information and to image text in the locale of the font set.
+</para>
+<para>
+<!-- .LP -->
+The base_font_name_list argument is a list of base font names
+that Xlib uses to load the fonts needed for the locale.
+The base font names are a comma-separated list.
+The string is null-terminated
+and is assumed to be in the Host Portable Character Encoding;
+otherwise, the result is implementation-dependent.
+White space immediately on either side of a separating comma is ignored.
+</para>
+<para>
+<!-- .LP -->
+Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a
+variety of locales from a single locale-independent base font name.
+The single base font name should name a family of fonts whose members
+are encoded in the various charsets needed by the locales of interest.
+</para>
+<para>
+<!-- .LP -->
+An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.
+This allows the user to specify an exact font for use with a charset required
+by a locale, fully controlling the font selection.
+</para>
+<para>
+<!-- .LP -->
+If a base font name is not an <acronym>XLFD</acronym> name,
+Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
+for the font.
+If this action is successful in obtaining an <acronym>XLFD</acronym> name, the
+<function>XBaseFontNameListOfFontSet</function>
+function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
+</para>
+<para>
+<!-- .LP -->
+Xlib uses the following algorithm to select the fonts
+that will be used to display text with the
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+For each font charset required by the locale,
+the base font name list is searched for the first appearance of one
+of the following cases that names a set of fonts that exist at the server:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The first <acronym>XLFD</acronym>-conforming base font name that specifies the required
+charset or a superset of the required charset in its
+<function>CharSetRegistry</function>
+and
+<function>CharSetEncoding</function>
+fields.
+The implementation may use a base font name whose specified charset
+is a superset of the required charset, for example,
+an ISO8859-1 font for an ASCII charset.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The first set of one or more <acronym>XLFD</acronym>-conforming base font names
+that specify one or more charsets that can be remapped to support the
+required charset.
+The Xlib implementation may recognize various mappings
+from a required charset to one or more other charsets
+and use the fonts for those charsets.
+For example, JIS Roman is ASCII with tilde and backslash replaced
+by yen and overbar;
+Xlib may load an ISO8859-1 font to support this character set
+if a JIS Roman font is not available.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The first <acronym>XLFD</acronym>-conforming font name or the first non-<acronym>XLFD</acronym> font name
+for which an <acronym>XLFD</acronym> font name can be obtained, combined with the
+required charset (replacing the
+<function>CharSetRegistry</function>
+and
+<function>CharSetEncoding</function>
+fields in the <acronym>XLFD</acronym> font name).
+As in case 1,
+the implementation may use a charset that is a superset
+of the required charset.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The first font name that can be mapped in some implementation-dependent
+manner to one or more fonts that support imaging text in the charset.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For example, assume that a locale required the charsets:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+ISO8859-1
+JISX0208.1983
+JISX0201.1976
+GB2312-1980.0
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The user could supply a base_font_name_list that explicitly specifies the
+charsets, ensuring that specific fonts are used if they exist.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
+-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Alternatively, the user could supply a base_font_name_list
+that omits the charsets,
+letting Xlib select font charsets required for the locale.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
+-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Alternatively, the user could simply supply a single base font name
+that allows Xlib to select from all available fonts
+that meet certain minimum <acronym>XLFD</acronym> property requirements.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"-*-*-*-R-Normal--*-180-100-100-*-*"
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XCreateFontSet</function>
+is unable to create the font set,
+either because there is insufficient memory or because the current locale
+is not supported,
+<function>XCreateFontSet</function>
+returns NULL, missing_charset_list_return is set to NULL,
+and missing_charset_count_return
+is set to zero.
+If fonts exist for all of the charsets required by the current locale,
+<function>XCreateFontSet</function>
+returns a valid
+<function>XFontSet</function>,
+missing_charset_list_return is set to NULL,
+and missing_charset_count_return is set to zero.
+</para>
+<para>
+<!-- .LP -->
+If no font exists for one or more of the required charsets,
+<function>XCreateFontSet</function>
+sets missing_charset_list_return to a
+list of one or more null-terminated charset names for which no font exists
+and sets missing_charset_count_return to the number of missing fonts.
+The charsets are from the list of the required charsets for
+the encoding of the locale and do not include any charsets to which Xlib
+may be able to remap a required charset.
+</para>
+<para>
+<!-- .LP -->
+If no font exists for any of the required charsets
+or if the locale definition in Xlib requires that a font exist
+for a particular charset and a font is not found for that charset,
+<function>XCreateFontSet</function>
+returns NULL.
+Otherwise,
+<function>XCreateFontSet</function>
+returns a valid
+<function>XFontSet</function>
+to font_set.
+</para>
+<para>
+<!-- .LP -->
+When an Xmb/wc drawing or measuring function is called with an
+<function>XFontSet</function>
+that has missing charsets, some characters in the locale will not be
+drawable.
+If def_string_return is non-NULL,
+<function>XCreateFontSet</function>
+returns a pointer to a string that represents the glyphs
+that are drawn with this
+<function>XFontSet</function>
+when the charsets of the available fonts do not include all font glyphs
+required to draw a codepoint.
+The string does not necessarily consist of valid characters
+in the current locale and is not necessarily drawn with
+the fonts loaded for the font set,
+but the client can draw and measure the default glyphs
+by including this string in a string being drawn or measured with the
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+If the string returned to def_string_return is the empty string (""),
+no glyphs are drawn, and the escapement is zero.
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It will be freed by a call to
+<function>XFreeFontSet</function>
+with the associated
+<function>XFontSet</function>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+The client is responsible for constructing an error message from the
+missing charset and default string information and may choose to continue
+operation in the case that some fonts did not exist.
+</para>
+<para>
+<!-- .LP -->
+The returned
+<function>XFontSet</function>
+and missing charset list should be freed with
+<function>XFreeFontSet</function>
+and
+<function>XFreeStringList</function>,
+respectively.
+The client-supplied base_font_name_list may be freed
+by the client after calling
+<function>XCreateFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of
+<function>XFontStruct</function>
+structures and full font names given an
+<function>XFontSet</function>,
+use
+<function>XFontsOfFontSet</function>.
+<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XFontsOfFontSet</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef>
+ <paramdef>char<parameter> ***font_name_list_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_struct_list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of font structs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_name_list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of font names.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFontsOfFontSet</function>
+function returns a list of one or more
+<function>XFontStructs</function>
+and font names for the fonts used by the Xmb and Xwc layers
+for the given font set.
+A list of pointers to the
+<function>XFontStruct</function>
+structures is returned to font_struct_list_return.
+A list of pointers to null-terminated, fully specified font name strings
+in the locale of the font set is returned to font_name_list_return.
+The font_name_list order corresponds to the font_struct_list order.
+The number of
+<function>XFontStruct</function>
+structures and font names is returned as the value of the function.
+</para>
+<para>
+<!-- .LP -->
+Because it is not guaranteed that a given character will be imaged using a
+single font glyph,
+there is no provision for mapping a character or default string
+to the font properties, font ID, or direction hint for the font
+for the character.
+The client may access the
+<function>XFontStruct</function>
+list to obtain these values for all the fonts currently in use.
+</para>
+<para>
+<!-- .LP -->
+Xlib does not guarantee that fonts are loaded from the server
+at the creation of an
+<function>XFontSet</function>.
+Xlib may choose to cache font data, loading it only as needed to draw text
+or compute text dimensions.
+Therefore, existence of the per_char metrics in the
+<function>XFontStruct</function>
+structures in the
+<function>XFontStructSet</function>
+is undefined.
+Also, note that all properties in the
+<function>XFontStruct</function>
+structures are in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XFontStruct</function>
+and font name lists are owned by Xlib
+and should not be modified or freed by the client.
+They will be freed by a call to
+<function>XFreeFontSet</function>
+with the associated
+<function>XFontSet</function>.
+Until freed, their contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the base font name list and the selected font name list given an
+<function>XFontSet</function>,
+use
+<function>XBaseFontNameListOfFontSet</function>.
+<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XBaseFontNameListOfFontSet</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XBaseFontNameListOfFontSet</function>
+function returns the original base font name list supplied
+by the client when the
+<function>XFontSet</function>
+was created.
+A null-terminated string containing a list of
+comma-separated font names is returned
+as the value of the function.
+White space may appear immediately on either side of separating commas.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XCreateFontSet</function>
+obtained an <acronym>XLFD</acronym> name from the font properties for the font specified
+by a non-<acronym>XLFD</acronym> base name, the
+<function>XBaseFontNameListOfFontSet</function>
+function will return the <acronym>XLFD</acronym> name instead of the non-<acronym>XLFD</acronym> base name.
+</para>
+<para>
+<!-- .LP -->
+The base font name list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to
+<function>XFreeFontSet</function>
+with the associated
+<function>XFontSet</function>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the locale name given an
+<function>XFontSet</function>,
+use
+<function>XLocaleOfFontSet</function>.
+<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XLocaleOfFontSet</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLocaleOfFontSet</function>
+function
+returns the name of the locale bound to the specified
+<function>XFontSet</function>,
+as a null-terminated string.
+</para>
+<para>
+<!-- .LP -->
+The returned locale name string is owned by Xlib
+and should not be modified or freed by the client.
+It may be freed by a call to
+<function>XFreeFontSet</function>
+with the associated
+<function>XFontSet</function>.
+Until freed, it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The
+<function>XFreeFontSet</function>
+function is a convenience function for freeing an output context.
+<function>XFreeFontSet </function>
+also frees its associated
+<function>XOM</function>
+if the output context was created by
+<function>XCreateFontSet</function>.
+<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XFreeFontSet</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontSet</function>
+function frees the specified font set.
+The associated base font name list, font name list,
+<function>XFontStruct</function>
+list, and
+<function>XFontSetExtents</function>,
+if any, are freed.
+</para>
+</sect2>
+<sect2 id="Obtaining_Font_Set_Metrics">
+<title>Obtaining Font Set Metrics</title>
+<!-- .XS -->
+<!-- (SN Obtaining Font Set Metrics -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Metrics for the internationalized text drawing functions
+are defined in terms of a primary draw direction,
+which is the default direction in which the character origin advances
+for each succeeding character in the string.
+The Xlib interface is currently defined to support only a left-to-right
+primary draw direction.
+The drawing origin is the position passed to the drawing function
+when the text is drawn.
+The baseline is a line drawn through the drawing origin parallel
+to the primary draw direction.
+Character ink is the pixels painted in the foreground color
+and does not include interline or intercharacter spacing
+or image text background pixels.
+</para>
+<para>
+<!-- .LP -->
+The drawing functions are allowed to implement implicit text
+directionality control, reversing the order in which characters are
+rendered along the primary draw direction in response to locale-specific
+lexical analysis of the string.
+</para>
+<para>
+<!-- .LP -->
+Regardless of the character rendering order,
+the origins of all characters are on the primary draw direction side
+of the drawing origin.
+The screen location of a particular character image may be determined with
+<function>XmbTextPerCharExtents</function>
+or
+<function>XwcTextPerCharExtents</function>.
+</para>
+<para>
+<!-- .LP -->
+The drawing functions are allowed to implement context-dependent
+rendering, where the glyphs drawn for a string are not simply a
+concatenation of the glyphs that represent each individual character.
+A string of two characters drawn with
+<function>XmbDrawString</function>
+may render differently than if the two characters
+were drawn with separate calls to
+<function>XmbDrawString</function>.
+If the client appends or inserts a character
+in a previously drawn string,
+the client may need to redraw some adjacent characters
+to obtain proper rendering.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find out about direction-dependent rendering, use
+<function>XDirectionalDependentDrawing</function>.
+<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XDirectionalDependentDrawing</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDirectionalDependentDrawing</function>
+function returns
+<function>True</function>
+if the drawing functions implement implicit text directionality;
+otherwise, it returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find out about context-dependent rendering, use
+<function>XContextualDrawing</function>.
+<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XContextualDrawing</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XContextualDrawing</function>
+function returns
+<function>True</function>
+if text drawn with the font set might include context-dependent drawing;
+otherwise, it returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find out about context-dependent or direction-dependent rendering, use
+<function>XContextDependentDrawing</function>.
+<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XContextDependentDrawing</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XContextDependentDrawing</function>
+function returns
+<function>True</function>
+if the drawing functions implement implicit text directionality or
+if text drawn with the font_set might include context-dependent drawing;
+otherwise, it returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+The drawing functions do not interpret newline, tab, or other control
+characters.
+The behavior when nonprinting characters other than space are drawn
+is implementation-dependent.
+It is the client's responsibility to interpret control characters
+in a text stream.
+</para>
+<para>
+<!-- .LP -->
+The maximum character extents for the fonts that are used by the text
+drawing layers can be accessed by the
+<function>XFontSetExtents</function>
+structure:
+<indexterm significance="preferred"><primary>XFontSetExtents</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ XRectangle max_ink_extent; /* over all drawable characters */
+ XRectangle max_logical_extent; /* over all drawable characters */
+} XFontSetExtents;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XRectangle</function>
+structures used to return font set metrics are the usual Xlib screen-oriented
+rectangles
+with x, y giving the upper left corner, and width and height always positive.
+</para>
+<para>
+<!-- .LP -->
+The max_ink_extent member gives the maximum extent, over all drawable characters, of
+the rectangles that bound the character glyph image drawn in the
+foreground color, relative to a constant origin.
+See
+<function>XmbTextExtents</function>
+and
+<function>XwcTextExtents</function>
+for detailed semantics.
+</para>
+<para>
+<!-- .LP -->
+The max_logical_extent member gives the maximum extent,
+over all drawable characters, of the rectangles
+that specify minimum spacing to other graphical features,
+relative to a constant origin.
+Other graphical features drawn by the client, for example,
+a border surrounding the text, should not intersect this rectangle.
+The max_logical_extent member should be used to compute minimum
+interline spacing and the minimum area that must be allowed
+in a text field to draw a given number of arbitrary characters.
+</para>
+<para>
+<!-- .LP -->
+Due to context-dependent rendering,
+appending a given character to a string may change
+the string's extent by an amount other than that character's
+individual extent.
+</para>
+<para>
+<!-- .LP -->
+The rectangles for a given character in a string can be obtained from
+<function>XmbPerCharExtents</function>
+or
+<function>XwcPerCharExtents</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the maximum extents structure given an
+<function>XFontSet</function>,
+use
+<function>XExtentsOfFontSet</function>.
+<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XFontSetExtents<function> *XExtentsOfFontSet</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XExtentsOfFontSet</function>
+function returns an
+<function>XFontSetExtents</function>
+structure for the fonts used by the Xmb and Xwc layers
+for the given font set.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XFontSetExtents</function>
+structure is owned by Xlib and should not be modified
+or freed by the client.
+It will be freed by a call to
+<function>XFreeFontSet</function>
+with the associated
+<function>XFontSet</function>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the escapement in pixels of the specified text as a value,
+use
+<function>XmbTextEscapement</function>
+or
+<function>XwcTextEscapement</function>.
+<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbTextEscapement</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcTextEscapement</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_wchars</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_wchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextEscapement</function>
+and
+<function>XwcTextEscapement</function>
+functions return the escapement in pixels of the specified string as a value,
+using the fonts loaded for the specified font set.
+The escapement is the distance in pixels in the primary draw
+direction from the drawing origin to the origin of the next character to
+be drawn, assuming that the rendering of the next character is not
+dependent on the supplied string.
+</para>
+<para>
+<!-- .LP -->
+Regardless of the character rendering order,
+the escapement is always positive.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the overall_ink_return and overall_logical_return arguments,
+the overall bounding box of the string's image, and a logical bounding box,
+use
+<function>XmbTextExtents</function>
+ or
+<function>XwcTextExtents</function>.
+<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbTextExtents</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_bytes</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcTextExtents</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_wchars</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_wchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+<!-- .ds Ov dimensions -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_ink_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall ink dimensions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_logical_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall logical dimensions.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextExtents</function>
+and
+<function>XwcTextExtents</function>
+functions set the components of the specified overall_ink_return and
+overall_logical_return
+arguments to the overall bounding box of the string's image
+and a logical bounding box for spacing purposes, respectively.
+They return the value returned by
+<function>XmbTextEscapement</function>
+or
+<function>XwcTextEscapement</function>.
+These metrics are relative to the drawing origin of the string,
+using the fonts loaded for the specified font set.
+</para>
+<para>
+<!-- .LP -->
+If the overall_ink_return argument is non-NULL,
+it is set to the bounding box of the string's character ink.
+The overall_ink_return for a nondescending, horizontally drawn
+Latin character is conventionally entirely above the baseline;
+that is, overall_ink_return.height <= -overall_ink_return.y.
+The overall_ink_return for a nonkerned character
+is entirely at, and to the right of, the origin;
+that is, overall_ink_return.x >= 0.
+A character consisting of a single pixel at the origin would set
+overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.
+</para>
+<para>
+<!-- .LP -->
+If the overall_logical_return argument is non-NULL,
+it is set to the bounding box that provides minimum spacing
+to other graphical features for the string.
+Other graphical features, for example, a border surrounding the text,
+should not intersect this rectangle.
+</para>
+<para>
+<!-- .LP -->
+When the
+<function>XFontSet</function>
+has missing charsets,
+metrics for each unavailable character are taken
+from the default string returned by
+<function>XCreateFontSet </function>
+so that the metrics represent the text as it will actually be drawn.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+To determine the effective drawing origin for a character in a drawn string,
+the client should call
+<function>XmbTextPerCharExtents</function>
+on the entire string, then on the character,
+and subtract the x values of the returned
+rectangles for the character.
+This is useful to redraw portions of a line of text
+or to justify words, but for context-dependent rendering,
+the client should not assume that it can redraw the character by itself
+and get the same rendering.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain per-character information for a text string,
+use
+<function>XmbTextPerCharExtents</function>
+or
+<function>XwcTextPerCharExtents</function>.
+<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XmbTextPerCharExtents</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_bytes</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
+ <paramdef>int<parameter> array_size</parameter></paramdef>
+ <paramdef>int<parameter> *num_chars_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XwcTextPerCharExtents</function></funcdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_wchars</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
+ <paramdef>int<parameter> array_size</parameter></paramdef>
+ <paramdef>int<parameter> *num_chars_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_wchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ink_array_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the ink dimensions for each character.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>logical_array_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the logical dimensions for each character.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>array_size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of ink_array_return and logical_array_return.
+The caller must pass in arrays of this size.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_chars_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of characters in the string argument.
+<!-- .ds Ov extents of the entire string -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_ink_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall ink dimensions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>overall_logical_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the overall logical dimensions.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextPerCharExtents</function>
+and
+<function>XwcTextPerCharExtents</function>
+functions return the text dimensions of each character of the specified text,
+using the fonts loaded for the specified font set.
+Each successive element of ink_array_return and logical_array_return
+is set to the successive character's drawn metrics,
+relative to the drawing origin of the string and one
+rectangle
+for each character in the supplied text string.
+The number of elements of ink_array_return and logical_array_return
+that have been set is returned to num_chars_return.
+</para>
+<para>
+<!-- .LP -->
+Each element of ink_array_return is set to the bounding box
+of the corresponding character's drawn foreground color.
+Each element of logical_array_return is set to the bounding box
+that provides minimum spacing to other graphical features
+for the corresponding character.
+Other graphical features should not intersect any of the
+logical_array_return rectangles.
+</para>
+<para>
+<!-- .LP -->
+Note that an
+<function>XRectangle</function>
+represents the effective drawing dimensions of the character,
+regardless of the number of font glyphs that are used to draw
+the character or the direction in which the character is drawn.
+If multiple characters map to a single character glyph,
+the dimensions of all the
+<function>XRectangles</function>
+of those characters are the same.
+</para>
+<para>
+<!-- .LP -->
+When the
+<function>XFontSet</function>
+has missing charsets, metrics for each unavailable
+character are taken from the default string returned by
+<function>XCreateFontSet</function>
+so that the metrics represent the text as it will actually be drawn.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+If the array_size is too small for the number of characters in the
+supplied text, the functions return zero
+and num_chars_return is set to the number of rectangles required.
+Otherwise, the functions return a nonzero value.
+</para>
+<para>
+<!-- .LP -->
+If the overall_ink_return or overall_logical_return argument is non-NULL,
+<function>XmbTextPerCharExtents</function>
+and
+<function>XwcTextPerCharExtents</function>
+return the maximum extent of the string's metrics to overall_ink_return
+or overall_logical_return, as returned by
+<function>XmbTextExtents</function>
+or
+<function>XwcTextExtents</function>.
+</para>
+</sect2>
+<sect2 id="Drawing_Text_Using_Font_Sets">
+<title>Drawing Text Using Font Sets</title>
+<!-- .XS -->
+<!-- (SN Drawing Text Using Font Sets -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The functions defined in this section
+draw text at a specified location in a drawable.
+They are similar to the functions
+<function>XDrawText</function>,
+<function>XDrawString</function>,
+and
+<function>XDrawImageString</function>
+except that they work with font sets instead of single fonts
+and interpret the text based on the locale of the font set
+instead of treating the bytes of the string as direct font indexes.
+See section 8.6 for details of the use of Graphics Contexts (GCs)
+and possible protocol errors.
+If a
+<function>BadFont</function>
+error is generated,
+characters prior to the offending character may have been drawn.
+</para>
+<para>
+<!-- .LP -->
+The text is drawn using the fonts loaded for the specified font set;
+the font in the GC is ignored and may be modified by the functions.
+No validation that all fonts conform to some width rule is performed.
+</para>
+<para>
+<!-- .LP -->
+The text functions
+<function>XmbDrawText</function>
+and
+<function>XwcDrawText</function>
+use the following structures:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XmbTextItem</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ char *chars; /* pointer to string */
+ int nchars; /* number of bytes */
+ int delta; /* pixel delta between strings */
+ XFontSet font_set; /* fonts, None means don't change */
+} XmbTextItem;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XwcTextItem</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ wchar_t *chars; /* pointer to wide char string */
+ int nchars; /* number of wide characters */
+ int delta; /* pixel delta between strings */
+ XFontSet font_set; /* fonts, None means don't change */
+} XwcTextItem;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw text using multiple font sets in a given drawable, use
+<function>XmbDrawText</function>
+or
+<function>XwcDrawText</function>.
+<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XmbDrawText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>XmbTextItem<parameter> *items</parameter></paramdef>
+ <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XwcDrawText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>XwcTextItem<parameter> *items</parameter></paramdef>
+ <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>items</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of text items.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of text items in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbDrawText</function>
+and
+<function>XwcDrawText </function>
+functions allow complex spacing and font set shifts between text strings.
+Each text item is processed in turn, with the origin of a text
+element advanced in the primary draw direction by the escapement of the
+previous text item.
+A text item delta specifies an additional escapement of the text item
+drawing origin in the primary draw direction.
+A font_set member other than
+<function>None</function>
+in an item causes the font set to be used for this and subsequent text items
+in the text_items list.
+Leading text items with a font_set member set to
+<function>None</function>
+will not be drawn.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbDrawText</function>
+and
+<function>XwcDrawText</function>
+do not perform any context-dependent rendering between text segments.
+Clients may compute the drawing metrics by passing each text segment to
+<function>XmbTextExtents</function>
+and
+<function>XwcTextExtents</function>
+or
+<function>XmbTextPerCharExtents</function>
+and
+<function>XwcTextPerCharExtents</function>.
+When the
+<function>XFontSet</function>
+has missing charsets, each unavailable character is drawn
+with the default string returned by
+<function>XCreateFontSet</function>.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw text using a single font set in a given drawable, use
+<function>XmbDrawString</function>
+or
+<function>XwcDrawString</function>.
+<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XmbDrawString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XwcDrawString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_wchars</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_wchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbDrawString</function>
+and
+<function>XwcDrawString</function>
+functions draw the specified text with the foreground pixel.
+When the
+<function>XFontSet</function>
+has missing charsets, each unavailable character is drawn
+with the default string returned by
+<function>XCreateFontSet</function>.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw image text using a single font set in a given drawable, use
+<function>XmbDrawImageString</function>
+or
+<function>XwcDrawImageString</function>.
+<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XmbDrawImageString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XwcDrawImageString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_wchars</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>font_set</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the font set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+<!-- .ds Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_wchars</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of characters in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbDrawImageString</function>
+and
+<function>XwcDrawImageString</function>
+functions fill a destination rectangle with the background pixel defined
+in the GC and then paint the text with the foreground pixel.
+The filled rectangle is the rectangle returned to overall_logical_return by
+<function>XmbTextExtents</function>
+or
+<function>XwcTextExtents</function>
+for the same text and
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+When the
+<function>XFontSet</function>
+has missing charsets, each unavailable character is drawn
+with the default string returned by
+<function>XCreateFontSet</function>.
+The behavior for an invalid codepoint is undefined.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Input_Methods">
+<title>Input Methods</title>
+<!-- .XS -->
+<!-- (SN Input Methods -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section provides discussions of the following X Input Method
+(<acronym>XIM</acronym>) topics:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Input method overview
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input method management
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input method functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input method values
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input context functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input context values
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input method callback semantics
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Event filtering
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Getting keyboard input
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input method conventions
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Input_Method_Overview">
+<title>Input Method Overview</title>
+<!-- .XS -->
+<!-- (SN Input Method Overview -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section provides definitions for terms and concepts used
+for internationalized text input and a brief overview of the
+intended use of the mechanisms provided by Xlib.
+</para>
+<para>
+<!-- .LP -->
+A large number of languages in the world use alphabets
+consisting of a small set of symbols (letters) to form words.
+To enter text into a computer in an alphabetic language,
+a user usually has a keyboard on which there exist key symbols corresponding
+to the alphabet.
+Sometimes, a few characters of an alphabetic language are missing
+on the keyboard.
+Many computer users who speak a Latin-alphabet-based language
+only have an English-based keyboard.
+They need to hit a combination of keystrokes
+to enter a character that does not exist directly on the keyboard.
+A number of algorithms have been developed for entering such characters.
+These are known as European input methods, compose input methods,
+or dead-key input methods.
+</para>
+<para>
+<!-- .LP -->
+Japanese is an example of a language with a phonetic symbol set,
+where each symbol represents a specific sound.
+There are two phonetic symbol sets in Japanese: Katakana and Hiragana.
+In general,
+Katakana is used for words that are of foreign origin,
+and Hiragana is used for writing native Japanese words.
+Collectively, the two systems are called Kana.
+Each set consists of 48 characters.
+</para>
+<para>
+<!-- .LP -->
+Korean also has a phonetic symbol set, called Hangul.
+Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
+represents a specific sound.
+A syllable is composed of two or three parts:
+the initial consonants, the vowels, and the optional last consonants.
+With Hangul,
+syllables can be treated as the basic units on which text processing is done.
+For example,
+a delete operation may work on a phonetic symbol or a syllable.
+Korean code sets include several thousands of these syllables.
+A user types the phonetic symbols that make up the syllables of the words
+to be entered.
+The display may change as each phonetic symbol is entered.
+For example,
+when the second phonetic symbol of a syllable is entered,
+the first phonetic symbol may change its shape and size.
+Likewise, when the third phonetic symbol is entered,
+the first two phonetic symbols may change their shape and size.
+</para>
+<para>
+<!-- .LP -->
+Not all languages rely solely on alphabetic or phonetic systems.
+Some languages, including Japanese and Korean, employ an
+ideographic writing system.
+In an ideographic system, rather than taking a small set of
+symbols and combining them in different ways to create words,
+each word consists of one unique symbol (or, occasionally, several symbols).
+The number of symbols can be very large:
+approximately 50,000 have been identified in Hanzi,
+the Chinese ideographic system.
+</para>
+<para>
+<!-- .LP -->
+Two major aspects of ideographic systems impact their use with computers.
+First, the standard computer character sets in Japan, China, and Korea
+include roughly 8,000 characters,
+while sets in Taiwan have between 15,000 and 30,000 characters.
+This makes it necessary to use more than one byte to represent a character.
+Second, it obviously is impractical to have a keyboard that includes
+all of a given language's ideographic symbols.
+Therefore, a mechanism is required for entering characters
+so that a keyboard with a reasonable number of keys can be used.
+Those input methods are usually based on phonetics,
+but there also exist methods based on the graphical properties of
+characters.
+</para>
+<para>
+<!-- .LP -->
+In Japan, both Kana and the ideographic system Kanji are used.
+In Korea, Hangul and sometimes the ideographic system Hanja are used.
+Now consider entering ideographs in Japan, Korea, China, and Taiwan.
+</para>
+<para>
+<!-- .LP -->
+In Japan, either Kana or English characters are typed and then a region
+is selected (sometimes automatically) for conversion to Kanji.
+Several Kanji characters may have the same phonetic representation.
+If that is the case with the string entered,
+a menu of characters is presented and
+the user must choose the appropriate one.
+If no choice is necessary or a preference has been established,
+the input method does the substitution directly.
+When Latin characters are converted to Kana or Kanji,
+it is called a romaji conversion.
+</para>
+<para>
+<!-- .LP -->
+In Korea, it is usually acceptable to keep Korean text in Hangul form,
+but some people may choose to write Hanja-originated words in Hanja
+rather than in Hangul.
+To change Hangul to Hanja,
+the user selects a region for conversion
+and then follows the same basic method as that described for Japanese.
+</para>
+<para>
+<!-- .LP -->
+Probably because there are well-accepted phonetic writing systems
+for Japanese and Korean,
+computer input methods in these countries for entering ideographs
+are fairly standard.
+Keyboard keys have both English characters and phonetic symbols
+engraved on them, and the user can switch between the two sets.
+</para>
+<para>
+<!-- .LP -->
+The situation is different for Chinese.
+While there is a phonetic system called Pinyin promoted by authorities,
+there is no consensus for entering Chinese text.
+Some vendors use a phonetic decomposition (Pinyin or another),
+others use ideographic decomposition of Chinese words,
+with various implementations and keyboard layouts.
+There are about 16 known methods, none of which is a clear standard.
+</para>
+<para>
+<!-- .LP -->
+Also, there are actually two ideographic sets used:
+Traditional Chinese (the original written Chinese)
+and Simplified Chinese.
+Several years ago,
+the People's Republic of China launched a campaign to simplify
+some ideographic characters and eliminate redundancies altogether.
+Under the plan,
+characters would be streamlined every five years.
+Characters have been revised several times now,
+resulting in the smaller, simpler set that makes up Simplified Chinese.
+</para>
+<sect3 id="Input_Method_Architecture">
+<title>Input Method Architecture</title>
+<!-- .XS -->
+<!-- (SN Input Method Architecture -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+As shown in the previous section,
+there are many different input methods in use today,
+each varying with language, culture, and history.
+A common feature of many input methods is that the user may type
+multiple keystrokes to compose a single character (or set
+of characters).
+The process of composing characters from keystrokes is called
+<emphasis remap='I'>preediting</emphasis>.
+It may require complex algorithms and large dictionaries
+involving substantial computer resources.
+</para>
+<para>
+<!-- .LP -->
+Input methods may require one or more areas in which to show the
+feedback of the actual keystrokes, to propose disambiguation to the
+user, to list dictionaries, and so on.
+The input method areas of concern are as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The <emphasis remap='I'>status</emphasis> area is a logical extension of the
+LEDs that exist on the physical keyboard.
+It is a window that is intended to present the internal state
+of the input method that is critical to the user.
+The status area may consist of text data and bitmaps or some combination.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>preedit</emphasis> area displays the
+intermediate text for those languages that are composing prior to
+the client handling the data.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>auxiliary</emphasis> area is used for pop-up menus and customizing
+dialogs that may be required for an input method.
+There may be multiple auxiliary areas for an input method.
+Auxiliary areas are managed by the input method independent of the client.
+Auxiliary areas are assumed to be separate dialogs,
+which are maintained by the input method.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+There are various user interaction styles used for preediting.
+The ones supported by Xlib are as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+For <emphasis remap='I'>on-the-spot</emphasis> input methods,
+preediting data will be displayed directly in the application window.
+Application data is moved to allow preedit data to appear
+at the point of insertion.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<emphasis remap='I'>Over-the-spot</emphasis> preediting means that the data is displayed in
+a preedit window that is placed over the point of insertion.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<emphasis remap='I'>Off-the-spot</emphasis> preediting means that the preedit window is
+inside the application window but not at the point of insertion.
+Often, this type of window is placed at the bottom of the application window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<emphasis remap='I'>Root-window</emphasis> preediting refers to input methods that use a preedit
+window that is the child of
+<function>RootWindow</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+It would require a lot of computing resources if portable applications
+had to include input methods for all the languages in the world.
+To avoid this,
+a goal of the Xlib design is to allow an application
+to communicate with an input method placed in a separate process.
+Such a process is called an <emphasis remap='I'>input server</emphasis>.
+The server to which the application should connect is dependent on
+the environment when the application is started up,
+that is, the user language and the actual encoding to be used for it.
+The input method connection is said to be <emphasis remap='I'>locale-dependent</emphasis>.
+It is also user-dependent.
+For a given language, the user can choose, to some extent,
+the user interface style of input method (if choice is possible among
+several).
+</para>
+<para>
+<!-- .LP -->
+Using an input server implies communication overhead,
+but applications can be migrated without relinking.
+Input methods can be implemented either as a
+stub communicating to an input server or as a local library.
+</para>
+<para>
+<!-- .LP -->
+An input method may be based on a <emphasis remap='I'>front-end</emphasis> or a <emphasis remap='I'>back-end</emphasis>
+architecture.
+In a front-end architecture,
+there are two separate connections to the X server:
+keystrokes go directly from the X server to the input method on
+one connection and other events to the regular client connection.
+The input method is then acting as a filter and sends composed strings
+to the client.
+A front-end architecture requires synchronization between the
+two connections to avoid lost key events or locking issues.
+</para>
+<para>
+<!-- .LP -->
+In a back-end architecture,
+a single X server connection is used.
+A dispatching mechanism must decide on this channel to delegate appropriate
+keystrokes to the input method.
+For instance,
+it may retain a Help keystroke for its own purpose.
+In the case where the input method is a separate process (that is, a server),
+there must be a special communication protocol between the back-end client
+and the input server.
+</para>
+<para>
+<!-- .LP -->
+A front-end architecture introduces synchronization issues
+and a filtering mechanism for noncharacter keystrokes
+(Function keys, Help, and so on).
+A back-end architecture sometimes implies more communication overhead
+and more process switching.
+If all three processes (X server, input server, client)
+are running on a single workstation,
+there are two process switches for each keystroke in a back-end
+architecture,
+but there is only one in a front-end architecture.
+</para>
+<para>
+<!-- .LP -->
+The abstraction used by a client to communicate with an input method
+is an opaque data structure represented by the
+<function>XIM</function>
+data type.
+This data structure is returned by the
+<function>XOpenIM</function>
+function, which opens an input method on a given display.
+Subsequent operations on this data structure encapsulate all communication
+between client and input method.
+There is no need for an X client to use any networking library
+or natural language package to use an input method.
+</para>
+<para>
+<!-- .LP -->
+A single input server may be used for one or more languages,
+supporting one or more encoding schemes.
+But the strings returned from an input method will always be encoded
+in the (single) locale associated with the
+<function>XIM</function>
+object.
+</para>
+</sect3>
+<sect3 id="Input_Contexts">
+<title>Input Contexts</title>
+<!-- .XS -->
+<!-- (SN Input Contexts -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides the ability to manage a multi-threaded state for text input.
+A client may be using multiple windows,
+each window with multiple text entry areas,
+and the user possibly switching among them at any time.
+The abstraction for representing the state of a particular input thread
+is called an <emphasis remap='I'>input context</emphasis>.
+The Xlib representation of an input context is an
+<function>XIC</function>.
+</para>
+<para>
+<!-- .LP -->
+An input context is the abstraction retaining the state, properties,
+and semantics of communication between a client and an input method.
+An input context is a combination of an input method, a locale
+specifying the encoding of the character strings to be returned,
+a client window, internal state information,
+and various layout or appearance characteristics.
+The input context concept somewhat matches for input the graphics context
+abstraction defined for graphics output.
+</para>
+<para>
+<!-- .LP -->
+One input context belongs to exactly one input method.
+Different input contexts may be associated with the same input method,
+possibly with the same client window.
+An
+<function>XIC</function>
+is created with the
+<function>XCreateIC</function>
+function, providing an
+<function>XIM</function>
+argument and affiliating the input context to the input method
+for its lifetime.
+When an input method is closed with
+<function>XCloseIM</function>,
+all of its affiliated input contexts should not be used any more
+(and should preferably be destroyed before closing the input method).
+</para>
+<para>
+<!-- .LP -->
+Considering the example of a client window with multiple text entry areas,
+the application programmer could, for example, choose to implement as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+As many input contexts are created as text entry areas, and the client
+will get the input accumulated on each context each time it looks up
+in that context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A single context is created for a top-level window in the application.
+If such a window contains several text entry areas,
+each time the user moves to another text entry area,
+the client has to indicate changes in the context.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+A range of choices can be made by application designers to use
+either a single or multiple input contexts,
+according to the needs of their application.
+</para>
+</sect3>
+<sect3 id="Getting_Keyboard_Input">
+<title>Getting Keyboard Input</title>
+<!-- .XS -->
+<!-- (SN Getting Keyboard Input -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain characters from an input method,
+a client must call the function
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+with an input context created from that input method.
+Both a locale and display are bound to an input method when it is opened,
+and an input context inherits this locale and display.
+Any strings returned by
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+will be encoded in that locale.
+</para>
+</sect3>
+<sect3 id="Focus_Management">
+<title>Focus Management</title>
+<!-- .XS -->
+<!-- (SN Focus Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+For each text entry area in which the
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+functions are used,
+there will be an associated input context.
+</para>
+<para>
+<!-- .LP -->
+When the application focus moves to a text entry area,
+the application must set the input context focus to the
+input context associated with that area.
+The input context focus is set by calling
+<function>XSetICFocus</function>
+with the appropriate input context.
+</para>
+<para>
+<!-- .LP -->
+Also, when the application focus moves out of a text entry area, the
+application should unset the focus for the associated input context
+by calling
+<function>XUnsetICFocus</function>.
+As an optimization, if
+<function>XSetICFocus</function>
+is called successively on two different input contexts,
+setting the focus on the second
+will automatically unset the focus on the first.
+</para>
+<para>
+<!-- .LP -->
+To set and unset the input context focus correctly,
+it is necessary to track application-level focus changes.
+Such focus changes do not necessarily correspond to X server focus changes.
+</para>
+<para>
+<!-- .LP -->
+If a single input context
+is being used to do input for
+multiple text entry areas, it will also be necessary
+to set the focus window of the
+input context whenever the focus window changes
+(see section 13.5.6.3).
+</para>
+</sect3>
+<sect3 id="Geometry_Management">
+<title>Geometry Management</title>
+<!-- .XS -->
+<!-- (SN Geometry Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In most input method architectures
+(on-the-spot being the notable exception),
+the input method will perform the display of its own data.
+To provide better visual locality,
+it is often desirable to have the input method areas embedded within a client.
+To do this,
+the client may need to allocate space for an input method.
+Xlib provides support that allows the size and position of input method
+areas to be provided by a client.
+The input method areas that are supported for geometry management
+are the status area and the preedit area.
+</para>
+<para>
+<!-- .LP -->
+The fundamental concept on which geometry management for input method windows
+is based is the proper division of responsibilities between the
+client (or toolkit) and the input method.
+The division of responsibilities is as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The client is responsible for the geometry of the input method window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The input method is responsible for the contents of the input method window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+An input method is able to suggest a size to the client,
+but it cannot suggest a placement.
+Also the input method can only suggest a size.
+It does not determine the size,
+and it must accept the size it is given.
+</para>
+<para>
+<!-- .LP -->
+Before a client provides geometry management for an input method,
+it must determine if geometry management is needed.
+The input method indicates the need for geometry management
+by setting
+<function>XIMPreeditArea</function>
+or
+<function>XIMStatusArea</function>
+in its
+<function>XIMStyles</function>
+value returned by
+<function>XGetIMValues</function>.
+When a client has decided that it will provide geometry management
+for an input method,
+it indicates that decision by setting the
+<function>XNInputStyle</function>
+value in the
+<function>XIC</function>.
+</para>
+<para>
+<!-- .LP -->
+After a client has established with the input method
+that it will do geometry management,
+the client must negotiate the geometry with the input method.
+The geometry is negotiated by the following steps:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The client suggests an area to the input method by setting the
+<function>XNAreaNeeded</function>
+value for that area.
+If the client has no constraints for the input method,
+it either will not suggest an area or will set the width and height to zero.
+Otherwise, it will set one of the values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client will get the <acronym>XIC</acronym> value
+<function>XNAreaNeeded</function>.
+The input method will return its suggested size in this value.
+The input method should pay attention to any constraints suggested
+by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client sets the <acronym>XIC</acronym> value
+<function>XNArea</function>
+to inform the input method of the geometry of its window.
+The client should try to honor the geometry requested by the input method.
+The input method must accept this geometry.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Clients doing geometry management must be aware that setting other
+<acronym>XIC</acronym> values may affect the geometry desired by an input method.
+For example,
+<function>XNFontSet</function>
+and
+<function>XNLineSpacing</function>
+may change the geometry desired by the input method.
+</para>
+<para>
+<!-- .LP -->
+The table of <acronym>XIC</acronym> values (see section 13.5.6)
+indicates the values that can cause the desired geometry to change
+when they are set.
+It is the responsibility of the client to renegotiate the geometry
+of the input method window when it is needed.
+</para>
+<para>
+<!-- .LP -->
+In addition,
+a geometry management callback is provided
+by which an input method can initiate a geometry change.
+</para>
+</sect3>
+<sect3 id="Event_Filtering">
+<title>Event Filtering</title>
+<!-- .XS -->
+<!-- (SN Event Filtering -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A filtering mechanism is provided to allow input methods
+to capture X events transparently to clients.
+It is expected that toolkits (or clients) using
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString </function>
+will call this filter at some point in the event processing mechanism
+to make sure that events needed by an input method can be filtered
+by that input method.
+</para>
+<para>
+<!-- .LP -->
+If there were no filter,
+a client could receive and discard events that are necessary
+for the proper functioning of an input method.
+The following provides a few examples of such events:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Expose events on preedit window in local mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Events may be used by an input method to communicate with an input server.
+Such input server protocol-related events have to be intercepted
+if one does not want to disturb client code.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Key events can be sent to a filter before they are bound
+to translations such as those the X Toolkit Intrinsics library provides.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Clients are expected to get the <acronym>XIC</acronym> value
+<function>XNFilterEvents</function>
+and augment the event mask for the client window with that event mask.
+This mask may be zero.
+</para>
+</sect3>
+<sect3 id="Callbacks">
+<title>Callbacks</title>
+<!-- .XS -->
+<!-- (SN Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When an on-the-spot input method is implemented,
+only the client can insert or delete preedit data in place
+and possibly scroll existing text.
+This means that the echo of the keystrokes has to be achieved
+by the client itself, tightly coupled with the input method logic.
+</para>
+<para>
+<!-- .LP -->
+When the user enters a keystroke,
+the client calls
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+At this point, in the on-the-spot case,
+the echo of the keystroke in the preedit has not yet been done.
+Before returning to the client logic that handles the input characters,
+the look-up function
+must call the echoing logic to insert the new keystroke.
+If the keystrokes entered so far make up a character,
+the keystrokes entered need to be deleted,
+and the composed character will be returned.
+Hence, what happens is that, while being called by client code,
+the input method logic has to call back to the client before it returns.
+The client code, that is, a callback procedure,
+is called from the input method logic.
+</para>
+<para>
+<!-- .LP -->
+There are a number of cases where the input method logic has to
+call back the client.
+Each of those cases is associated with a well-defined callback action.
+It is possible for the client to specify, for each input context,
+what callback is to be called for each action.
+</para>
+<para>
+<!-- .LP -->
+There are also callbacks provided for feedback of status information
+and a callback to initiate a geometry request for an input method.
+</para>
+</sect3>
+<sect3 id="Visible_Position_Feedback_Masks">
+<title>Visible Position Feedback Masks</title>
+<!-- .XS -->
+<!-- (SN Visible Position Feedback Masks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In the on-the-spot input style, there is a problem when
+attempting to draw preedit strings that are longer than the
+available space. Once the display area is exceeded, it is not
+clear how best to display the preedit string.
+The visible position feedback masks of
+<function>XIMText</function>
+help resolve this problem by allowing the input method to specify hints that
+indicate the essential portions of the preedit string.
+For example, such hints can help developers implement
+scrolling of a long preedit string within a short preedit display area.
+</para>
+</sect3>
+<sect3 id="Preedit_String_Management">
+<title>Preedit String Management</title>
+<!-- .XS -->
+<!-- (SN Preedit String Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+As highlighted before, the input method architecture provides
+preediting, which supports a type of preprocessor input composition.
+In this case, composition consists of interpreting a sequence
+of key events and returning a committed string via
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+This provides the basics for input methods.
+</para>
+<para>
+<!-- .LP -->
+In addition to preediting based on key events, a general framework
+is provided to give a client that desires it more advanced preediting based
+on the text within the client. This framework is called
+<emphasis remap='I'>string conversion</emphasis> and is provided using <acronym>XIC</acronym> values.
+The fundamental concept of string conversion
+is to allow the input method to manipulate the client's
+text independent of any user preediting operation.
+</para>
+<para>
+<!-- .LP -->
+The need for string conversion is based on
+language needs and input method capabilities.
+The following are some examples of string conversion:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Transliteration conversion provides language-specific conversions
+within the input method.
+In the case of Korean input, users wish to convert a Hangul string
+into a Hanja string while in preediting, after preediting,
+or in other situations (for example, on a selected string).
+The conversion is triggered when the user
+presses a Hangul-to-Hanja key sequence (which may be input method specific).
+Sometimes the user may want to invoke the conversion after finishing
+preediting or on a user-selected string.
+Thus, the string to be converted is in an application buffer, not in
+the preedit area of the input method. The string conversion services
+allow the client to request this transliteration conversion from the
+input method.
+There are many other transliteration conversions defined for
+various languages, for example, Kana-to-Kanji conversion in Japanese.
+<!-- .sp -->
+The key to remember is that transliteration conversions are triggered
+at the request of the user and returned to the client
+immediately without affecting the preedit area of the input method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Reconversion of a previously committed string or
+a selected string is supported by many input methods as a
+convenience to the user.
+For example, a user tends to mistype the commit key while
+preediting. In that case, some input methods provide a special
+key sequence to request a ``reconvert'' operation on the
+committed string, similiar to the undo facility provided by most
+text editors.
+Another example is where the user is proofreading a document
+that has some misconversions from preediting and wants to correct
+the misconverted text. Such reconversion is again triggered
+by the user invoking some special action, but reconversions should
+not affect the state of the preedit area.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Context-sensitive conversion is required for some languages
+and input methods that need to retrieve text that surrounds the
+current spot location (cursor position) of the client's buffer.
+Such text is needed when the preediting operation depends on
+some surrounding characters (usually preceding the spot location).
+For example,
+in Thai language input, certain character sequences may be invalid and
+the input method may want to check whether characters constitute a
+valid word. Input methods that do such context-dependent
+checking need to retrieve the characters surrounding the current
+cursor position to obtain complete words.
+<!-- .sp -->
+Unlike other conversions, this conversion is not explicitly
+requested by the user.
+Input methods that provide such context-sensitive conversion
+continuously need to request context from the client, and any change
+in the context of the spot location may affect such conversions.
+The client's context would be needed if the user moves the cursor
+and starts editing again.
+<!-- .sp -->
+For this reason, an input method supporting this type of conversion
+should take notice of when the client calls
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>,
+which is usually an indication of a context change.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Context-sensitive conversions just need a copy of the client's text,
+while other conversions replace the client's text with new text
+to achieve the reconversion or transliteration. Yet in all
+cases the result of a conversion, either immediately or via preediting,
+is returned by the
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+functions.
+</para>
+<para>
+<!-- .LP -->
+String conversion support is dependent on the availability of the
+<function>XNStringConversion</function>
+or
+<function>XNStringConversionCallback </function>
+<acronym>XIC</acronym> values.
+Because the input method may not support string conversions,
+clients have to query the availability of string conversion
+operations by checking the supported <acronym>XIC</acronym> values list by calling
+<function>XGetIMValues</function>
+with the
+<function>XNQueryICValuesList</function>
+IM value.
+</para>
+<para>
+<!-- .LP -->
+The difference between these two values is whether the
+conversion is invoked by the client or the input method.
+The
+<function>XNStringConversion</function>
+<acronym>XIC</acronym> value is used by clients to request
+a string conversion from the input method. The client
+is responsible for determining which events are used
+to trigger the string conversion and whether the string to be
+converted should be copied or deleted. The type of conversion
+is determined by the input method; the client can only
+pass the string to be converted. The client is guaranteed that
+no
+<function>XNStringConversionCallback</function>
+will be issued when this value is set; thus, the client need
+only set one of these values.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XNStringConversionCallback</function>
+<acronym>XIC</acronym> value is used by the client to notify the input method that
+it will accept requests from the input method for string conversion.
+If this value is set,
+it is the input method's responsibility to determine which
+events are used to trigger the string conversion.
+When such events occur, the input method issues a call to the
+client-supplied procedure to retrieve the string to be converted. The client's
+callback procedure is notified whether to copy or delete the string and
+is provided with hints as to the amount of text needed.
+The
+<function>XIMStringConversionCallbackStruct</function>
+specifies which text should be passed back to the input method.
+</para>
+<para>
+<!-- .LP -->
+Finally, the input method may call the client's
+<function>XNStringConversionCallback</function>
+procedure multiple times if the string returned from the callback is
+not sufficient to perform a successful conversion. The arguments
+to the client's procedure allow the input method to define a
+position (in character units) relative to the client's cursor position
+and the size of the text needed. By varying the position and size of
+the desired text in subsequent callbacks, the input method can retrieve
+additional text.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Input_Method_Management">
+<title>Input Method Management</title>
+<!-- .XS -->
+<!-- (SN Input Method Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The interface to input methods might appear to be simply creating
+an input method
+(<function>XOpenIM</function>)
+and freeing an input method
+(<function>XCloseIM</function>).
+However, input methods may
+require complex communication with input method servers (IM servers),
+for example:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+If the X server, IM server, and X clients are started asynchronously,
+some clients may attempt to connect to the IM server before it is
+fully operational, and fail.
+Therefore, some mechanism is needed to allow clients to detect when an IM
+server has started.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+It is up to clients to decide what should be done when an IM server is
+not available (for example, wait, or use some other IM server).
+</para>
+<para>
+<!-- .LP -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Some input methods may allow the underlying IM server to be switched.
+Such customization may be desired without restarting the entire client.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To support management of input methods in these cases, the following
+functions are provided:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XRegisterIMInstantiateCallback</function></entry>
+ <entry>This function allows clients to register a callback procedure
+ to be called when Xlib detects that an IM server is up and available.</entry>
+ </row>
+ <row>
+ <entry><function>XOpenIM</function></entry>
+ <entry>A client calls this function as a result of the callback procedure
+ being called.</entry>
+ </row>
+ <row>
+ <entry><function>XSetIMValue</function>, <function>XSetICValue</function></entry>
+ <entry>These functions use the <acronym>XIM</acronym> and <acronym>XIC</acronym> values,
+ <function>XNDestroyCallback</function>,
+ to allow a client
+ to register a callback procedure to be called when Xlib detects that
+ an IM server that was associated with an opened
+ input method is no longer available.
+ In addition, this function can be used to switch IM servers for those input
+ methods that support such functionality. The IM value for switching IM
+ servers is implementation-dependent; see the description below about
+ switching IM servers.</entry>
+ </row>
+ <row>
+ <entry><function>XUnregisterIMInstantiateCallback</function></entry>
+ <entry>This function removes a callback procedure registered by the client.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Input methods that support switching of IM servers may exhibit some
+side-effects:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The input method will ensure that any new IM server supports any of the
+input styles being used by input contexts already associated with the
+input method.
+However, the list of supported input styles may be different.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Geometry management requests on previously created input contexts
+may be initiated by the new IM server.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Hot_Keys">
+<title>Hot Keys</title>
+<!-- .XS -->
+<!-- (SN Hot Keys -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some clients need to guarantee which keys can be used to escape from the
+input method, regardless of the input method state;
+for example, the client-specific Help key or the keys to move the
+input focus.
+The HotKey mechanism allows clients
+to specify a set of keys for this purpose. However, the input
+method might not allow clients to specify hot keys.
+Therefore, clients have to query support of hot keys by checking the
+supported <acronym>XIC</acronym> values list by calling
+<function>XGetIMValues</function>
+with the
+<function>XNQueryICValuesList</function>
+IM value.
+When the hot keys specified conflict with the key bindings of the
+input method, hot keys take precedence over the key bindings of the input
+method.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Preedit_State_Operation">
+<title>Preedit State Operation</title>
+<!-- .XS -->
+<!-- (SN Preedit State Operation -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input method may have several internal states, depending on its
+implementation and the locale. However, one state that is
+independent of locale and implementation is whether the input method
+is currently performing a preediting operation.
+Xlib provides the ability for an application to manage the preedit state
+programmatically. Two methods are provided for
+retrieving the preedit state of an input context.
+One method is to query the state by calling
+<function>XGetICValues</function>
+with the
+<function>XNPreeditState</function>
+<acronym>XIC</acronym> value.
+Another method is to receive notification whenever
+the preedit state is changed. To receive such notification,
+an application needs to register a callback by calling
+<function>XSetICValues</function>
+with the
+<function>XNPreeditStateNotifyCallback</function>
+<acronym>XIC</acronym> value.
+In order to change the preedit state programmatically, an application
+needs to call
+<function>XSetICValues</function>
+with
+<function>XNPreeditState</function>.
+</para>
+<para>
+<!-- .LP -->
+Availability of the preedit state is input method dependent. The input
+method may not provide the ability to set the state or to
+retrieve the state programmatically. Therefore, clients have to
+query availability of preedit state operations by checking the
+supported <acronym>XIC</acronym> values list by calling
+<function>XGetIMValues</function>
+with the
+<function>XNQueryICValuesList</function>
+IM value.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Input_Method_Functions">
+<title>Input Method Functions</title>
+<!-- .XS -->
+<!-- (SN Input Method Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open a connection, use
+<function>XOpenIM</function>.
+<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XIM<function> XOpenIM</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+ <paramdef>char<parameter> *res_name</parameter></paramdef>
+ <paramdef>char<parameter> *res_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full resource name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XOpenIM</function>
+function opens an input method,
+matching the current locale and modifiers specification.
+Current locale and modifiers are bound to the input method at opening time.
+The locale associated with an input method cannot be changed dynamically.
+This implies that the strings returned by
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>,
+for any input context affiliated with a given input method,
+will be encoded in the locale current at the time the input method is opened.
+</para>
+<para>
+<!-- .LP -->
+The specific input method to which this call will be routed
+is identified on the basis of the current locale.
+<function>XOpenIM</function>
+will identify a default input method corresponding to the
+current locale.
+That default can be modified using
+<function>XSetLocaleModifiers</function>
+for the input method modifier.
+</para>
+<para>
+<!-- .LP -->
+The db argument is the resource database to be used by the input method
+for looking up resources that are private to the input method.
+It is not intended that this database be used to look
+up values that can be set as IC values in an input context.
+If db is NULL,
+no database is passed to the input method.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments specify the resource name
+and class of the application.
+They are intended to be used as prefixes by the input method
+when looking up resources that are common to all input contexts
+that may be created for this input method.
+The characters used for resource names and classes must be in the
+X Portable Character Set.
+The resources looked up are not fully specified
+if res_name or res_class is NULL.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments are not assumed to exist beyond
+the call to
+<function>XOpenIM</function>.
+The specified resource database is assumed to exist for the lifetime
+of the input method.
+</para>
+<para>
+<!-- .LP -->
+<function>XOpenIM</function>
+returns NULL if no input method could be opened.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To close a connection, use
+<function>XCloseIM</function>.
+<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XCloseIM</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseIM</function>
+function closes the specified input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set input method attributes, use
+<function>XSetIMValues</function>.
+<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+<!-- .ds Al \ to set <acronym>XIM</acronym> values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable-length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIMValues</function>
+function presents a variable argument list programming interface
+for setting attributes of the specified input method.
+It returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be set.
+Xlib does not attempt to set arguments from the supplied list that
+follow the failed argument;
+all arguments in the list preceding the failed argument have been set
+correctly.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query an input method, use
+<function>XGetIMValues</function>.
+<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+<!-- .ds Al \ to get XIM values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIMValues</function>
+function presents a variable argument list programming interface
+for querying properties or features of the specified input method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+</para>
+<para>
+<!-- .LP -->
+Each <acronym>XIM</acronym> value argument (following a name) must point to
+a location where the <acronym>XIM</acronym> value is to be stored.
+That is, if the <acronym>XIM</acronym> value is of type T,
+the argument must be of type T*.
+If T itself is a pointer type,
+then
+<function>XGetIMValues</function>
+allocates memory to store the actual data,
+and the client is responsible for freeing this data by calling
+<function>XFree</function>
+with the returned pointer.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the display associated with an input method, use
+<function>XDisplayOfIM</function>.
+<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display<function> *</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayOfIM</function>
+function returns the display associated with the specified input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the locale associated with an input method, use
+<function>XLocaleOfIM</function>.
+<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLocaleOfIM</function>
+function returns the locale associated with the specified input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To register an input method instantiate callback, use
+<function>XRegisterIMInstantiateCallback</function>.
+<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XRegisterIMInstantiateCallback</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+ <paramdef>char<parameter> *res_name</parameter></paramdef>
+ <paramdef>char<parameter> *res_class</parameter></paramdef>
+ <paramdef>XIMProc<parameter> callback</parameter></paramdef>
+ <paramdef>XPointer<parameter> *client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full resource name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the input method instantiate callback.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRegisterIMInstantiateCallback</function>
+function registers a callback to be invoked whenever a new input method
+becomes available for the specified display that matches the current
+locale and modifiers.
+</para>
+<para>
+<!-- .LP -->
+The function returns
+<function>True</function>
+ if it succeeds; otherwise, it returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> IMInstantiateCallback</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To unregister an input method instantiation callback, use
+<function>XUnregisterIMInstantiateCallback</function>.
+<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XUnregisterIMInstantiateCallback</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+ <paramdef>char<parameter> *res_name</parameter></paramdef>
+ <paramdef>char<parameter> *res_class</parameter></paramdef>
+ <paramdef>XIMProc<parameter> callback</parameter></paramdef>
+ <paramdef>XPointer<parameter> *client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full resource name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>res_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the full class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the input method instantiate callback.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnregisterIMInstantiateCallback</function>
+function removes an input method instantiation callback previously
+registered.
+The function returns
+<function>True</function>
+if it succeeds; otherwise, it returns
+<function>False</function>.
+</para>
+</sect2>
+<sect2 id="Input_Method_Values">
+<title>Input Method Values</title>
+<!-- .XS -->
+<!-- (SN Input Method Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following table describes how <acronym>XIM</acronym> values are interpreted
+by an input method.
+The first column lists the <acronym>XIM</acronym> values.
+The second column indicates how each of the <acronym>XIM</acronym> values
+are treated by that input style.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The following keys apply to this table.
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Explanation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>D</entry>
+ <entry>This value may be set using
+ <function>XSetIMValues</function>.
+ If it is not set,
+ a default is provided.</entry>
+ </row>
+ <row>
+ <entry>S</entry>
+ <entry>This value may be set using <function>XSetIMValues</function>.</entry>
+ </row>
+ <row>
+ <entry>G</entry>
+ <entry>This value may be read using <function>XGetIMValues</function>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry><acronym>XIM</acronym> Value</entry>
+ <entry>Key</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XNQueryInputStyle</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNResourceName</function></entry>
+ <entry>D-S-G</entry>
+ </row>
+ <row>
+ <entry><function>XNResourceClass</function></entry>
+ <entry>D-S-G</entry>
+ </row>
+ <row>
+ <entry><function>XNDestroyCallback</function></entry>
+ <entry>D-S-G</entry>
+ </row>
+ <row>
+ <entry><function>XNQueryIMValuesList</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNQueryICValuesList</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNVisiblePosition</function></entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>XNR6PreeditCallbackBehavior</function></entry>
+ <entry>D-S-G</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+<function>XNR6PreeditCallbackBehavior</function>
+is obsolete and its use is not recommended (see section 13.5.4.6).
+</para>
+
+<sect3 id="Query_Input_Style">
+<title>Query Input Style</title>
+<!-- .XS -->
+<!-- (SN Query Input Style -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A client should always query the input method to determine which input
+styles are supported.
+The client should then find an input style it is capable of supporting.
+</para>
+<para>
+<!-- .LP -->
+If the client cannot find an input style that it can support,
+it should negotiate with the user the continuation of the program
+(exit, choose another input method, and so on).
+</para>
+<para>
+<!-- .LP -->
+The argument value must be a pointer to a location
+where the returned value will be stored.
+The returned value is a pointer to a structure of type
+<function>XIMStyles</function>.
+Clients are responsible for freeing the
+<function>XIMStyles</function>
+structure.
+To do so, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMStyles</function>
+structure is defined as follows:
+</para>
+
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMStyle</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStyles</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef unsigned long XIMStyle;
+
+
+#define XIMPreeditArea 0x0001L
+#define XIMPreeditCallbacks 0x0002L
+#define XIMPreeditPosition 0x0004L
+#define XIMPreeditNothing 0x0008L
+#define XIMPreeditNone 0x0010L
+
+#define XIMStatusArea 0x0100L
+#define XIMStatusCallbacks 0x0200L
+#define XIMStatusNothing 0x0400L
+#define XIMStatusNone 0x0800L
+
+typedef struct {
+ unsigned short count_styles;
+ XIMStyle * supported_styles;
+} XIMStyles;
+
+</literallayout>
+
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+An
+<function>XIMStyles</function>
+structure contains the number of input styles supported
+in its count_styles field.
+This is also the size of the supported_styles array.
+</para>
+<para>
+<!-- .LP -->
+The supported styles is a list of bitmask combinations,
+which indicate the combination of styles for each of the areas supported.
+These areas are described later.
+Each element in the list should select one of the bitmask values for
+each area.
+The list describes the complete set of combinations supported.
+Only these combinations are supported by the input method.
+</para>
+<para>
+<!-- .LP -->
+The preedit category defines what type of support is provided
+by the input method for preedit information.
+</para>
+<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XIMPreeditArea </function></entry>
+ <entry>If chosen,
+ the input method would require the client to provide some area values
+ for it to do its preediting.
+ Refer to <acronym>XIC</acronym> values
+ <function>XNArea</function>
+ and
+ <function>XNAreaNeeded</function>.</entry>
+ </row>
+ <row>
+ <entry><function>XIMPreeditPosition</function></entry>
+ <entry>If chosen,
+ the input method would require the client to provide positional values.
+ Refer to <acronym>XIC</acronym> values
+ <function>XNSpotLocation</function>
+ and
+ <function>XNFocusWindow</function>.</entry>
+ </row>
+ <row>
+ <entry><function>XIMPreeditCallbacks</function></entry>
+ <entry>If chosen,
+ the input method would require the client to define the set of preedit callbacks.
+ Refer to <acronym>XIC</acronym> values
+ <function>XNPreeditStartCallback</function>,
+ <function>XNPreeditDoneCallback</function>,
+ <function>XNPreeditDrawCallback</function>,
+ and
+ <function>XNPreeditCaretCallback</function>.</entry>
+ </row>
+ <row>
+ <entry><function>XIMPreeditNothing</function></entry>
+ <entry>If chosen, the input method can function without any preedit values.</entry>
+ </row>
+ <row>
+ <entry><function>XIMPreeditNone</function></entry>
+ <entry>The input method does not provide any preedit feedback.
+ Any preedit value is ignored.
+ This style is mutually exclusive with the other preedit styles.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+The status category defines what type of support is provided
+by the input method for status information.
+</para>
+<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XIMStatusArea</function></entry>
+ <entry>The input method requires the client to provide
+ some area values for it to do its status feedback.
+ See
+ <function>XNArea</function>
+ and
+ <function>XNAreaNeeded</function>.</entry>
+ </row>
+ <row>
+ <entry><function>XIMStatusCallbacks</function></entry>
+ <entry>The input method requires the client to define the set of status callbacks,
+ <function>XNStatusStartCallback</function>,
+ <function>XNStatusDoneCallback</function>,
+ and
+ <function>XNStatusDrawCallback</function>.</entry>
+ </row>
+ <row>
+ <entry><function>XIMStatusNothing</function></entry>
+ <entry>The input method can function without any status values.</entry>
+ </row>
+ <row>
+ <entry><function>XIMStatusNone</function></entry>
+ <entry>The input method does not provide any status feedback.
+ If chosen, any status value is ignored.
+ This style is mutually exclusive with the other status styles.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect3>
+<sect3 id="Resource_Name_and_Class_c">
+<title>Resource Name and Class</title>
+<!-- .XS -->
+<!-- (SN Resource Name and Class -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNResourceName</function>
+and
+<function>XNResourceClass</function>
+arguments are strings that specify the full name and class
+used by the input method.
+These values should be used as prefixes for the name and class
+when looking up resources that may vary according to the input method.
+If these values are not set,
+the resources will not be fully specified.
+</para>
+<para>
+<!-- .LP -->
+It is not intended that values that can be set as <acronym>XIM</acronym> values be
+set as resources.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Destroy_Callback">
+<title>Destroy Callback</title>
+<!-- .XS -->
+<!-- (SN Destroy Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNDestroyCallback </function>
+argument is a pointer to a structure of type
+<function>XIMCallback</function>.
+<function>XNDestroyCallback</function>
+is triggered when an input method stops its service for any reason.
+After the callback is invoked, the input method is closed and the
+associated input context(s) are destroyed by Xlib.
+Therefore, the client should not call
+<function>XCloseIM</function>
+or
+<function>XDestroyIC</function>.
+</para>
+<para>
+<!-- .LP -->
+The generic prototype of this callback function is as follows:
+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> DestroyCallback</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+A DestroyCallback is always called with a NULL call_data argument.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Query_IM_IC_Values_List">
+<title>Query IM/IC Values List</title>
+<!-- .XS -->
+<!-- (SN Query IM/IC Values List -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<function>XNQueryIMValuesList</function>
+and
+<function>XNQueryICValuesList</function>
+are used to query about <acronym>XIM</acronym> and <acronym>XIC</acronym> values supported by the input method.
+</para>
+<para>
+<!-- .LP -->
+The argument value must be a pointer to a location where the returned
+value will be stored. The returned value is a pointer to a structure
+of type
+<function>XIMValuesList</function>.
+Clients are responsible for freeing the
+<function>XIMValuesList</function>
+structure.
+To do so, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMValuesList</function>
+structure is defined as follows:
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ unsigned short count_values;
+ char **supported_values;
+} XIMValuesList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect3>
+<sect3 id="Visible_Position">
+<title>Visible Position</title>
+<!-- .XS -->
+<!-- (SN Visible Position -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNVisiblePosition</function>
+argument indicates whether the visible position masks of
+<function>XIMFeedback</function>
+in
+<function>XIMText</function>
+are available.
+</para>
+<para>
+<!-- .LP -->
+The argument value must be a pointer to a location where the returned
+value will be stored. The returned value is of type
+<function>Bool</function>.
+If the returned value is
+<function>True</function>,
+the input method uses the visible position masks of
+<function>XIMFeedback</function>
+in
+<function>XIMText</function>;
+otherwise, the input method does not use the masks.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIM</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryIMValues</function>
+before using this argument.
+If the
+<function>XNVisiblePosition</function>
+does not exist in the IM values list returned from
+<function>XNQueryIMValues</function>,
+the visible position masks of
+<function>XIMFeedback</function>
+in
+<function>XIMText</function>
+are not used to indicate the visible position.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Preedit_Callback_Behavior">
+<title>Preedit Callback Behavior</title>
+<!-- .XS -->
+<!-- (SN Preedit Callback Behavior -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNR6PreeditCallbackBehavior</function>
+argument originally included in the X11R6 specification has been
+deprecated.\(dg
+<!-- .\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -->
+<!-- .\" should be changed from *Bool to Bool. -->
+<!-- .FS \(dg -->
+During formulation of the X11R6 specification, the behavior of
+the R6 PreeditDrawCallbacks was going to differ significantly from
+that of the R5 callbacks.
+Late changes to the specification converged the R5 and R6 behaviors,
+eliminating the need for
+<function>XNR6PreeditCallbackBehavior</function>.
+Unfortunately, this argument was not removed from the R6 specification
+before it was published.
+<!-- .FE -->
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XNR6PreeditCallbackBehavior</function>
+argument indicates whether the behavior of preedit callbacks regarding
+<function>XIMPreeditDrawCallbackStruct</function>
+values follows Release 5 or Release 6 semantics.
+</para>
+<para>
+<!-- .LP -->
+The value is of type
+<function>Bool</function>.
+When querying for
+<function>XNR6PreeditCallbackBehavior</function>,
+if the returned value is
+<function>True</function>,
+the input method uses the Release 6 behavior;
+otherwise, it uses the Release 5 behavior.
+The default value is
+<function>False</function>.
+In order to use Release 6 semantics, the value of
+<function>XNR6PreeditCallbackBehavior</function>
+must be set to
+<function>True</function>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIM</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryIMValues</function>
+before using this argument.
+If the
+<function>XNR6PreeditCallbackBehavior</function>
+does not exist in the IM values list returned from
+<function>XNQueryIMValues</function>,
+the PreeditCallback behavior is Release 5 semantics.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Input_Context_Functions">
+<title>Input Context Functions</title>
+<!-- .XS -->
+<!-- (SN Input Context Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input context is an abstraction that is used to contain both the data
+required (if any) by an input method and the information required
+to display that data.
+There may be multiple input contexts for one input method.
+The programming interfaces for creating, reading, or modifying
+an input context use a variable argument list.
+The name elements of the argument lists are referred to as <acronym>XIC</acronym> values.
+It is intended that input methods be controlled by these <acronym>XIC</acronym> values.
+As new <acronym>XIC</acronym> values are created,
+they should be registered with the X Consortium.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an input context, use
+<function>XCreateIC</function>.
+<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XIC<function> XCreateIC</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateIC </function>
+function creates a context within the specified input method.
+</para>
+<para>
+<!-- .LP -->
+Some of the arguments are mandatory at creation time, and
+the input context will not be created if those arguments are not provided.
+The mandatory arguments are the input style and the set of text callbacks
+(if the input style selected requires callbacks).
+All other input context values can be set later.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateIC</function>
+returns a NULL value if no input context could be created.
+A NULL value could be returned for any of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A required argument was not set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A read-only argument was set (for example,
+<function>XNFilterEvents</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The argument name is not recognized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The input method encountered an input method implementation-dependent error.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XCreateIC</function>
+can generate
+<function>BadAtom</function>,
+<function>BadColor</function>,
+<function>BadPixmap</function>,
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an input context, use
+<function>XDestroyIC</function>.
+<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XDestroyIC</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XDestroyIC</function>
+destroys the specified input context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To communicate to and synchronize with input method
+for any changes in keyboard focus from the client side,
+use
+<function>XSetICFocus</function>
+and
+<function>XUnsetICFocus</function>.
+<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetICFocus</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetICFocus</function>
+function allows a client to notify an input method that the focus window
+attached to the specified input context has received keyboard focus.
+The input method should take action to provide appropriate feedback.
+Complete feedback specification is a matter of user interface policy.
+</para>
+<para>
+<!-- .LP -->
+Calling
+<function>XSetICFocus</function>
+does not affect the focus window value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XUnsetICFocus</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnsetICFocus</function>
+function allows a client to notify an input method that the specified input context
+has lost the keyboard focus and that no more input is expected on the focus window
+attached to that input context.
+The input method should take action to provide appropriate feedback.
+Complete feedback specification is a matter of user interface policy.
+</para>
+<para>
+<!-- .LP -->
+Calling
+<function>XUnsetICFocus</function>
+does not affect the focus window value;
+the client may still receive
+events from the input method that are directed to the focus window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To reset the state of an input context to its initial state, use
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>.
+<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>wchar_t<function> *</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When
+<function>XNResetState</function>
+is set to
+<function>XIMInitialState</function>,
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>
+reset an input context to its initial state;
+when
+<function>XNResetState</function>
+is set to
+<function>XIMPreserveState</function>,
+the current input context state is preserved.
+In both cases, any input pending on that context is deleted.
+The input method is required to clear the preedit area, if any,
+and update the status accordingly.
+Calling
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>
+does not change the focus.
+</para>
+<para>
+<!-- .LP -->
+The return value of
+<function>XmbResetIC</function>
+is its current preedit string as a multibyte string.
+If there is any preedit text drawn or visible to the user,
+then these procedures must return a non-NULL string.
+If there is no visible preedit text,
+then it is input method implementation-dependent
+whether these procedures return a non-NULL string or NULL.
+</para>
+<para>
+<!-- .LP -->
+The client should free the returned string by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the input method associated with an input context, use
+<function>XIMOfIC</function>.
+<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XIM<function> XIMOfIC</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIMOfIC</function>
+function returns the input method associated with the specified input context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Xlib provides two functions for setting and reading <acronym>XIC</acronym> values, respectively,
+<function>XSetICValues</function>
+and
+<function>XGetICValues</function>.
+Both functions have a variable-length argument list.
+In that argument list, any <acronym>XIC</acronym> value's name must be denoted
+with a character string using the X Portable Character Set.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set <acronym>XIC</acronym> values, use
+<function>XSetICValues</function>.
+<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetICValues</function>
+function returns NULL if no error occurred;
+otherwise,
+it returns the name of the first argument that could not be set.
+An argument might not be set for any of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The argument is read-only (for example,
+<function>XNFilterEvents</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The argument name is not recognized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An implementation-dependent error occurs.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each value to be set must be an appropriate datum,
+matching the data type imposed by the semantics of the argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetICValues</function>
+can generate
+<function>BadAtom</function>,
+<function>BadColor</function>,
+<function>BadCursor</function>,
+<function>BadPixmap</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain <acronym>XIC</acronym> values, use
+<function>XGetICValues</function>.
+<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+<!-- .ds Al \ to get XIC values -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable length argument list(Al.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetICValues</function>
+function returns NULL if no error occurred; otherwise,
+it returns the name of the first argument that could not be obtained.
+An argument could not be obtained for any of the following reasons:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The argument name is not recognized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The input method encountered an implementation-dependent error.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each IC attribute value argument (following a name) must point to
+a location where the IC value is to be stored.
+That is, if the IC value is of type T,
+the argument must be of type T*.
+If T itself is a pointer type,
+then
+<function>XGetICValues</function>
+allocates memory to store the actual data,
+and the client is responsible for freeing this data by calling
+<function>XFree</function>
+with the returned pointer.
+The exception to this rule is for an IC value of type
+<function>XVaNestedList</function>
+(for preedit and status attributes).
+In this case, the argument must also be of type
+<function>XVaNestedList</function>.
+Then, the rule of changing type T to T* and freeing the allocated data
+applies to each element of the nested list.
+</para>
+</sect2>
+<sect2 id="Input_Context_Values">
+<title>Input Context Values</title>
+<!-- .XS -->
+<!-- (SN Input Context Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following tables describe how <acronym>XIC</acronym> values are interpreted
+by an input method depending on the input style chosen by the
+user.
+</para>
+<para>
+<!-- .LP -->
+The first column lists the <acronym>XIC</acronym> values.
+The second column indicates which values are involved in affecting,
+negotiating, and setting the geometry of the input method windows.
+The subentries under the third column indicate the different
+input styles that are supported.
+Each of these columns indicates how each of the <acronym>XIC</acronym> values
+are treated by that input style.
+</para>
+<para>
+<!-- .LP -->
+The following keys apply to these tables.
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Explanation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>C</entry>
+ <entry>This value must be set with <function>XCreateIC</function>.</entry>
+ </row>
+ <row>
+ <entry>D</entry>
+ <entry>This value may be set using
+ <function>XCreateIC</function>.>
+ If it is not set,>
+ a default is provided.</entry>
+ </row>
+ <row>
+ <entry>G</entry>
+ <entry>This value may be read using
+ <function>XGetICValues</function>.</entry>
+ </row>
+ <row>
+ <entry>GN</entry>
+ <entry>This value may cause geometry negotiation when its value is set by means of
+ <function>XCreateIC</function>
+ or
+ <function>XSetICValues</function>.</entry>
+ </row>
+ <row>
+ <entry>GR</entry>
+ <entry>This value will be the response of the input method when any
+ GN value is changed.</entry>
+ </row>
+ <row>
+ <entry>GS</entry>
+ <entry>This value will cause the geometry of the input method window to be set.</entry>
+ </row>
+ <row>
+ <entry>O</entry>
+ <entry>This value must be set once and only once.
+ It need not be set at create time.</entry>
+ </row>
+ <row>
+ <entry>S</entry>
+ <entry>This value may be set with
+ <function>XSetICValues</function>.</entry>
+ </row>
+ <row>
+ <entry>Ignored</entry>
+ <entry>This value is ignored by the input method for the given input style.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='7' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <colspec colname='c6'/>
+ <colspec colname='c7'/>
+ <tbody>
+ <row>
+ <entry><acronym>XIC</acronym> Value</entry>
+ <entry>Geometry Mangement</entry>
+ <entry>Preedit Callback</entry>
+ <entry>Preedit Position</entry>
+ <entry>Input Style Preedit Area</entry>
+ <entry>Preedit Nothing</entry>
+ <entry>Preedit None</entry>
+ </row>
+ <row>
+ <entry>Input Style</entry>
+ <entry></entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ </row>
+ <row>
+ <entry>Client Window</entry>
+ <entry></entry>
+ <entry>O-G</entry>
+ <entry>O-G</entry>
+ <entry>O-G</entry>
+ <entry>O-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Focus Window</entry>
+ <entry>GN</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Resource Name</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Resource Class</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Geometry Callback</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Filter Events</entry>
+ <entry></entry>
+ <entry>G</entry>
+ <entry>G</entry>
+ <entry>G</entry>
+ <entry>G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Destroy Callback</entry>
+ <entry></entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ </row>
+ <row>
+ <entry>String Conversion Callback</entry>
+ <entry></entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ </row>
+ <row>
+ <entry>String Conversion</entry>
+ <entry></entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ </row>
+ <row>
+ <entry>Reset State</entry>
+ <entry></entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>HotKey</entry>
+ <entry></entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>HotKeyState</entry>
+ <entry></entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry><function>Preedit</function></entry>
+ </row>
+ <row>
+ <entry>Area</entry>
+ <entry>GS</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Area Needed</entry>
+ <entry>GN-GR</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ <entry>S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Spot Location</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Foreground</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Background</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Background Pixmap</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Font Set</entry>
+ <entry>GN</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Line Spacing</entry>
+ <entry>GN</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Preedit State</entry>
+ <entry></entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Preedit State Notify Callback</entry>
+ <entry></entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Preedit Callbacks</entry>
+ <entry></entry>
+ <entry>C-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='6' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <colspec colname='c6'/>
+ <thead>
+ <row>
+ <entry><acronym>XIC</acronym> Value</entry>
+ <entry>Geomentry Management</entry>
+ <entry>Status Callback</entry>
+ <entry>Status Area</entry>
+ <entry>Status Nothing</entry>
+ <entry>Status None</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Input Style</entry>
+ <entry></entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ <entry>C-G</entry>
+ </row>
+ <row>
+ <entry>Client Window</entry>
+ <entry></entry>
+ <entry>O-G</entry>
+ <entry>O-G</entry>
+ <entry>O-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Focus Window</entry>
+ <entry>GN</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Resource Name</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Resource Class</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Geometry Callback</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Filter Events</entry>
+ <entry></entry>
+ <entry>G</entry>
+ <entry>G</entry>
+ <entry>G</entry>
+ <entry>G</entry>
+ </row>
+ <row>
+ <entry><function>Status</function></entry>
+ </row>
+ <row>
+ <entry>Area</entry>
+ <entry>GS</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Area Needed</entry>
+ <entry>GN-GR</entry>
+ <entry>Ignored</entry>
+ <entry>S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Foreground</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Background</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Background Pixmap</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Font Set</entry>
+ <entry>GN</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Line Spacing</entry>
+ <entry>GN</entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>Ignored</entry>
+ <entry>D-S-G</entry>
+ <entry>D-S-G</entry>
+ <entry>Ignored</entry>
+ </row>
+ <row>
+ <entry>Status Callbacks</entry>
+ <entry></entry>
+ <entry>C-S-G</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ <entry>Ignored</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<sect3 id="Input_Style">
+<title>Input Style</title>
+<!-- .XS -->
+<!-- (SN Input Style -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNInputStyle</function>
+argument specifies the input style to be used.
+The value of this argument must be one of the values returned by the
+<function>XGetIMValues</function>
+function with the
+<function>XNQueryInputStyle</function>
+argument specified in the supported_styles list.
+</para>
+<para>
+<!-- .LP -->
+Note that this argument must be set at creation time
+and cannot be changed.
+</para>
+</sect3>
+<sect3 id="Client_Window">
+<title>Client Window</title>
+<!-- .XS -->
+<!-- (SN Client Window -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNClientWindow</primary></indexterm>
+The
+<function>XNClientWindow</function>
+argument specifies to the input method the client window in
+which the input method
+can display data or create subwindows.
+Geometry values for input method areas are given with respect to the client
+window.
+Dynamic change of client window is not supported.
+This argument may be set only once and
+should be set before any input is done using this input context.
+If it is not set,
+the input method may not operate correctly.
+</para>
+<para>
+<!-- .LP -->
+If an attempt is made to set this value a second time with
+<function>XSetICValues</function>,
+the string
+<function>XNClientWindow</function>
+will be returned by
+<function>XSetICValues</function>,
+and the client window will not be changed.
+</para>
+<para>
+<!-- .LP -->
+If the client window is not a valid window ID on the display
+attached to the input method,
+a
+<function>BadWindow </function>
+error can be generated when this value is used by the input method.
+</para>
+</sect3>
+<sect3 id="Focus_Window">
+<title>Focus Window</title>
+<!-- .XS -->
+<!-- (SN Focus Window -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNFocusWindow</primary></indexterm>
+The
+<function>XNFocusWindow</function>
+argument specifies the focus window.
+The primary purpose of the
+<function>XNFocusWindow</function>
+is to identify the window that will receive the key event when input
+is composed.
+In addition, the input method may possibly affect the focus window
+as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Select events on it
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Send events to it
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Modify its properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Grab the keyboard within that window
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The associated value must be of type
+<function>Window</function>.
+If the focus window is not a valid window ID on the display
+attached to the input method,
+a
+<function>BadWindow</function>
+error can be generated when this value is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+When this <acronym>XIC</acronym> value is left unspecified,
+the input method will use the client window as the default focus window.
+</para>
+</sect3>
+<sect3 id="Resource_Name_and_Class_b">
+<title>Resource Name and Class</title>
+<!-- .XS -->
+<!-- (SN Resource Name and Class -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNResourceName</primary></indexterm>
+<indexterm significance="preferred"><primary>XNResourceClass</primary></indexterm>
+The
+<function>XNResourceName</function>
+and
+<function>XNResourceClass</function>
+arguments are strings that specify the full name and class
+used by the client to obtain resources for the client window.
+These values should be used as prefixes for name and class
+when looking up resources that may vary according to the input context.
+If these values are not set,
+the resources will not be fully specified.
+</para>
+<para>
+<!-- .LP -->
+It is not intended that values that can be set as <acronym>XIC</acronym> values be
+set as resources.
+</para>
+</sect3>
+<sect3 id="Geometry_Callback">
+<title>Geometry Callback</title>
+<!-- .XS -->
+<!-- (SN Geometry Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNGeometryCallback</primary></indexterm>
+The
+<function>XNGeometryCallback</function>
+argument is a structure of type
+<function>XIMCallback </function>
+(see section 13.5.6.13.12).
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XNGeometryCallback</function>
+argument specifies the geometry callback that a client can set.
+This callback is not required for correct operation of either
+an input method or a client.
+It can be set for a client whose user interface policy permits
+an input method to request the dynamic change of that input
+method's window.
+An input method that does dynamic change will need to filter any
+events that it uses to initiate the change.
+</para>
+</sect3>
+<sect3 id="Filter_Events">
+<title>Filter Events</title>
+<!-- .XS -->
+<!-- (SN Filter Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNFilterEvents</primary></indexterm>
+The
+<function>XNFilterEvents</function>
+argument returns the event mask that an input method needs
+to have selected for.
+The client is expected to augment its own event mask
+for the client window with this one.
+</para>
+<para>
+<!-- .LP -->
+This argument is read-only, is set by the input method at create time,
+and is never changed.
+</para>
+<para>
+<!-- .LP -->
+The type of this argument is
+<function>unsigned</function>
+<function>long</function>.
+Setting this value will cause an error.
+</para>
+</sect3>
+<sect3 id="Destroy_Callback_b">
+<title>Destroy Callback</title>
+<!-- .XS -->
+<!-- (SN Destroy Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNDestroyCallback </function>
+argument is a pointer to a structure of type
+<function>XIMCallback </function>
+(see section 13.5.6.13.12). This callback is triggered when the input method
+stops its service for any reason; for example, when a connection to an IM
+server is broken. After the destroy callback is called,
+the input context is destroyed and the input method is closed.
+Therefore, the client should not call
+<function>XDestroyIC</function>
+and
+<function>XCloseIM</function>.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="String_Conversion_Callback">
+<title>String Conversion Callback</title>
+<!-- .XS -->
+<!-- (SN String Conversion Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNStringConversionCallback</function>
+argument is a structure of type
+<function>XIMCallback </function>
+(see section 13.5.6.13.12).
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XNStringConversionCallback</function>
+argument specifies a string conversion callback. This callback
+is not required for correct operation of
+either the input method or the client. It can be set by a client
+to support string conversions that may be requested
+by the input method. An input method that does string conversions
+will filter any events that it uses to initiate the conversion.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryICValuesList</function>
+before using this argument.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="String_Conversion_">
+<title>String Conversion </title>
+<!-- .XS -->
+<!-- (SN String Conversion -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNStringConversion</function>
+argument is a structure of type
+<function>XIMStringConversionText</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XNStringConversion</function>
+argument specifies the string to be converted by an input method.
+This argument is not required for correct operation of either
+the input method or the client.
+</para>
+<para>
+<!-- .LP -->
+String conversion facilitates the manipulation of text independent
+of preediting.
+It is essential for some input methods and clients to manipulate
+text by performing context-sensitive conversion,
+reconversion, or transliteration conversion on it.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryICValuesList</function>
+before using this argument.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMStringConversionText</function>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+
+typedef struct _XIMStringConversionText {
+ unsigned short length;
+ XIMStringConversionFeedback *feedback;
+ Bool encoding_is_wchar;
+ union {
+ char *mbs;
+ wchar_t *wcs;
+ } string;
+} XIMStringConversionText;
+
+typedef unsigned long XIMStringConversionFeedback;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The feedback member is reserved for future use. The text to be
+converted is defined by the string and length members. The length
+is indicated in characters. To prevent the library from freeing memory
+pointed to by an uninitialized pointer, the client should set the feedback
+element to NULL.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Reset_State">
+<title>Reset State</title>
+<!-- .XS -->
+<!-- (SN Reset State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNResetState</function>
+argument specifies the state the input context will return to after calling
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>.
+</para>
+<para>
+<!-- .LP -->
+The <acronym>XIC</acronym> state may be set to its initial state, as specified by the
+<function>XNPreeditState</function>
+value when
+<function>XCreateIC</function>
+was called, or it may be set to preserve the current state.
+</para>
+<para>
+<!-- .LP -->
+The valid masks for
+<function>XIMResetState</function>
+are as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMInitialState</primary></indexterm>
+<indexterm significance="preferred"><primary>XINPreserveState</primary></indexterm>
+<!-- .sM -->
+</para>
+<literallayout class="monospaced">
+typedef unsigned long XIMResetState;
+
+#define XIMInitialState (1L)
+#define XIMPreserveState (1L<<1)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If
+<function>XIMInitialState</function>
+is set, then
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>
+will return to the initial
+<function>XNPreeditState</function>
+state of the <acronym>XIC</acronym>.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XIMPreserveState</function>
+is set, then
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>
+will preserve the current state of the <acronym>XIC</acronym>.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XNResetState</function>
+is left unspecified, the default is
+<function>XIMInitialState</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XIMResetState</function>
+values other than those specified above will default to
+<function>XIMInitialState</function>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryICValuesList</function>
+before using this argument.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Hot_Keys_b">
+<title>Hot Keys</title>
+<!-- .XS -->
+<!-- (SN Hot Keys -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNHotKey</function>
+argument specifies the hot key list to the <acronym>XIC</acronym>.
+The hot key list is a pointer to the structure of type
+<function>XIMHotKeyTriggers</function>,
+which specifies the key events that must be received
+without any interruption of the input method.
+For the hot key list set with this argument to be utilized, the client
+must also set
+<function>XNHotKeyState</function>
+to
+<function>XIMHotKeyStateON</function>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryICValuesList</function>
+before using this functionality.
+</para>
+<para>
+<!-- .LP -->
+The value of the argument is a pointer to a structure of type
+<function>XIMHotKeyTriggers</function>.
+</para>
+<para>
+<!-- .LP -->
+If an event for a key in the hot key list is found, then the process will
+receive the event and it will be processed inside the client.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ KeySym keysym;
+ unsigned int modifier;
+ unsigned int modifier_mask;
+} XIMHotKeyTrigger;
+
+typedef struct {
+ int num_hot_key;
+ XIMHotKeyTrigger *key;
+} XIMHotKeyTriggers;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+The combination of modifier and modifier_mask are used to represent one of
+three states for each modifier:
+either the modifier must be on, or the modifier must be off, or the modifier
+is a ``don't care'' - it may be on or off.
+When a modifier_mask bit is set to 0, the state of the associated modifier
+is ignored when evaluating whether the key is hot or not.
+</para>
+
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Modifier Bit</entry>
+ <entry>Mask Bit</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>1</entry>
+ <entry>The modifier must be off.</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>1</entry>
+ <entry>The modifier must be on.</entry>
+ </row>
+ <row>
+ <entry>n/a</entry>
+ <entry>0</entry>
+ <entry>Do not care if the modifier is on or off.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect3>
+<sect3 id="Hot_Key_State">
+<title>Hot Key State</title>
+<!-- .XS -->
+<!-- (SN Hot Key State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNHotKeyState</function>
+argument specifies the hot key state of the input method.
+This is usually used to switch the input method between hot key
+operation and normal input processing.
+</para>
+<para>
+<!-- .LP -->
+The value of the argument is a pointer to a structure of type
+XIMHotKeyState .
+</para>
+<literallayout class="monospaced">
+typedef unsigned long XIMHotKeyState;
+
+#define XIMHotKeyStateON (0x0001L)
+#define XIMHotKeyStateOFF (0x0002L)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+If not specified, the default is
+<function>XIMHotKeyStateOFF</function>.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Preedit_and_Status_Attributes">
+<title>Preedit and Status Attributes</title>
+<!-- .XS -->
+<!-- (SN Preedit and Status Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNPreeditAttributes</primary></indexterm>
+<indexterm significance="preferred"><primary>XNStatusAttributes</primary></indexterm>
+The
+<function>XNPreeditAttributes</function>
+and
+<function>XNStatusAttributes</function>
+arguments specify to an input method the attributes to be used for the
+preedit and status areas,
+if any.
+Those attributes are passed to
+<function>XSetICValues</function>
+or
+<function>XGetICValues</function>
+as a nested variable-length list.
+The names to be used in these lists are described in the following sections.
+</para>
+<sect4 id="Area">
+<title>Area</title>
+<!-- .XS -->
+<!-- (SN Area -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNArea</primary></indexterm>
+The value of the
+<function>XNArea</function>
+argument must be a pointer to a structure of type
+<function>XRectangle</function>.
+The interpretation of the
+<function>XNArea</function>
+argument is dependent on the input method style that has been set.
+</para>
+<para>
+<!-- .LP -->
+If the input method style is
+<function>XIMPreeditPosition</function>,
+<function>XNArea</function>
+specifies the clipping region within which preediting will take place.
+If the focus window has been set,
+the coordinates are assumed to be relative to the focus window.
+Otherwise, the coordinates are assumed to be relative to the client window.
+If neither has been set,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XNArea</function>
+is not specified, is set to NULL, or is invalid,
+the input method will default the clipping region
+to the geometry of the
+<function>XNFocusWindow</function>.
+If the area specified is NULL or invalid,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+If the input style is
+<function>XIMPreeditArea</function>
+or
+<function>XIMStatusArea</function>,
+<function>XNArea</function>
+specifies the geometry provided by the client to the input method.
+The input method may use this area to display its data,
+either preedit or status depending on the area designated.
+The input method may create a window as a child of the client window
+with dimensions that fit the
+<function>XNArea</function>.
+The coordinates are relative to the client window.
+If the client window has not been set yet,
+the input method should save these values
+and apply them when the client window is set.
+If
+<function>XNArea</function>
+is not specified, is set to NULL, or is invalid,
+the results are undefined.
+</para>
+</sect4>
+<sect4 id="Area_Needed">
+<title>Area Needed</title>
+<!-- .XS -->
+<!-- (SN Area Needed -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNAreaNeeded</primary></indexterm>
+When set, the
+<function>XNAreaNeeded</function>
+argument specifies the geometry suggested by the client for this area
+(preedit or status).
+The value associated with the argument must be a pointer to a
+structure of type
+<function>XRectangle</function>.
+Note that the x, y values are not used
+and that nonzero values for width or height are the constraints
+that the client wishes the input method to respect.
+</para>
+<para>
+<!-- .LP -->
+When read, the
+<function>XNAreaNeeded</function>
+argument specifies the preferred geometry desired by the input method
+for the area.
+</para>
+<para>
+<!-- .LP -->
+This argument is only valid if the input style is
+<function>XIMPreeditArea</function>
+or
+<function>XIMStatusArea</function>.
+It is used for geometry negotiation between the client and the input method
+and has no other effect on the input method
+(see section 13.5.1.5).
+</para>
+</sect4>
+<sect4 id="Spot_Location">
+<title>Spot Location</title>
+<!-- .XS -->
+<!-- (SN Spot Location -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNSpotLocation</primary></indexterm>
+The
+<function>XNSpotLocation</function>
+argument specifies to the input method the coordinates of the spot
+to be used by an input method executing with
+<function>XNInputStyle </function>
+set to
+<function>XIMPreeditPosition</function>.
+When specified to any input method other than
+<function>XIMPreeditPosition</function>,
+this <acronym>XIC</acronym> value is ignored.
+</para>
+<para>
+<!-- .LP -->
+The x coordinate specifies the position where the next character
+would be inserted.
+The y coordinate is the position of the baseline used
+by the current text line in the focus window.
+The x and y coordinates are relative to the focus window, if it has been set;
+otherwise, they are relative to the client window.
+If neither the focus window nor the client window has been set,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+The value of the argument is a pointer to a structure of type
+<function>XPoint</function>.
+</para>
+</sect4>
+<sect4 id="Colormap">
+<title>Colormap</title>
+<!-- .XS -->
+<!-- (SN Colormap -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Two different arguments can be used to indicate what colormap the input method
+should use to allocate colors, a colormap ID, or a standard colormap name.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNColormap</primary></indexterm>
+The
+<function>XNColormap</function>
+argument is used to specify a colormap ID.
+The argument value is of type
+<function>Colormap</function>.
+An invalid argument may generate a
+<function>BadColor</function>
+error when it is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNStdColormap</primary></indexterm>
+The
+<function>XNStdColormap</function>
+argument is used to indicate the name of the standard colormap
+in which the input method should allocate colors.
+The argument value is an
+<function>Atom</function>
+that should be a valid atom for calling
+<function>XGetRGBColormaps</function>.
+An invalid argument may generate a
+<function>BadAtom</function>
+error when it is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+If the colormap is left unspecified,
+the client window colormap becomes the default.
+</para>
+</sect4>
+<sect4 id="Foreground_and_Background">
+<title>Foreground and Background</title>
+<!-- .XS -->
+<!-- (SN Foreground and Background -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNForeground</primary></indexterm>
+<indexterm significance="preferred"><primary>XNBackground</primary></indexterm>
+The
+<function>XNForeground</function>
+and
+<function>XNBackground</function>
+arguments specify the foreground and background pixel, respectively.
+The argument value is of type
+<function>unsigned</function>
+<function>long</function>.
+It must be a valid pixel in the input method colormap.
+</para>
+<para>
+<!-- .LP -->
+If these values are left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Background_Pixmap">
+<title>Background Pixmap</title>
+<!-- .XS -->
+<!-- (SN Background Pixmap -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNBackgroundPixmap</function>
+argument specifies a background pixmap to be used as the background of the
+window.
+The value must be of type
+<function>Pixmap</function>.
+An invalid argument may generate a
+<function>BadPixmap</function>
+error when it is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Font_Set">
+<title>Font Set</title>
+<!-- .XS -->
+<!-- (SN Font Set -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNFontSet</primary></indexterm>
+The
+<function>XNFontSet</function>
+argument specifies to the input method what font set is to be used.
+The argument value is of type
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Line_Spacing">
+<title>Line Spacing</title>
+<!-- .XS -->
+<!-- (SN Line Spacing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNLineSpace</function>
+argument specifies to the input method what line spacing is to be used
+in the preedit window if more than one line is to be used.
+This argument is of type
+<function>int</function>.
+</para>
+<para>
+<!-- .LP -->
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Cursor">
+<title>Cursor</title>
+<!-- .XS -->
+<!-- (SN Cursor -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNCursor</primary></indexterm>
+The
+<function>XNCursor</function>
+argument specifies to the input method what cursor is to be used
+in the specified window.
+This argument is of type
+<function>Cursor</function>.
+</para>
+<para>
+<!-- .LP -->
+An invalid argument may generate a
+<function>BadCursor</function>
+error when it is used by the input method.
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Preedit_State">
+<title>Preedit State</title>
+<!-- .XS -->
+<!-- (SN Preedit State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XNPreeditState</function>
+argument specifies the state of input preediting for the input method.
+Input preediting can be on or off.
+</para>
+<para>
+<!-- .LP -->
+The valid mask names for
+<function>XNPreeditState</function>
+are as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMPreeditUnknown</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditEnable</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditDisable</primary></indexterm>
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef unsigned long XIMPreeditState;
+
+#define XIMPreeditUnknown 0L
+#define XIMPreeditEnable 1L
+#define XIMPreeditDisable (1L<<1)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If a value of
+<function>XIMPreeditEnable</function>
+is set, then input preediting is turned on by the input method.
+</para>
+<para>
+<!-- .LP -->
+If a value of
+<function>XIMPreeditDisable</function>
+is set, then input preediting is turned off by the input method.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XNPreeditState</function>
+is left unspecified, then the state will be implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+When
+<function>XNResetState</function>
+is set to
+<function>XIMInitialState</function>,
+the
+<function>XNPreeditState</function>
+value specified at the creation time will be reflected as the initial state for
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryICValuesList</function>
+before using this argument.
+</para>
+</sect4>
+<sect4 id="Preedit_State_Notify_Callback">
+<title>Preedit State Notify Callback</title>
+<!-- .XS -->
+<!-- (SN Preedit State Notify Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The preedit state notify callback is triggered by the input method
+when the preediting state has changed.
+The value of the
+<function>XNPreeditStateNotifyCallback</function>
+argument is a pointer to a structure of type
+<function>XIMCallback</function>.
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> PreeditStateNotifyCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the current preedit state.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIMPreeditStateNotifyCallbackStruct</function>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMPreeditStateNotifyCallbackStruct</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XIMPreeditStateNotifyCallbackStruct {
+ XIMPreeditState state;
+} XIMPreeditStateNotifyCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<function>XNQueryICValuesList</function>
+before using this argument.
+</para>
+</sect4>
+<sect4 id="Preedit_and_Status_Callbacks">
+<title>Preedit and Status Callbacks</title>
+<!-- .XS -->
+<!-- (SN Preedit and Status Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A client that wants to support the input style
+<function>XIMPreeditCallbacks</function>
+must provide a set of preedit callbacks to the input method.
+The set of preedit callbacks is as follows:
+</para>
+<indexterm significance="preferred"><primary>XNPreeditStartCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNPreeditDoneCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNPreeditDrawCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNPreeditCaretCallback</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XNPreeditStartCallback</function></entry>
+ <entry>This is called when the input method starts preedit.</entry>
+ </row>
+ <row>
+ <entry><function>XNPreeditDoneCallback</function></entry>
+ <entry>This is called when the input method stops preedit.</entry>
+ </row>
+ <row>
+ <entry><function>XNPreeditDrawCallback</function></entry>
+ <entry>This is called when a number of preedit keystrokes should be echoed.</entry>
+ </row>
+ <row>
+ <entry><function>XNPreeditCaretCallback</function></entry>
+ <entry>This is called to move the text insertion point within the preedit string.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+A client that wants to support the input style
+<function>XIMStatusCallbacks</function>
+must provide a set of status callbacks to the input method.
+The set of status callbacks is as follows:
+</para>
+
+<indexterm significance="preferred"><primary>XNStatusStartCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNStatusDoneCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNStatusDrawCallback</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XNStatusStartCallback</function></entry>
+ <entry>This is called when the input method initializes the status area.</entry>
+ </row>
+ <row>
+ <entry><function>XNStatusDoneCallback</function></entry>
+ <entry>This is called when the input method no longer needs the status area.</entry>
+ </row>
+ <row>
+ <entry><function>XNStatusDrawCallback</function></entry>
+ <entry>This is called when updating of the status area is required.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<para>
+<!-- .LP -->
+The value of any status or preedit argument is a pointer
+to a structure of type
+<function>XIMCallback</function>.
+<indexterm significance="preferred"><primary>XIMProc</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMCallback</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef void (*XIMProc)();
+
+typedef struct {
+ XPointer client_data;
+ XIMProc callback;
+} XIMCallback;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Each callback has some particular semantics and will carry the data
+that expresses the environment necessary to the client
+into a specific data structure.
+This paragraph only describes the arguments to be used to set
+the callback.
+</para>
+<para>
+<!-- .LP -->
+Setting any of these values while doing preedit
+may cause unexpected results.
+</para>
+</sect4>
+</sect3>
+</sect2>
+<sect2 id="Input_Method_Callback_Semantics">
+<title>Input Method Callback Semantics</title>
+<!-- .XS -->
+<!-- (SN Input Method Callback Semantics -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<acronym>XIM</acronym> callbacks are procedures defined by clients or text drawing packages
+that are to be called from the input method when selected events occur.
+Most clients will use a text editing package or a toolkit
+and, hence, will not need to define such callbacks.
+This section defines the callback semantics, when they are triggered,
+and what their arguments are.
+This information is mostly useful for X toolkit implementors.
+</para>
+<para>
+<!-- .LP -->
+Callbacks are mostly provided so that clients (or text editing
+packages) can implement on-the-spot preediting in their own window.
+In that case,
+the input method needs to communicate and synchronize with the client.
+The input method needs to communicate changes in the preedit window
+when it is under control of the client.
+Those callbacks allow the client to initialize the preedit area,
+display a new preedit string,
+move the text insertion point during preedit,
+terminate preedit, or update the status area.
+</para>
+<para>
+<!-- .LP -->
+All callback procedures follow the generic prototype:
+<indexterm significance="preferred"><primary>CallbackPrototype</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> CallbackPrototype</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>SomeType<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies data specific to the callback.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The call_data argument is a structure that expresses the arguments needed
+to achieve the semantics;
+that is,
+it is a specific data structure appropriate to the callback.
+In cases where no data is needed in the callback,
+this call_data argument is NULL.
+The client_data argument is a closure that has been initially specified
+by the client when specifying the callback and passed back.
+It may serve, for example, to inherit application context in the callback.
+</para>
+<para>
+<!-- .LP -->
+The following paragraphs describe the programming semantics
+and specific data structure associated with the different reasons.
+</para>
+<sect3 id="Geometry_Callback_b">
+<title>Geometry Callback</title>
+<!-- .XS -->
+<!-- (SN Geometry Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The geometry callback is triggered by the input method
+to indicate that it wants the client to negotiate geometry.
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>GeometryCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> GeometryCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is called with a NULL call_data argument.
+</para>
+</sect3>
+<sect3 id="Destroy_Callback_c">
+<title>Destroy Callback</title>
+<!-- .XS -->
+<!-- (SN Destroy Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The destroy callback is triggered by the input method
+when it stops service for any reason.
+After the callback is invoked, the input context will be freed by Xlib.
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> DestroyCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is called with a NULL call_data argument.
+</para>
+</sect3>
+<sect3 id="String_Conversion_Callback_b">
+<title>String Conversion Callback</title>
+<!-- .XS -->
+<!-- (SN String Conversion Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The string conversion callback is triggered by the input method
+to request the client to return the string to be converted. The
+returned string may be either a multibyte or wide character string,
+with an encoding matching the locale bound to the input context.
+The callback prototype is as follows:
+<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> StringConversionCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the amount of the string to be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is passed an
+<function>XIMStringConversionCallbackStruct</function>
+structure in the call_data argument.
+The text member is an
+<function>XIMStringConversionText</function>
+structure (see section 13.5.6.9) to be filled in by the client
+and describes the text to be sent to the input method.
+The data pointed to by the
+string and feedback elements of the
+<function>XIMStringConversionText</function>
+structure will be freed using
+<function>XFree</function>
+by the input method
+after the callback returns. So the client should not point to
+internal buffers that are critical to the client.
+Similarly, because the feedback element is currently reserved for future
+use, the client should set feedback to NULL to prevent the library from
+freeing memory at some random location due to an uninitialized pointer.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMStringConversionCallbackStruct</function>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMStringConversionCallbackStruct</primary></indexterm>
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef struct _XIMStringConversionCallbackStruct {
+ XIMStringConversionPosition position;
+ XIMCaretDirection direction;
+ short factor;
+ XIMStringConversionOperation operation;
+ XIMStringConversionText *text;
+} XIMStringConversionCallbackStruct;
+
+typedef short XIMStringConversionPosition;
+
+typedef unsigned short XIMStringConversionOperation;
+
+#define XIMStringConversionSubstitution (0x0001)
+#define XIMStringConversionRetrieval (0x0001)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XIMStringConversionPosition</function>
+specifies the starting position of the string to be returned
+in the
+<function>XIMStringConversionText</function>
+structure. The value identifies a position, in units of characters,
+relative to the client's cursor position in the client's buffer.
+</para>
+<para>
+<!-- .LP -->
+The ending position of the text buffer is determined by
+the direction and factor members. Specifically, it is the character position
+relative to the starting point as defined by the
+<function>XIMCaretDirection</function>.
+The factor member of
+<function>XIMStringConversionCallbackStruct </function>
+specifies the number of
+<function>XIMCaretDirection </function>
+positions to be applied. For example, if the direction specifies
+<function>XIMLineEnd</function>
+and factor is 1, then all characters from the starting position to
+the end of the current display line are returned. If the direction
+specifies
+<function>XIMForwardChar</function>
+or
+<function>XIMBackwardChar</function>,
+then the factor specifies a relative position, indicated in characters,
+from the starting position.
+</para>
+<para>
+<!-- .LP -->
+<function>XIMStringConversionOperation</function>
+specifies whether the string to be converted should be
+deleted (substitution) or copied (retrieval) from the client's
+buffer. When the
+<function>XIMStringConversionOperation</function>
+is
+<function>XIMStringConversionSubstitution</function>,
+the client must delete the string to be converted from its own buffer.
+When the
+<function>XIMStringConversionOperation</function>
+is
+<function>XIMStringConversionRetrieval</function>,
+the client must not delete the string to be converted from its buffer.
+The substitute operation is typically used for reconversion and
+transliteration conversion,
+while the retrieval operation is typically used for context-sensitive
+conversion.
+</para>
+</sect3>
+<sect3 id="Preedit_State_Callbacks">
+<title>Preedit State Callbacks</title>
+<!-- .XS -->
+<!-- (SN Preedit State Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When the input method turns preediting on or off, a
+<function>PreeditStartCallback</function>
+or
+<function>PreeditDoneCallback</function>
+callback is triggered to let the toolkit do the setup
+or the cleanup for the preedit region.
+<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> PreeditStartCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When preedit starts on the specified input context,
+the callback is called with a NULL call_data argument.
+<function>PreeditStartCallback</function>
+will return the maximum size of the preedit string.
+A positive number indicates the maximum number of bytes allowed
+in the preedit string,
+and a value of -1 indicates there is no limit.
+<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> PreeditDoneCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When preedit stops on the specified input context,
+the callback is called with a NULL call_data argument.
+The client can release the data allocated by
+<function>PreeditStartCallback</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>PreeditStartCallback</function>
+should initialize appropriate data needed for
+displaying preedit information and for handling further
+<function>PreeditDrawCallback</function>
+calls.
+Once
+<function>PreeditStartCallback</function>
+is called, it will not be called again before
+<function>PreeditDoneCallback</function>
+has been called.
+</para>
+</sect3>
+<sect3 id="Preedit_Draw_Callback">
+<title>Preedit Draw Callback</title>
+<!-- .XS -->
+<!-- (SN Preedit Draw Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This callback is triggered to draw and insert, delete or replace,
+preedit text in the preedit region.
+The preedit text may include unconverted input text such as Japanese Kana,
+converted text such as Japanese Kanji characters, or characters of both kinds.
+That string is either a multibyte or wide character string,
+whose encoding matches the locale bound to the input context.
+The callback prototype
+is as follows:
+<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> PreeditDrawCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the preedit drawing information.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is passed an
+<function>XIMPreeditDrawCallbackStruct</function>
+structure in the call_data argument.
+The text member of this structure contains the text to be drawn.
+After the string has been drawn,
+the caret should be moved to the specified location.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMPreeditDrawCallbackStruct</function>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMPreeditDrawCallbackStruct</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XIMPreeditDrawCallbackStruct {
+ int caret; /* Cursor offset within preedit string */
+ int chg_first; /* Starting change position */
+ int chg_length; /* Length of the change in character count */
+ XIMText *text;
+} XIMPreeditDrawCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The client must keep updating a buffer of the preedit text
+and the callback arguments referring to indexes in that buffer.
+The call_data fields have specific meanings according to the operation,
+as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+To indicate text deletion,
+the call_data member specifies a NULL text field.
+The text to be deleted is then the current text in the buffer
+from position chg_first (starting at zero) on a character length
+of chg_length.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When text is non-NULL,
+it indicates insertion or replacement of text in the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The chg_length member
+identifies the number of characters in the current preedit buffer
+that are affected by this call.
+A positive chg_length indicates that chg_length number of characters, starting
+at chg_first, must be deleted or must be replaced by text, whose length is
+specified in the
+<function>XIMText</function>
+structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A chg_length value of zero indicates that text must be inserted
+right at the position specified by chg_first.
+A value of zero for chg_first specifies the first character in the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+chg_length and chg_first combine to identify the modification required to
+the preedit buffer; beginning at chg_first, replace chg_length number of
+characters with the text in the supplied
+<function>XIMText</function>
+structure. For example, suppose the preedit buffer contains the string "ABCDE".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literallayout class="monospaced">
+<!-- .ft C -->
+Text: A B C D E
+ ^ ^ ^ ^ ^ ^
+CharPos: 0 1 2 3 4 5
+<!-- .sp -->
+<!-- .ft P -->
+</literallayout>
+The CharPos in the diagram shows the location of the character position
+relative to the character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the value of chg_first is 1 and the value of chg_length is 3, this
+says to replace 3 characters beginning at character position 1 with the
+string in the
+<function>XIMText</function>
+structure.
+Hence, <acronym>BCD</acronym> would be replaced by the value in the structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Though chg_length and chg_first are both signed integers they will
+never have a negative value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The caret member
+identifies the character position before which the cursor should
+be placed - after modification to the preedit buffer has been completed.
+For example, if caret is zero, the cursor is at
+the beginning of the buffer. If the caret is one, the cursor is between
+the first and second character.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMText</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i 3i -->
+typedef struct _XIMText {
+ unsigned short length;
+ XIMFeedback * feedback;
+ Bool encoding_is_wchar;
+ union {
+ char * multi_byte;
+ wchar_t * wide_char;
+ } string;
+} XIMText;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The text string passed is actually a structure specifying as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The length member is the text length in characters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The encoding_is_wchar member is a value that indicates
+if the text string is encoded in wide character or multibyte format.
+The text string may be passed either as multibyte or as wide character;
+the input method controls in which form data is passed.
+The client's
+callback routine must be able to handle data passed in either form.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The string member is the text string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The feedback member indicates rendering type for each character in the
+string member.
+If string is NULL (indicating that only highlighting of the existing
+preedit buffer should be updated), feedback points to length highlight
+elements that should be applied to the existing preedit buffer, beginning
+at chg_first.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The feedback member expresses the types of rendering feedback
+the callback should apply when drawing text.
+Rendering of the text to be drawn is specified either in generic ways
+(for example, primary, secondary) or in specific ways (reverse, underline).
+When generic indications are given,
+the client is free to choose the rendering style.
+It is necessary, however, that primary and secondary be mapped
+to two distinct rendering styles.
+</para>
+<para>
+<!-- .LP -->
+If an input method wants to control display of the preedit string, an
+input method can indicate the visibility hints using feedbacks in
+a specific way.
+The
+<function>XIMVisibleToForward</function>,
+<function>XIMVisibleToBackward</function>,
+and
+<function>XIMVisibleCenter</function>
+masks are exclusively used for these visibility hints.
+The
+<function>XIMVisibleToForward</function>
+mask
+indicates that the preedit text is preferably displayed in the
+primary draw direction from the
+caret position in the preedit area forward.
+The
+<function>XIMVisibleToBackward</function>
+mask
+indicates that the preedit text is preferably displayed from
+the caret position in the preedit area backward, relative to the primary
+draw direction.
+The
+<function>XIMVisibleCenter</function>
+mask
+indicates that the preedit text is preferably displayed with
+the caret position in the preedit area centered.
+</para>
+<para>
+<!-- .LP -->
+The insertion point of the preedit string could exist outside of
+the visible area when visibility hints are used.
+Only one of the
+masks
+is valid for the entire preedit string, and only one character
+can hold one of these feedbacks for a given input context at one time.
+This feedback may be OR'ed together with another highlight (such as
+<function>XIMReverse</function>).
+Only the most recently set feedback is valid, and any previous
+feedback is automatically canceled. This is a hint to the client, and
+the client is free to choose how to display the preedit string.
+</para>
+<para>
+<!-- .LP -->
+The feedback member also specifies how rendering of the text argument
+should be performed.
+If the feedback is NULL,
+the callback should apply the same feedback as is used for the surrounding
+characters in the preedit buffer; if chg_first is at a highlight boundary,
+the client can choose which of the two highlights to use.
+If feedback is not NULL, feedback specifies an array defining the
+rendering for each
+character of the string, and the length of the array is thus length.
+</para>
+<para>
+<!-- .LP -->
+If an input method wants to indicate that it is only updating the feedback of
+the preedit text without changing the content of it,
+the
+<function>XIMText</function>
+structure will contain a NULL value for the string field,
+the number of characters affected (relative to chg_first)
+will be in the length field,
+and the feedback field will point to an array of
+<function>XIMFeedback</function>.
+</para>
+<para>
+<!-- .LP -->
+Each element in the feedback array is a bitmask represented by a value of type
+<function>XIMFeedback</function>.
+The valid mask names are as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMReverse</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMUnderline</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMHighlight</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPrimary</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMSecondary</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMTertiary</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMVisibleToForward</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMVisibleToBackward</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMVisibleCenter</primary></indexterm>
+<!-- .sM -->
+</para>
+<literallayout class="monospaced">
+typedef unsigned long XIMFeedback;
+
+#define XIMReverse 1L
+#define XIMUnderline (1L<<1)
+#define XIMHighlight (1L<<2)
+#define XIMPrimary (1L<<5)*
+#define XIMSecondary (1L<<6)*
+#define XIMTertiary (1L<<7)*
+#define XIMVisibleToForward (1L<<8)
+#define XIMVisibleToBackward (1L<<9)
+#define XIMVisibleCenter (1L<<10)
+
+*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in
+the R5 specification. The X Consortium’s X11R5 implementation correctly implemented the val-
+ues for these highlights. The value of these highlights has been corrected in this specification to
+agree with the values in the Consortium’s X11R5 and X11R6 implementations.
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+Characters drawn with the
+<function>XIMReverse</function>
+highlight should be drawn by swapping the foreground and background colors
+used to draw normal, unhighlighted characters.
+Characters drawn with the
+<function>XIMUnderline</function>
+highlight should be underlined.
+Characters drawn with the
+<function>XIMHighlight</function>,
+<function>XIMPrimary</function>,
+<function>XIMSecondary</function>,
+and
+<function>XIMTertiary</function>
+highlights should be drawn in some unique manner that must be different
+from
+<function>XIMReverse</function>
+and
+<function>XIMUnderline</function>.
+<!-- .FS \(dg -->
+The values for
+<function>XIMPrimary</function>,
+<function>XIMSecondary</function>,
+and
+<function>XIMTertiary</function>
+were incorrectly defined in the R5 specification.
+The X Consortium's X11R5
+implementation correctly implemented the values for these highlights.
+The value of these highlights has been corrected in this specification
+to agree with the values in the Consortium's X11R5 and X11R6 implementations.
+<!-- .FE -->
+</para>
+</sect3>
+<sect3 id="Preedit_Caret_Callback">
+<title>Preedit Caret Callback</title>
+<!-- .XS -->
+<!-- (SN Preedit Caret Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input method may have its own navigation keys to allow the user
+to move the text insertion point in the preedit area
+(for example, to move backward or forward).
+Consequently, input method needs to indicate to the client that it
+should move the text insertion point.
+It then calls the PreeditCaretCallback.
+<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> PreeditCaretCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the preedit caret information.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The input method will trigger PreeditCaretCallback
+to move the text insertion point during preedit.
+The call_data argument contains a pointer to an
+<function>XIMPreeditCaretCallbackStruct</function>
+structure,
+which indicates where the caret should be moved.
+The callback must move the insertion point to its new location
+and return, in field position, the new offset value from the initial position.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMPreeditCaretCallbackStruct</function>
+structure is defined as follows:
+<indexterm significance="preferred"><primary>XIMPreeditCaretCallbackStruct</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XIMPreeditCaretCallbackStruct {
+ int position; /* Caret offset within preedit string */
+ XIMCaretDirection direction; /* Caret moves direction */
+ XIMCaretStyle style; /* Feedback of the caret */
+} XIMPreeditCaretCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIMCaretStyle</function>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMCaretStyle</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+ XIMIsInvisible, /* Disable caret feedback */
+ XIMIsPrimary, /* <acronym>UI</acronym> defined caret feedback */
+ XIMIsSecondary, /* <acronym>UI</acronym> defined caret feedback */
+} XIMCaretStyle;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIMCaretDirection</function>
+structure is defined as follows:
+<indexterm significance="preferred"><primary>XIMCaretDirection</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+ XIMForwardChar, XIMBackwardChar,
+ XIMForwardWord, XIMBackwardWord,
+ XIMCaretUp, XIMCaretDown,
+ XIMNextLine, XIMPreviousLine,
+ XIMLineStart, XIMLineEnd,
+ XIMAbsolutePosition,
+ XIMDontChange,
+ } XIMCaretDirection;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+These values are defined as follows:
+</para>
+<indexterm significance="preferred"><primary>XIMForwardChar</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMBackwardChar</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMForwardWord</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMBackwardWord</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMCaretUp</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMCaretDown</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XIMForwardChar</function></entry>
+ <entry>Move the caret forward one character position.</entry>
+ </row>
+ <row>
+ <entry><function>XIMBackwardChar</function></entry>
+ <entry>Move the caret backward one character position.</entry>
+ </row>
+ <row>
+ <entry><function>XIMForwardWord</function></entry>
+ <entry>Move the caret forward one word.</entry>
+ </row>
+ <row>
+ <entry><function>XIMBackwardWord</function></entry>
+ <entry>Move the caret backward one word.</entry>
+ </row>
+ <row>
+ <entry><function>XIMCaretUp</function></entry>
+ <entry>Move the caret up one line keeping the current horizontal offset.</entry>
+ </row>
+ <row>
+ <entry><function>XIMCaretDown</function></entry>
+ <entry>Move the caret down one line keeping the current horizontal offset.</entry>
+ </row>
+ <row>
+ <entry><function>XIMPreviousLine</function></entry>
+ <entry>Move the caret to the beginning of the previous line.</entry>
+ </row>
+ <row>
+ <entry><function>XIMNextLine</function></entry>
+ <entry>Move the caret to the beginning of the next line.</entry>
+ </row>
+ <row>
+ <entry><function>XIMLineStart</function></entry>
+ <entry>Move the caret to the beginning of the current display line that contains the caret.</entry>
+ </row>
+ <row>
+ <entry><function>XIMLineEnd</function></entry>
+ <entry>Move the caret to the end of the current display line that contains the caret.</entry>
+ </row>
+ <row>
+ <entry><function>XIMAbsolutePosition</function></entry>
+ <entry>The callback must move to the location specified by the position field
+ of the callback data, indicated in characters, starting from the beginning
+ of the preedit text.
+ Hence, a value of zero means move back to the beginning of the preedit text.</entry>
+ </row>
+ <row>
+ <entry><function>XIMDontChange</function></entry>
+ <entry>The caret position does not change.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<indexterm significance="preferred"><primary>XIMNextLine</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreviousLine</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMLineStart</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMLineEnd</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMAbsolutePosition</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMDontChange</primary></indexterm>
+</sect3>
+<sect3 id="Status_Callbacks">
+<title>Status Callbacks</title>
+<!-- .XS -->
+<!-- (SN Status Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input method may communicate changes in the status of an input context
+(for example, created, destroyed, or focus changes) with three status
+callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+When the input context is created or gains focus,
+the input method calls the StatusStartCallback callback.
+<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> StatusStartCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback should initialize appropriate data for displaying status
+and for responding to StatusDrawCallback calls.
+Once StatusStartCallback is called,
+it will not be called again before StatusDoneCallback has been called.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+When an input context
+is destroyed or when it loses focus, the input method calls StatusDoneCallback.
+<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> StatusDoneCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Not used for this callback and always passed as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback may release any data allocated on
+<function>StatusStart</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+When an input context status has to be updated, the input method calls
+StatusDrawCallback.
+<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> StatusDrawCallback</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the status drawing information.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback should update the status area by either drawing a string
+or imaging a bitmap in the status area.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIMStatusDataType</function>
+and
+<function>XIMStatusDrawCallbackStruct</function>
+structures are defined as follows:
+<indexterm significance="preferred"><primary>XIMStatusDataType</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusDrawCallbackStruct</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef enum {
+ XIMTextType,
+ XIMBitmapType,
+} XIMStatusDataType;
+
+typedef struct _XIMStatusDrawCallbackStruct {
+ XIMStatusDataType type;
+ union {
+ XIMText *text;
+ Pixmap bitmap;
+ } data;
+} XIMStatusDrawCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+The feedback styles
+<function>XIMVisibleToForward</function>,
+<function>XIMVisibleToBackward</function>,
+and
+<function>XIMVisibleToCenter</function>
+are not relevant and will not appear in the
+<function>XIMFeedback</function>
+element of the
+<function>XIMText</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Event_Filtering_b">
+<title>Event Filtering</title>
+<!-- .XS -->
+<!-- (SN Event Filtering -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides the ability for an input method
+to register a filter internal to Xlib.
+This filter is called by a client (or toolkit) by calling
+<function>XFilterEvent</function>
+after calling
+<function>XNextEvent</function>.
+Any client that uses the
+<function>XIM</function>
+interface should call
+<function>XFilterEvent</function>
+to allow input methods to process their events without knowledge
+of the client's dispatching mechanism.
+A client's user interface policy may determine the priority
+of event filters with respect to other event-handling mechanisms
+(for example, modal grabs).
+</para>
+<para>
+<!-- .LP -->
+Clients may not know how many filters there are, if any,
+and what they do.
+They may only know if an event has been filtered on return of
+<function>XFilterEvent</function>.
+Clients should discard filtered events.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To filter an event, use
+<function>XFilterEvent</function>.
+<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XFilterEvent</function></funcdef>
+ <paramdef>XEvent<parameter> *event</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ev event to filter -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the (Ev.
+<!-- .ds Wi for which the filter is to be applied -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the window argument is
+<function>None</function>,
+<function>XFilterEvent </function>
+applies the filter to the window specified in the
+<function>XEvent</function>
+structure.
+The window argument is provided so that layers above Xlib
+that do event redirection can indicate to which window an event
+has been redirected.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XFilterEvent</function>
+returns
+<function>True</function>,
+then some input method has filtered the event,
+and the client should discard the event.
+If
+<function>XFilterEvent</function>
+returns
+<function>False</function>,
+then the client should continue processing the event.
+</para>
+<para>
+<!-- .LP -->
+If a grab has occurred in the client and
+<function>XFilterEvent</function>
+returns
+<function>True</function>,
+the client should ungrab the keyboard.
+</para>
+</sect2>
+<sect2 id="Getting_Keyboard_Input_b">
+<title>Getting Keyboard Input</title>
+<!-- .XS -->
+<!-- (SN Getting Keyboard Input -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To get composed input from an input method,
+use
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbLookupString</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
+ <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> bytes_buffer</parameter></paramdef>
+ <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
+ <paramdef>Status<parameter> *status_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcLookupString</function></funcdef>
+ <paramdef>XIC<parameter> ic</parameter></paramdef>
+ <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
+ <paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> wchars_buffer</parameter></paramdef>
+ <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
+ <paramdef>Status<parameter> *status_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ic</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the input context.
+<!-- .ds Ev key event to be used -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the (Ev.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a multibyte string or wide character string (if any)
+from the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes_buffer</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>wchars_buffer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies space available in the return buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the KeySym computed from the event if this argument is not NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>status_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a value indicating what kind of data is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+functions return the string from the input method specified
+in the buffer_return argument.
+If no string is returned,
+the buffer_return argument is unchanged.
+</para>
+<para>
+<!-- .LP -->
+The KeySym into which the KeyCode from the event was mapped is returned
+in the keysym_return argument if it is non-NULL and the status_return
+argument indicates that a KeySym was returned.
+If both a string and a KeySym are returned,
+the KeySym value does not necessarily correspond to the string returned.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbLookupString</function>
+returns the length of the string in bytes, and
+<function>XwcLookupString</function>
+returns the length of the string in characters.
+Both
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+return text in the encoding of the locale bound to the input method
+of the specified input context.
+</para>
+<para>
+<!-- .LP -->
+Each string returned by
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+begins in the initial state of the encoding of the locale
+(if the encoding of the locale is state-dependent).
+<!-- .NT -->
+<note><para>
+To insure proper input processing,
+it is essential that the client pass only
+<function>KeyPress</function>
+events to
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>.
+Their behavior when a client passes a
+<function>KeyRelease</function>
+event is undefined.
+</para></note>
+<!-- .NE -->
+</para>
+<para>
+<!-- .LP -->
+Clients should check the status_return argument before
+using the other returned values.
+These two functions both return a value to status_return
+that indicates what has been returned in the other arguments.
+The possible values returned are:
+</para>
+
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>XBufferOverflow</function></entry>
+ <entry>The input string to be returned is too large for the supplied buffer_return.
+ The required size
+ (<function>XmbLookupString</function>
+ in bytes;
+ <function>XwcLookupString</function>
+ in characters) is returned as the value of the function,
+ and the contents of buffer_return and keysym_return are not modified.
+ The client should recall the function with the same event
+ and a buffer of adequate size to obtain the string.</entry>
+ </row>
+ <row>
+ <entry><function>XLookupNone</function></entry>
+ <entry>No consistent input has been composed so far.
+ The contents of buffer_return and keysym_return are not modified,
+ and the function returns zero.</entry>
+ </row>
+ <row>
+ <entry><function>XLookupChars</function></entry>
+ <entry>Some input characters have been composed.
+ They are placed in the buffer_return argument,
+ and the string length is returned as the value of the function.
+ The string is encoded in the locale bound to the input context.
+ The content of the keysym_return argument is not modified.</entry>
+ </row>
+ <row>
+ <entry><function>XLookupKeySym</function></entry>
+ <entry>A KeySym has been returned instead of a string
+ and is returned in keysym_return.
+ The content of the buffer_return argument is not modified,
+ and the function returns zero.</entry>
+ </row>
+ <row>
+ <entry><function>XLookupBoth</function></entry>
+ <entry>Both a KeySym and a string are returned;
+ <function>XLookupChars</function>
+ and
+ <function>XLookupKeySym</function>
+ occur simultaneously.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+It does not make any difference if the input context passed as an argument to
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+is the one currently in possession of the focus or not.
+Input may have been composed within an input context before it lost the focus,
+and that input may be returned on subsequent calls to
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+even though it does not have any more keyboard focus.
+</para>
+</sect2>
+<sect2 id="Input_Method_Conventions">
+<title>Input Method Conventions</title>
+<!-- .XS -->
+<!-- (SN Input Method Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The input method architecture is transparent to the client.
+However, clients should respect a number of conventions in order
+to work properly.
+Clients must also be aware of possible effects of synchronization
+between input method and library in the case of a remote input server.
+</para>
+<sect3 id="Client_Conventions">
+<title>Client Conventions</title>
+<!-- .XS -->
+<!-- (SN Client Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A well-behaved client (or toolkit) should first query the input method style.
+If the client cannot satisfy the requirements of the supported styles
+(in terms of geometry management or callbacks),
+it should negotiate with the user continuation of the program
+or raise an exception or error of some sort.
+</para>
+</sect3>
+<sect3 id="Synchronization_Conventions">
+<title>Synchronization Conventions</title>
+<!-- .XS -->
+<!-- (SN Synchronization Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A
+<function>KeyPress</function>
+event with a KeyCode of zero is used exclusively as a
+signal that an input method has composed input that can be returned by
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+No other use is made of a
+<function>KeyPress</function>
+event with KeyCode of zero.
+</para>
+<para>
+<!-- .LP -->
+Such an event may be generated by either a front-end
+or a back-end input method in an implementation-dependent manner.
+Some possible ways to generate this event include:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A synthetic event sent by an input method server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An artificial event created by a input method filter and pushed
+onto a client's event queue
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A
+<function>KeyPress</function>
+event whose KeyCode value is modified by an input method filter
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+When callback support is specified by the client,
+input methods will not take action unless they explicitly
+called back the client and obtained no response
+(the callback is not specified or returned invalid data).
+</para>
+</sect3>
+</sect2>
+</sect1>
+<sect1 id="String_Constants">
+<title>String Constants</title>
+<!-- .XS -->
+<!-- (SN String Constants -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following symbols for string constants are defined in
+<X11/Xlib.h> .
+Although they are shown here with particular macro definitions,
+they may be implemented as macros, as global symbols, or as a
+mixture of the two. The string pointer value itself
+is not significant; clients must not assume that inequality of two
+values implies inequality of the actual string data.
+</para>
+
+<literallayout class="monospaced">
+#define XNVaNestedList "XNVaNestedList"
+#define XNSeparatorofNestedList "separatorofNestedList"
+#define XNQueryInputStyle "queryInputStyle"
+#define XNClientWindow "clientWindow"
+#define XNInputStyle "inputStyle"
+#define XNFocusWindow "focusWindow"
+#define XNResourceName "resourceName"
+#define XNResourceClass "resourceClass"
+#define XNGeometryCallback "geometryCallback"
+#define XNDestroyCallback "destroyCallback"
+#define XNFilterEvents "filterEvents"
+#define XNPreeditStartCallback "preeditStartCallback"
+#define XNPreeditDoneCallback "preeditDoneCallback"
+#define XNPreeditDrawCallback "preeditDrawCallback"
+#define XNPreeditCaretCallback "preeditCaretCallback"
+#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback"
+#define XNPreeditAttributes "preeditAttributes"
+#define XNStatusStartCallback "statusStartCallback"
+#define XNStatusDoneCallback "statusDoneCallback"
+#define XNStatusDrawCallback "statusDrawCallback"
+#define XNStatusAttributes "statusAttributes"
+#define XNArea "area"
+#define XNAreaNeeded "areaNeeded"
+#define XNSpotLocation "spotLocation"
+#define XNColormap "colorMap"
+#define XNStdColormap "stdColorMap"
+#define XNForeground "foreground"
+#define XNBackground "background"
+#define XNBackgroundPixmap "backgroundPixmap"
+#define XNFontSet "fontSet"
+#define XNLineSpace "lineSpace"
+#define XNCursor "cursor"
+#define XNQueryIMValuesList "queryIMValuesList"
+#define XNQueryICValuesList "queryICValuesList"
+#define XNStringConversionCallback "stringConversionCallback"
+#define XNStringConversion "stringConversion"
+#define XNResetState "resetState"
+#define XNHotKey "hotkey"
+#define XNHotKeyState "hotkeyState"
+#define XNPreeditState "preeditState"
+#define XNVisiblePosition "visiblePosition"
+#define XNR6PreeditCallbackBehavior "r6PreeditCallback"
+#define XNRequiredCharSet "requiredCharSet"
+#define XNQueryOrientation "queryOrientation"
+#define XNDirectionalDependentDrawing "directionalDependentDrawing"
+#define XNContextualDrawing "contextualDrawing"
+#define XNBaseFontName "baseFontName"
+#define XNMissingCharSet "missingCharSet"
+#define XNDefaultString "defaultString"
+#define XNOrientation "orientation"
+#define XNFontInfo "fontInfo"
+#define XNOMAutomatic "omAutomatic"
+
+</literallayout>
+
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH14 b/libX11/specs/libX11/CH14 deleted file mode 100644 index 34c09da8b..000000000 --- a/libX11/specs/libX11/CH14 +++ /dev/null @@ -1,3590 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 14\fP\s-1 - -\s+1\fBInter-Client Communication Functions\fP\s-1 -.sp 2 -.nr H1 14 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 14: Inter-Client Communication Functions -.XE -The \fIInter-Client Communication Conventions Manual\fP, -hereafter referred to as the ICCCM, details the -X Consortium approved conventions that govern inter-client communications. -These conventions ensure peer-to-peer client cooperation in the use -of selections, cut buffers, and shared resources as well as client cooperation -with window and session managers. -For further information, -see the \fIInter-Client Communication Conventions Manual\fP. -.LP -Xlib provides a number of standard properties and programming interfaces -that are ICCCM compliant. -The predefined atoms for some of these properties are defined in the -.hN X11/Xatom.h -header file, where -to avoid name conflicts with user symbols their -.PN #define -name has an XA_ prefix. -For further information about atoms and properties, -see section 4.3. -.LP -Xlib's selection and cut buffer mechanisms provide the primary programming -interfaces by which peer client applications communicate with each other -(see sections 4.5 and 16.6). -The functions discussed in this chapter provide -the primary programming interfaces by which client applications communicate -with their window and session managers as well as share standard colormaps. -.LP -The standard properties that are of special interest for communicating -with window and session managers are: -.IN "Atom" "predefined" -.TS H -lw(2i) lw(1.1i) lw(.4i) lw(2.25i) -lw(2i) lw(1.1i) cw(.4i) lw(2.25i). -_ -.sp 6p -.B -Name Type Format Description -.sp 6p -_ -.TH -.R -T{ -\s-1WM_CLASS\s+1 -T} T{ -\s-1STRING\s+1 -T} T{ -8 -T} T{ -Set by application programs to allow window and session -managers to obtain the application's resources from the resource database. -T} -.sp 6p -T{ -\s-1WM_CLIENT_MACHINE\s+1 -T} T{ -\s-1TEXT\s+1 -T} T{ -T} T{ -The string name of the machine on which the client application is running. -T} -.sp 6p -T{ -\s-1WM_COLORMAP_WINDOWS\s+1 -T} T{ -\s-1WINDOW\s+1 -T} T{ -32 -T} T{ -The list of window IDs that may need a different colormap -from that of their top-level window. -T} -.sp 6p -T{ -\s-1WM_COMMAND\s+1 -T} T{ -\s-1TEXT\s+1 -T} T{ -T} T{ -The command and arguments, null-separated, used to invoke the -application. -T} -.sp 6p -T{ -\s-1WM_HINTS\s+1 -T} T{ -\s-1WM_HINTS\s+1 -T} T{ -32 -T} T{ -Additional hints set by the client for use by the window manager. -The C type of this property is -.PN XWMHints . -T} -.sp 6p -T{ -\s-1WM_ICON_NAME\s+1 -T} T{ -\s-1TEXT\s+1 -T} T{ -T} T{ -The name to be used in an icon. -T} -.sp 6p -T{ -\s-1WM_ICON_SIZE\s+1 -T} T{ -\s-1WM_ICON_SIZE\s+1 -T} T{ -32 -T} T{ -The window manager may set this property on the root window to -specify the icon sizes it supports. -The C type of this property is -.PN XIconSize . -T} -.sp 6p -T{ -\s-1WM_NAME\s+1 -T} T{ -\s-1TEXT\s+1 -T} T{ -T} T{ -The name of the application. -T} -.sp 6p -T{ -\s-1WM_NORMAL_HINTS\s+1 -T} T{ -\s-1WM_SIZE_HINTS\s+1 -T} T{ -32 -T} T{ -Size hints for a window in its normal state. -The C type of this property is -.PN XSizeHints . -T} -.sp 6p -T{ -\s-1WM_PROTOCOLS\s+1 -T} T{ -\s-1ATOM\s+1 -T} T{ -32 -T} T{ -List of atoms that identify the communications protocols between the -client and window manager in which the client is willing to participate. -T} -.sp 6p -T{ -\s-1WM_STATE\s+1 -T} T{ -\s-1WM_STATE\s+1 -T} T{ -32 -T} T{ -Intended for communication between window and session managers only. -T} -.sp 6p -T{ -\s-1WM_TRANSIENT_FOR\s+1 -T} T{ -\s-1WINDOW\s+1 -T} T{ -32 -T} T{ -Set by application programs to indicate to the window manager that a transient -top-level window, such as a dialog box. -T} -.sp 6p -_ -.TE -.LP -The remainder of this chapter discusses: -.IP \(bu 5 -Client to window manager communication -.IP \(bu 5 -Client to session manager communication -.IP \(bu 5 -Standard colormaps -.NH 2 -Client to Window Manager Communication -.XS -\*(SN Client to Window Manager Communication -.XE -.LP -This section discusses how to: -.IP \(bu 5 -Manipulate top-level windows -.IP \(bu 5 -Convert string lists -.IP \(bu 5 -Set and read text properties -.IP \(bu 5 -Set and read the WM_NAME property -.IP \(bu 5 -Set and read the WM_ICON_NAME property -.IP \(bu 5 -Set and read the WM_HINTS property -.IP \(bu 5 -Set and read the WM_NORMAL_HINTS property -.IP \(bu 5 -Set and read the WM_CLASS property -.IP \(bu 5 -Set and read the WM_TRANSIENT_FOR property -.IP \(bu 5 -Set and read the WM_PROTOCOLS property -.IP \(bu 5 -Set and read the WM_COLORMAP_WINDOWS property -.IP \(bu 5 -Set and read the WM_ICON_SIZE property -.IP \(bu 5 -Use window manager convenience functions -.NH 3 -Manipulating Top-Level Windows -.XS -\*(SN Manipulating Top-Level Windows -.XE -.LP -Xlib provides functions that you can use to change the visibility or size -of top-level windows (that is, those that were created as children -of the root window). -Note that the subwindows that you create are ignored by window managers. -Therefore, -you should use the basic window functions described in chapter 3 -to manipulate your application's subwindows. -.LP -To request that a top-level window be iconified, use -.PN XIconifyWindow . -.IN "XIconifyWindow" "" "@DEF@" -.sM -.FD 0 -Status XIconifyWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -The -.PN XIconifyWindow -function sends a WM_CHANGE_STATE -.PN ClientMessage -event with a format of 32 and a first data element of -.PN IconicState -(as described in section 4.1.4 of the -\fIInter-Client Communication Conventions Manual\fP) -and a window of w -to the root window of the specified screen -with an event mask set to -.PN SubstructureNotifyMask | -.PN SubstructureRedirectMask . -Window managers may elect to receive this message and -if the window is in its normal state, -may treat it as a request to change the window's state from normal to iconic. -If the WM_CHANGE_STATE property cannot be interned, -.PN XIconifyWindow -does not send a message and returns a zero status. -It returns a nonzero status if the client message is sent successfully; -otherwise, it returns a zero status. -.sp -.LP -To request that a top-level window be withdrawn, use -.PN XWithdrawWindow . -.IN "XWithdrawWindow" "" "@DEF@" -.sM -.FD 0 -Status XWithdrawWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -The -.PN XWithdrawWindow -function unmaps the specified window -and sends a synthetic -.PN UnmapNotify -event to the root window of the specified screen. -Window managers may elect to receive this message -and may treat it as a request to change the window's state to withdrawn. -When a window is in the withdrawn state, -neither its normal nor its iconic representations is visible. -It returns a nonzero status if the -.PN UnmapNotify -event is successfully sent; -otherwise, it returns a zero status. -.LP -.PN XWithdrawWindow -can generate a -.PN BadWindow -error. -.sp -.LP -To request that a top-level window be reconfigured, use -.PN XReconfigureWMWindow . -.IN "XReconfigureWMWindow" "" "@DEF@" -.sM -.FD 0 -Status XReconfigureWMWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP, \ -\fIvalue_mask\fP, \fIvalues\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIscreen_number\fP\^; -.br - unsigned int \fIvalue_mask\fP\^; -.br - XWindowChanges *\fIvalues\fP; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.IP \fIvalue_mask\fP 1i -Specifies which values are to be set using information in -the values structure. -This mask is the bitwise inclusive OR of the valid configure window values bits. -.IP \fIvalues\fP 1i -Specifies the -.PN XWindowChanges -structure. -.LP -.eM -The -.PN XReconfigureWMWindow -function issues a -.PN ConfigureWindow -request on the specified top-level window. -If the stacking mode is changed and the request fails with a -.PN BadMatch -error, -the error is trapped by Xlib and a synthetic -.PN ConfigureRequestEvent -containing the same configuration parameters is sent to the root -of the specified window. -Window managers may elect to receive this event -and treat it as a request to reconfigure the indicated window. -It returns a nonzero status if the request or event is successfully sent; -otherwise, it returns a zero status. -.LP -.PN XReconfigureWMWindow -can generate -.PN BadValue -and -.PN BadWindow -errors. -.NH 3 -Converting String Lists -.XS -\*(SN Converting String Lists -.XE -.LP -Many of the text properties allow a variety of types and formats. -Because the data stored in these properties are not -simple null-terminated strings, an -.PN XTextProperty -structure is used to describe the encoding, type, and length of the text -as well as its value. -The -.PN XTextProperty -structure contains: -.IN "XTextProperty" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - unsigned char *value; /* property data */ - Atom encoding; /* type of property */ - int format; /* 8, 16, or 32 */ - unsigned long nitems; /* number of items in value */ -} XTextProperty; -.De -.LP -.eM -Xlib provides functions to convert localized text to or from encodings -that support the inter-client communication conventions for text. -In addition, functions are provided for converting between lists of pointers -to character strings and text properties in the STRING encoding. -.LP -The functions for localized text return a signed integer error status -that encodes -.PN Success -as zero, specific error conditions as negative numbers, and partial conversion -as a count of unconvertible characters. -.LP -.IN "XICCEncodingStyle" "" "@DEF@" -.sM -.TS -lw(.5i) lw(2i) lw(2.5i). -T{ -#define -T} T{ -.PN XNoMemory -T} T{ -\-1 -T} -T{ -#define -T} T{ -.PN XLocaleNotSupported -T} T{ -\-2 -T} -T{ -#define -T} T{ -.PN XConverterNotFound -T} T{ -\-3 -T} -.TE -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef enum { - XStringStyle, /* STRING */ - XCompoundTextStyle, /* COMPOUND_TEXT */ - XTextStyle, /* text in owner's encoding (current locale) */ - XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ -} XICCEncodingStyle; -.De -.LP -.eM -.sp -.LP -To convert a list of text strings to an -.PN XTextProperty -structure, use -.PN XmbTextListToTextProperty -or -.PN XwcTextListToTextProperty . -.IN "XmbTextListToTextProperty" "" "@DEF@" -.IN "XwcTextListToTextProperty" "" "@DEF@" -.sM -.FD 0 -int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char **\fIlist\fP\^; -.br - int \fIcount\fP\^; -.br - XICCEncodingStyle \fIstyle\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.FN -.FD 0 -int XwcTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - wchar_t **\fIlist\fP\^; -.br - int \fIcount\fP\^; -.br - XICCEncodingStyle \fIstyle\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIlist\fP 1i -Specifies a list of null-terminated character strings. -.IP \fIcount\fP 1i -Specifies the number of strings specified. -.IP \fIstyle\fP 1i -Specifies the manner in which the property is encoded. -.IP \fItext_prop_return\fP 1i -Returns the -.PN XTextProperty -structure. -.LP -.eM -The -.PN XmbTextListToTextProperty -and -.PN XwcTextListToTextProperty -functions set the specified -.PN XTextProperty -value to a set of null-separated elements representing the concatenation -of the specified list of null-terminated text strings. -A final terminating null is stored at the end of the value field -of text_prop_return but is not included in the nitems member. -.LP -The functions set the encoding field of text_prop_return to an -.PN Atom -for the specified display -naming the encoding determined by the specified style -and convert the specified text list to this encoding for storage in -the text_prop_return value field. -If the style -.PN XStringStyle -or -.PN XCompoundTextStyle -is specified, -this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. -If the style -.PN XTextStyle -is specified, -this encoding is the encoding of the current locale. -If the style -.PN XStdICCTextStyle -is specified, -this encoding is ``STRING'' if the text is fully convertible to STRING, -else ``COMPOUND_TEXT''. -.LP -If insufficient memory is available for the new value string, -the functions return -.PN XNoMemory . -If the current locale is not supported, -the functions return -.PN XLocaleNotSupported . -In both of these error cases, -the functions do not set text_prop_return. -.LP -To determine if the functions are guaranteed not to return -.PN XLocaleNotSupported , -use -.PN XSupportsLocale . -.LP -If the supplied text is not fully convertible to the specified encoding, -the functions return the number of unconvertible characters. -Each unconvertible character is converted to an implementation-defined and -encoding-specific default string. -Otherwise, the functions return -.PN Success . -Note that full convertibility to all styles except -.PN XStringStyle -is guaranteed. -.LP -To free the storage for the value field, use -.PN XFree . -.sp -.LP -To obtain a list of text strings from an -.PN XTextProperty -structure, use -.PN XmbTextPropertyToTextList -or -.PN XwcTextPropertyToTextList . -.IN "XmbTextPropertyToTextList" "" "@DEF@" -.IN "XwcTextPropertyToTextList" "" "@DEF@" -.sM -.FD 0 -int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XTextProperty *\fItext_prop\fP\^; -.br - char ***\fIlist_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.FD 0 -int XwcTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XTextProperty *\fItext_prop\fP\^; -.br - wchar_t ***\fIlist_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItext_prop\fP 1i -Specifies the -.PN XTextProperty -structure to be used. -.IP \fIlist_return\fP 1i -Returns a list of null-terminated character strings. -.ds Cn strings -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XmbTextPropertyToTextList -and -.PN XwcTextPropertyToTextList -functions return a list of text strings in the current locale representing the -null-separated elements of the specified -.PN XTextProperty -structure. -The data in text_prop must be format 8. -.LP -Multiple elements of the property (for example, the strings in a disjoint -text selection) are separated by a null byte. -The contents of the property are not required to be null-terminated; -any terminating null should not be included in text_prop.nitems. -.LP -If insufficient memory is available for the list and its elements, -.PN XmbTextPropertyToTextList -and -.PN XwcTextPropertyToTextList -return -.PN XNoMemory . -If the current locale is not supported, -the functions return -.PN XLocaleNotSupported . -Otherwise, if the encoding field of text_prop is not convertible -to the encoding of the current locale, -the functions return -.PN XConverterNotFound . -For supported locales, -existence of a converter from COMPOUND_TEXT, STRING -or the encoding of the current locale is guaranteed if -.PN XSupportsLocale -returns -.PN True -for the current locale (but the actual text -may contain unconvertible characters). -Conversion of other encodings is implementation-dependent. -In all of these error cases, -the functions do not set any return values. -.LP -Otherwise, -.PN XmbTextPropertyToTextList -and -.PN XwcTextPropertyToTextList -return the list of null-terminated text strings to list_return -and the number of text strings to count_return. -.LP -If the value field of text_prop is not fully convertible to the encoding of -the current locale, -the functions return the number of unconvertible characters. -Each unconvertible character is converted to a string in the -current locale that is specific to the current locale. -To obtain the value of this string, -use -.PN XDefaultString . -Otherwise, -.PN XmbTextPropertyToTextList -and -.PN XwcTextPropertyToTextList -return -.PN Success . -.LP -To free the storage for the list and its contents returned by -.PN XmbTextPropertyToTextList , -use -.PN XFreeStringList . -To free the storage for the list and its contents returned by -.PN XwcTextPropertyToTextList , -use -.PN XwcFreeStringList . -.sp -.LP -To free the in-memory data associated with the specified -wide character string list, use -.PN XwcFreeStringList . -.IN "XwcFreeStringList" "" "@DEF@" -.sM -.FD 0 -void XwcFreeStringList\^(\^\fIlist\fP\^) -.br - wchar_t **\fIlist\fP\^; -.FN -.IP \fIlist\fP 1i -Specifies the list of strings to be freed. -.LP -.eM -The -.PN XwcFreeStringList -function frees memory allocated by -.PN XwcTextPropertyToTextList . -.sp -.LP -To obtain the default string for text conversion in the current locale, -use -.PN XDefaultString . -.IN "XDefaultString" "" "@DEF@" -.sM -.FD 0 -char *XDefaultString\^(\|) -.FN -.LP -.eM -The -.PN XDefaultString -function returns the default string used by Xlib for text conversion -(for example, in -.PN XmbTextPropertyToTextList ). -The default string is the string in the current locale that is output -when an unconvertible character is found during text conversion. -If the string returned by -.PN XDefaultString -is the empty string ("\^"), -no character is output in the converted text. -.PN XDefaultString -does not return NULL. -.LP -The string returned by -.PN XDefaultString -is independent of the default string for text drawing; -see -.PN XCreateFontSet -to obtain the default string for an -.PN XFontSet . -.LP -The behavior when an invalid codepoint is supplied to any Xlib function is -undefined. -.LP -The returned string is null-terminated. -It is owned by Xlib and should not be modified or freed by the client. -It may be freed after the current locale is changed. -Until freed, it will not be modified by Xlib. -.sp -.LP -To set the specified list of strings in the STRING encoding to a -.PN XTextProperty -structure, use -.PN XStringListToTextProperty . -.IN "XStringListToTextProperty" "" "@DEF@" -.sM -.FD 0 -Status XStringListToTextProperty\^(\^\fIlist\fP, \fIcount\fP, \ -\fItext_prop_return\fP\^) -.br - char **\fIlist\fP\^; -.br - int \fIcount\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.FN -.IP \fIlist\fP 1i -Specifies a list of null-terminated character strings. -.ds Cn strings -.IP \fIcount\fP 1i -Specifies the number of \*(Cn. -.IP \fItext_prop_return\fP 1i -Returns the -.PN XTextProperty -structure. -.LP -.eM -The -.PN XStringListToTextProperty -function sets the specified -.PN XTextProperty -to be of type STRING (format 8) with a value representing the -concatenation of the specified list of null-separated character strings. -An extra null byte (which is not included in the nitems member) -is stored at the end of the value field of text_prop_return. -The strings are assumed (without verification) to be in the STRING encoding. -If insufficient memory is available for the new value string, -.PN XStringListToTextProperty -does not set any fields in the -.PN XTextProperty -structure and returns a zero status. -Otherwise, it returns a nonzero status. -To free the storage for the value field, use -.PN XFree . -.sp -.LP -To obtain a list of strings from a specified -.PN XTextProperty -structure in the STRING encoding, use -.PN XTextPropertyToStringList . -.IN "XTextPropertyToStringList" "" "@DEF@" -.sM -.FD 0 -Status XTextPropertyToStringList\^(\^\fItext_prop\fP, \fIlist_return\fP, \ -\fIcount_return\fP\^) -.br - XTextProperty *\fItext_prop\fP\^; -.br - char ***\fIlist_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fItext_prop\fP 1i -Specifies the -.PN XTextProperty -structure to be used. -.IP \fIlist_return\fP 1i -Returns a list of null-terminated character strings. -.ds Cn strings -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XTextPropertyToStringList -function returns a list of strings representing the null-separated elements -of the specified -.PN XTextProperty -structure. -The data in text_prop must be of type STRING and format 8. -Multiple elements of the property -(for example, the strings in a disjoint text selection) -are separated by NULL (encoding 0). -The contents of the property are not null-terminated. -If insufficient memory is available for the list and its elements, -.PN XTextPropertyToStringList -sets no return values and returns a zero status. -Otherwise, it returns a nonzero status. -To free the storage for the list and its contents, use -.PN XFreeStringList . -.sp -.LP -To free the in-memory data associated with the specified string list, use -.PN XFreeStringList . -.IN "XFreeStringList" "" "@DEF@" -.sM -.FD 0 -void XFreeStringList\^(\^\fIlist\fP\^) -.br - char **\fIlist\fP\^; -.FN -.IP \fIlist\fP 1i -Specifies the list of strings to be freed. -.LP -.eM -The -.PN XFreeStringList -function releases memory allocated by -.PN XmbTextPropertyToTextList -and -.PN XTextPropertyToStringList -and the missing charset list allocated by -.PN XCreateFontSet . -.NH 3 -Setting and Reading Text Properties -.XS -\*(SN Setting and Reading Text Properties -.XE -.LP -Xlib provides two functions that you can use to set and read -the text properties for a given window. -You can use these functions to set and read those properties of type TEXT -(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE). -In addition, -Xlib provides separate convenience functions that you can use to set each -of these properties. -For further information about these convenience functions, -see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively. -.sp -.LP -To set one of a window's text properties, use -.PN XSetTextProperty . -.IN "XSetTextProperty" "" "@DEF@" -.sM -.FD 0 -void XSetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP, \ -\fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop\fP 1i -Specifies the -.PN XTextProperty -structure to be used. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XSetTextProperty -function replaces the existing specified property for the named window -with the data, type, format, and number of items determined -by the value field, the encoding field, the format field, -and the nitems field, respectively, of the specified -.PN XTextProperty -structure. -If the property does not already exist, -.PN XSetTextProperty -sets it for the specified window. -.LP -.PN XSetTextProperty -can generate -.PN BadAlloc , -.PN BadAtom , -.PN BadValue , -and -.PN BadWindow -errors. -.sp -.LP -To read one of a window's text properties, use -.PN XGetTextProperty . -.IN "XGetTextProperty" "" "@DEF@" -.sM -.FD 0 -Status XGetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP, \ -\fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop_return\fP 1i -Returns the -.PN XTextProperty -structure. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XGetTextProperty -function reads the specified property from the window -and stores the data in the returned -.PN XTextProperty -structure. -It stores the data in the value field, -the type of the data in the encoding field, -the format of the data in the format field, -and the number of items of data in the nitems field. -An extra byte containing null (which is not included in the nitems member) -is stored at the end of the value field of text_prop_return. -The particular interpretation of the property's encoding -and data as text is left to the calling application. -If the specified property does not exist on the window, -.PN XGetTextProperty -sets the value field to NULL, -the encoding field to -.PN None , -the format field to zero, -and the nitems field to zero. -.LP -If it was able to read and store the data in the -.PN XTextProperty -structure, -.PN XGetTextProperty -returns a nonzero status; -otherwise, it returns a zero status. -.LP -.PN XGetTextProperty -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.NH 3 -Setting and Reading the WM_NAME Property -.XS -\*(SN Setting and Reading the WM_NAME Property -.XE -.LP -Xlib provides convenience functions that you can use to set and read -the WM_NAME property for a given window. -.sp -.LP -To set a window's WM_NAME property with the supplied convenience function, use -.PN XSetWMName . -.IN "XSetWMName" "" "@DEF@" -.sM -.FD 0 -void XSetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop\fP 1i -Specifies the -.PN XTextProperty -structure to be used. -.LP -.eM -The -.PN XSetWMName -convenience function calls -.PN XSetTextProperty -to set the WM_NAME property. -.sp -.LP -To read a window's WM_NAME property with the supplied convenience function, use -.PN XGetWMName . -.IN "XGetWMName" "" "@DEF@" -.sM -.FD 0 -Status XGetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop_return\fP 1i -Returns the -.PN XTextProperty -structure. -.LP -.eM -The -.PN XGetWMName -convenience function calls -.PN XGetTextProperty -to obtain the WM_NAME property. -It returns a nonzero status on success; -otherwise, it returns a zero status. -.LP -The following two functions have been superseded by -.PN XSetWMName -and -.PN XGetWMName , -respectively. -You can use these additional convenience functions -for window names that are encoded as STRING properties. -.sp -.LP -To assign a name to a window, use -.PN XStoreName . -.IN "Window" "name" -.IN "XStoreName" "" "@DEF@" -.sM -.FD 0 -XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char *\fIwindow_name\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwindow_name\fP 1i -Specifies the window name, -which should be a null-terminated string. -.LP -.eM -The -.PN XStoreName -function assigns the name passed to window_name to the specified window. -A window manager can display the window name in some prominent -place, such as the title bar, to allow users to identify windows easily. -Some window managers may display a window's name in the window's icon, -although they are encouraged to use the window's icon name -if one is provided by the application. -If the string is not in the Host Portable Character Encoding, -the result is implementation-dependent. -.LP -.PN XStoreName -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To get the name of a window, use -.PN XFetchName . -.IN "XFetchName" "" "@DEF@" -.sM -.FD 0 -Status XFetchName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char **\fIwindow_name_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwindow_name_return\fP 1i -Returns the window name, which is a null-terminated string. -.LP -.eM -The -.PN XFetchName -function returns the name of the specified window. -If it succeeds, -it returns a nonzero status; -otherwise, no name has been set for the window, -and it returns zero. -If the WM_NAME property has not been set for this window, -.PN XFetchName -sets window_name_return to NULL. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned string is in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -When finished with it, a client must free -the window name string using -.PN XFree . -.LP -.PN XFetchName -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_ICON_NAME Property -.XS -\*(SN Setting and Reading the WM_ICON_NAME Property -.XE -.LP -Xlib provides convenience functions that you can use to set and read -the WM_ICON_NAME property for a given window. -.LP -.sp -To set a window's WM_ICON_NAME property, -use -.PN XSetWMIconName . -.IN "XSetWMIconName" "" "@DEF@" -.sM -.FD 0 -void XSetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop\fP 1i -Specifies the -.PN XTextProperty -structure to be used. -.LP -.eM -The -.PN XSetWMIconName -convenience function calls -.PN XSetTextProperty -to set the WM_ICON_NAME property. -.sp -.LP -To read a window's WM_ICON_NAME property, -use -.PN XGetWMIconName . -.IN "XGetWMIconName" "" "@DEF@" -.sM -.FD 0 -Status XGetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop_return\fP 1i -Returns the -.PN XTextProperty -structure. -.LP -.eM -The -.PN XGetWMIconName -convenience function calls -.PN XGetTextProperty -to obtain the WM_ICON_NAME property. -It returns a nonzero status on success; -otherwise, it returns a zero status. -.LP -The next two functions have been superseded by -.PN XSetWMIconName -and -.PN XGetWMIconName , -respectively. -You can use these additional convenience functions -for window names that are encoded as STRING properties. -.sp -.LP -.sp -To set the name to be displayed in a window's icon, use -.PN XSetIconName . -.IN "Window" "icon name" -.IN "XSetIconName" "" "@DEF@" -.sM -.FD 0 -XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char *\fIicon_name\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIicon_name\fP 1i -Specifies the icon name, -which should be a null-terminated string. -.LP -.eM -If the string is not in the Host Portable Character Encoding, -the result is implementation-dependent. -.PN XSetIconName -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To get the name a window wants displayed in its icon, use -.PN XGetIconName . -.IN "XGetIconName" "" "@DEF@" -.sM -.FD 0 -Status XGetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char **\fIicon_name_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIicon_name_return\fP 1i -Returns the window's icon name, -which is a null-terminated string. -.LP -.eM -The -.PN XGetIconName -function returns the name to be displayed in the specified window's icon. -If it succeeds, it returns a nonzero status; otherwise, -if no icon name has been set for the window, -it returns zero. -If you never assigned a name to the window, -.PN XGetIconName -sets icon_name_return to NULL. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned string is in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -When finished with it, a client must free -the icon name string using -.PN XFree . -.LP -.PN XGetIconName -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_HINTS Property -.XS -\*(SN Setting and Reading the WM_HINTS Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_HINTS property for a given window. -These functions use the flags and the -.PN XWMHints -structure, as defined in the -.hN X11/Xutil.h -header file. -.sp -.LP -To allocate an -.PN XWMHints -structure, use -.PN XAllocWMHints . -.IN "XAllocWMHints" "" "@DEF@" -.sM -.FD 0 -XWMHints *XAllocWMHints\^(\|) -.FN -.LP -.eM -The -.PN XAllocWMHints -function allocates and returns a pointer to an -.PN XWMHints -structure. -Note that all fields in the -.PN XWMHints -structure are initially set to zero. -If insufficient memory is available, -.PN XAllocWMHints -returns NULL. -To free the memory allocated to this structure, -use -.PN XFree . -.LP -The -.PN XWMHints -structure contains: -.LP -.sM -/* Window manager hints mask bits */ -.TS -lw(.5i) lw(2.5i) lw(2.5i). -T{ -#define -T} T{ -.PN InputHint -T} T{ -(1L << 0) -T} -T{ -#define -T} T{ -.PN StateHint -T} T{ -(1L << 1) -T} -T{ -#define -T} T{ -.PN IconPixmapHint -T} T{ -(1L << 2) -T} -T{ -#define -T} T{ -.PN IconWindowHint -T} T{ -(1L << 3) -T} -T{ -#define -T} T{ -.PN IconPositionHint -T} T{ -(1L << 4) -T} -T{ -#define -T} T{ -.PN IconMaskHint -T} T{ -(1L << 5) -T} -T{ -#define -T} T{ -.PN WindowGroupHint -T} T{ -(1L << 6) -T} -T{ -#define -T} T{ -.PN UrgencyHint -T} T{ -(1L << 8) -T} -T{ -#define -T} T{ -.PN AllHints -T} T{ -(InputHint|StateHint|IconPixmapHint| -.br -IconWindowHint|IconPositionHint| -.br -IconMaskHint|WindowGroupHint) -T} -.TE -.IN "XWMHints" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -/* Values */ - -typedef struct { - long flags; /* marks which fields in this structure are defined */ - Bool input; /* does this application rely on the window manager to - get keyboard input? */ - int initial_state; /* see below */ - Pixmap icon_pixmap; /* pixmap to be used as icon */ - Window icon_window; /* window to be used as icon */ - int icon_x, icon_y; /* initial position of icon */ - Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */ - XID window_group; /* id of related window group */ - /* this structure may be extended in the future */ -} XWMHints; -.De -.LP -.eM -The input member is used to communicate to the window manager the input focus -model used by the application. -Applications that expect input but never explicitly set focus to any -of their subwindows (that is, use the push model of focus management), -such as X Version 10 style applications that use real-estate -driven focus, should set this member to -.PN True . -Similarly, applications -that set input focus to their subwindows only when it is given to their -top-level window by a window manager should also set this member to -.PN True . -Applications that manage their own input focus by explicitly setting -focus to one of their subwindows whenever they want keyboard input -(that is, use the pull model of focus management) should set this member to -.PN False . -Applications that never expect any keyboard input also should set this member -to -.PN False . -.LP -Pull model window managers should make it possible for push model -applications to get input by setting input focus to the top-level windows of -applications whose input member is -.PN True . -Push model window managers should -make sure that pull model applications do not break them -by resetting input focus to -.PN PointerRoot -when it is appropriate (for example, whenever an application whose -input member is -.PN False -sets input focus to one of its subwindows). -.LP -The definitions for the initial_state flag are: -.TS -lw(.5i) lw(2i) lw(.2i) lw(2.8i). -T{ -#define -T} T{ -.PN WithdrawnState -T} T{ -0 -T} T{ -T} -T{ -#define -T} T{ -.PN NormalState -T} T{ -1 -T} T{ -/* most applications start this way */ -T} -T{ -#define -T} T{ -.PN IconicState -T} T{ -3 -T} T{ -/* application wants to start as an icon */ -T} -.TE -The icon_mask specifies which pixels of the icon_pixmap should be used as the -icon. -This allows for nonrectangular icons. -Both icon_pixmap and icon_mask must be bitmaps. -The icon_window lets an application provide a window for use as an icon -for window managers that support such use. -The window_group lets you specify that this window belongs to a group -of other windows. -For example, if a single application manipulates multiple -top-level windows, this allows you to provide enough -information that a window manager can iconify all of the windows -rather than just the one window. -.LP -The -.PN UrgencyHint -flag, if set in the flags field, indicates that the client deems the window -contents to be urgent, requiring the timely response of the user. The -window manager will make some effort to draw the user's attention to this -window while this flag is set. The client must provide some means by which the -user can cause the urgency flag to be cleared (either mitigating -the condition that made the window urgent or merely shutting off the alarm) -or the window to be withdrawn. -.LP -.sp -To set a window's WM_HINTS property, use -.PN XSetWMHints . -.IN "XSetWMHints" "" "@DEF@" -.sM -.FD 0 -XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XWMHints *\fIwmhints\fP\^; - -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwmhints\fP 1i -Specifies the -.PN XWMHints -structure to be used. -.LP -.eM -The -.PN XSetWMHints -function sets the window manager hints that include icon information and location, -the initial state of the window, and whether the application relies on the -window manager to get keyboard input. -.LP -.PN XSetWMHints -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To read a window's WM_HINTS property, use -.PN XGetWMHints . -.IN "XGetWMHints" "" "@DEF@" -.sM -.FD 0 -XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.LP -.eM -The -.PN XGetWMHints -function reads the window manager hints and -returns NULL if no WM_HINTS property was set on the window -or returns a pointer to an -.PN XWMHints -structure if it succeeds. -When finished with the data, -free the space used for it by calling -.PN XFree . -.LP -.PN XGetWMHints -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_NORMAL_HINTS Property -.XS -\*(SN Setting and Reading the WM_NORMAL_HINTS Property -.XE -.LP -Xlib provides functions that you can use to set or read -the WM_NORMAL_HINTS property for a given window. -The functions use the flags and the -.PN XSizeHints -structure, as defined in the -.hN X11/Xutil.h -header file. -.LP -The size of the -.PN XSizeHints -structure may grow in future releases, as new components are -added to support new ICCCM features. -Passing statically allocated instances of this structure into -Xlib may result in memory corruption when running against a -future release of the library. -As such, it is recommended that only dynamically allocated -instances of the structure be used. -.sp -.LP -To allocate an -.PN XSizeHints -structure, use -.PN XAllocSizeHints . -.IN "XAllocSizeHints" "" "@DEF@" -.sM -.FD 0 -XSizeHints *XAllocSizeHints\^(\|) -.FN -.LP -.eM -The -.PN XAllocSizeHints -function allocates and returns a pointer to an -.PN XSizeHints -structure. -Note that all fields in the -.PN XSizeHints -structure are initially set to zero. -If insufficient memory is available, -.PN XAllocSizeHints -returns NULL. -To free the memory allocated to this structure, -use -.PN XFree . -.LP -The -.PN XSizeHints -structure contains: -.LP -.sM -/* Size hints mask bits */ -.TS -lw(.5i) lw(1.1i) lw(1.5i) lw(3.1i). -T{ -#define -T} T{ -.PN USPosition -T} T{ -(1L << 0) -T} T{ -/* user specified x, y */ -T} -T{ -#define -T} T{ -.PN USSize -T} T{ -(1L << 1) -T} T{ -/* user specified width, height */ -T} -T{ -#define -T} T{ -.PN PPosition -T} T{ -(1L << 2) -T} T{ -/* program specified position */ -T} -T{ -#define -T} T{ -.PN PSize -T} T{ -(1L << 3) -T} T{ -/* program specified size */ -T} -T{ -#define -T} T{ -.PN PMinSize -T} T{ -(1L << 4) -T} T{ -/* program specified minimum size */ -T} -T{ -#define -T} T{ -.PN PMaxSize -T} T{ -(1L << 5) -T} T{ -/* program specified maximum size */ -T} -T{ -#define -T} T{ -.PN PResizeInc -T} T{ -(1L << 6) -T} T{ -/* program specified resize increments */ -T} -T{ -#define -T} T{ -.PN PAspect -T} T{ -(1L << 7) -T} T{ -/* program specified min and max aspect ratios */ -T} -T{ -#define -T} T{ -.PN PBaseSize -T} T{ -(1L << 8) -T} -T{ -#define -T} T{ -.PN PWinGravity -T} T{ -(1L << 9) -T} -T{ -#define -T} T{ -.PN PAllHints -T} T{ -(PPosition|PSize| -.br -PMinSize|PMaxSize| -.br -PResizeInc|PAspect) -T} T{ -T} -.TE -.IN "XSizeHints" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -/* Values */ - -typedef struct { - long flags; /* marks which fields in this structure are defined */ - int x, y; /* Obsolete */ - int width, height; /* Obsolete */ - int min_width, min_height; - int max_width, max_height; - int width_inc, height_inc; - struct { - int x; /* numerator */ - int y; /* denominator */ - } min_aspect, max_aspect; - int base_width, base_height; - int win_gravity; - /* this structure may be extended in the future */ -} XSizeHints; -.De -.LP -.eM -The x, y, width, and height members are now obsolete -and are left solely for compatibility reasons. -The min_width and min_height members specify the -minimum window size that still allows the application to be useful. -The max_width and max_height members specify the maximum window size. -The width_inc and height_inc members define an arithmetic progression of -sizes (minimum to maximum) into which the window prefers to be resized. -The min_aspect and max_aspect members are expressed -as ratios of x and y, -and they allow an application to specify the range of aspect -ratios it prefers. -The base_width and base_height members define the desired size of the window. -The window manager will interpret the position of the window -and its border width to position the point of the outer rectangle -of the overall window specified by the win_gravity member. -The outer rectangle of the window includes any borders or decorations -supplied by the window manager. -In other words, -if the window manager decides to place the window where the client asked, -the position on the parent window's border named by the win_gravity -will be placed where the client window would have been placed -in the absence of a window manager. -.LP -Note that use of the -.PN PAllHints -macro is highly discouraged. -.sp -.LP -To set a window's WM_NORMAL_HINTS property, use -.PN XSetWMNormalHints . -.IN "XSetWMNormalHints" "" "@DEF@" -.sM -.FD 0 -void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints\fP 1i -Specifies the size hints for the window in its normal state. -.LP -.eM -The -.PN XSetWMNormalHints -function replaces the size hints for the WM_NORMAL_HINTS property -on the specified window. -If the property does not already exist, -.PN XSetWMNormalHints -sets the size hints for the WM_NORMAL_HINTS property on the specified window. -The property is stored with a type of WM_SIZE_HINTS and a format of 32. -.LP -.PN XSetWMNormalHints -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.sp -.LP -To read a window's WM_NORMAL_HINTS property, use -.PN XGetWMNormalHints . -.IN "XGetWMNormalHints" "" "@DEF@" -.sM -.FD 0 -Status XGetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \ -\fIsupplied_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints_return\fP\^; -.br - long *\fIsupplied_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints_return\fP 1i -Returns the size hints for the window in its normal state. -.IP \fIsupplied_return\fP 1i -Returns the hints that were supplied by the user. -.LP -.eM -The -.PN XGetWMNormalHints -function returns the size hints stored in the WM_NORMAL_HINTS property -on the specified window. -If the property is of type WM_SIZE_HINTS, is of format 32, -and is long enough to contain either an old (pre-ICCCM) -or new size hints structure, -.PN XGetWMNormalHints -sets the various fields of the -.PN XSizeHints -structure, sets the supplied_return argument to the list of fields -that were supplied by the user (whether or not they contained defined values), -and returns a nonzero status. -Otherwise, it returns a zero status. -.LP -If -.PN XGetWMNormalHints -returns successfully and a pre-ICCCM size hints property is read, -the supplied_return argument will contain the following bits: -.LP -.Ds -(USPosition|USSize|PPosition|PSize|PMinSize| - PMaxSize|PResizeInc|PAspect) -.De -.LP -If the property is large enough to contain the base size -and window gravity fields as well, -the supplied_return argument will also contain the following bits: -.LP -.Ds -PBaseSize|PWinGravity -.De -.LP -.PN XGetWMNormalHints -can generate a -.PN BadWindow -error. -.sp -.LP -To set a window's WM_SIZE_HINTS property, use -.PN XSetWMSizeHints . -.IN "XSetWMSizeHints" "" "@DEF@" -.sM -.FD 0 -void XSetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints\fP 1i -Specifies the -.PN XSizeHints -structure to be used. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XSetWMSizeHints -function replaces the size hints for the specified property -on the named window. -If the specified property does not already exist, -.PN XSetWMSizeHints -sets the size hints for the specified property -on the named window. -The property is stored with a type of WM_SIZE_HINTS and a format of 32. -To set a window's normal size hints, -you can use the -.PN XSetWMNormalHints -function. -.LP -.PN XSetWMSizeHints -can generate -.PN BadAlloc , -.PN BadAtom , -and -.PN BadWindow -errors. -.sp -.LP -To read a window's WM_SIZE_HINTS property, use -.PN XGetWMSizeHints . -.IN "XGetWMSizeHints" "" "@DEF@" -.sM -.FD 0 -Status XGetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \ -\fIsupplied_return\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XSizeHints *\fIhints_return\fP\^; -.br - long *\fIsupplied_return\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIhints_return\fP 1i -Returns the -.PN XSizeHints -structure. -.IP \fIsupplied_return\fP 1i -Returns the hints that were supplied by the user. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XGetWMSizeHints -function returns the size hints stored in the specified property -on the named window. -If the property is of type WM_SIZE_HINTS, is of format 32, -and is long enough to contain either an old (pre-ICCCM) -or new size hints structure, -.PN XGetWMSizeHints -sets the various fields of the -.PN XSizeHints -structure, sets the supplied_return argument to the -list of fields that were supplied by the user -(whether or not they contained defined values), -and returns a nonzero status. -Otherwise, it returns a zero status. -To get a window's normal size hints, -you can use the -.PN XGetWMNormalHints -function. -.LP -If -.PN XGetWMSizeHints -returns successfully and a pre-ICCCM size hints property is read, -the supplied_return argument will contain the following bits: -.LP -.Ds -(USPosition|USSize|PPosition|PSize|PMinSize| - PMaxSize|PResizeInc|PAspect) -.De -.LP -If the property is large enough to contain the base size -and window gravity fields as well, -the supplied_return argument will also contain the following bits: -.LP -.Ds -PBaseSize|PWinGravity -.De -.LP -.PN XGetWMSizeHints -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.NH 3 -Setting and Reading the WM_CLASS Property -.XS -\*(SN Setting and Reading the WM_CLASS Property -.XE -.LP -Xlib provides functions that you can use to set and get -the WM_CLASS property for a given window. -These functions use the -.PN XClassHint -structure, which is defined in the -.hN X11/Xutil.h -header file. -.sp -.LP -To allocate an -.PN XClassHint -structure, use -.PN XAllocClassHint . -.IN "XAllocClassHint" "" "@DEF@" -.sM -.FD 0 -XClassHint *XAllocClassHint\^(\|) -.FN -.LP -.eM -The -.PN XAllocClassHint -function allocates and returns a pointer to an -.PN XClassHint -structure. -Note that the pointer fields in the -.PN XClassHint -structure are initially set to NULL. -If insufficient memory is available, -.PN XAllocClassHint -returns NULL. -To free the memory allocated to this structure, -use -.PN XFree . -.LP -The -.PN XClassHint -contains: -.LP -.sM -.IN "XClassHint" "" "@DEF@" -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - char *res_name; - char *res_class; -} XClassHint; -.De -.LP -.eM -The res_name member contains the application name, -and the res_class member contains the application class. -Note that the name set in this property may differ from the name set as WM_NAME. -That is, WM_NAME specifies what should be displayed in the title bar and, -therefore, can contain temporal information (for example, the name of -a file currently in an editor's buffer). -On the other hand, -the name specified as part of WM_CLASS is the formal name of the application -that should be used when retrieving the application's resources from the -resource database. -.LP -.sp -To set a window's WM_CLASS property, use -.PN XSetClassHint . -.IN "XSetClassHint" "" "@DEF@" -.sM -.FD 0 -XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XClassHint *\fIclass_hints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIclass_hints\fP 1i -Specifies the -.PN XClassHint -structure that is to be used. -.LP -.eM -The -.PN XSetClassHint -function sets the class hint for the specified window. -If the strings are not in the Host Portable Character Encoding, -the result is implementation-dependent. -.LP -.PN XSetClassHint -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To read a window's WM_CLASS property, use -.PN XGetClassHint . -.IN "XGetClassHint" "" "@DEF@" -.sM -.FD 0 -Status XGetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP; -.br - XClassHint *\fIclass_hints_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIclass_hints_return\fP 1i -Returns the -.PN XClassHint -structure. -.LP -.eM -The -.PN XGetClassHint -function returns the class hint of the specified window to the members -of the supplied structure. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned strings are in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -It returns a nonzero status on success; -otherwise, it returns a zero status. -To free res_name and res_class when finished with the strings, -use -.PN XFree -on each individually. -.LP -.PN XGetClassHint -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_TRANSIENT_FOR Property -.XS -\*(SN Setting and Reading the WM_TRANSIENT_FOR Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_TRANSIENT_FOR property for a given window. -.LP -.sp -To set a window's WM_TRANSIENT_FOR property, use -.PN XSetTransientForHint . -.IN "XSetTransientForHint" "" "@DEF@" -.sM -.FD 0 -XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window \fIprop_window\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIprop_window\fP 1i -Specifies the window that the WM_TRANSIENT_FOR property is to be set to. -.LP -.eM -The -.PN XSetTransientForHint -function sets the WM_TRANSIENT_FOR property of the specified window to the -specified prop_window. -.LP -.PN XSetTransientForHint -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To read a window's WM_TRANSIENT_FOR property, use -.PN XGetTransientForHint . -.IN "XGetTransientForHint" "" "@DEF@" -.sM -.FD 0 -Status XGetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window *\fIprop_window_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIprop_window_return\fP 1i -Returns the WM_TRANSIENT_FOR property of the specified window. -.LP -.eM -The -.PN XGetTransientForHint -function returns the WM_TRANSIENT_FOR property for the specified window. -It returns a nonzero status on success; -otherwise, it returns a zero status. -.LP -.PN XGetTransientForHint -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_PROTOCOLS Property -.XS -\*(SN Setting and Reading the WM_PROTOCOLS Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_PROTOCOLS property for a given window. -.LP -.sp -To set a window's WM_PROTOCOLS property, use -.PN XSetWMProtocols . -.IN "XSetWMProtocols" "" "@DEF@" -.sM -.FD 0 -Status XSetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols\fP, \ -\fIcount\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Atom *\fIprotocols\fP\^; -.br - int \fIcount\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIprotocols\fP 1i -Specifies the list of protocols. -.ds Cn protocols in the list -.IP \fIcount\fP 1i -Specifies the number of \*(Cn. -.LP -.eM -The -.PN XSetWMProtocols -function replaces the WM_PROTOCOLS property on the specified window -with the list of atoms specified by the protocols argument. -If the property does not already exist, -.PN XSetWMProtocols -sets the WM_PROTOCOLS property on the specified window -to the list of atoms specified by the protocols argument. -The property is stored with a type of ATOM and a format of 32. -If it cannot intern the WM_PROTOCOLS atom, -.PN XSetWMProtocols -returns a zero status. -Otherwise, it returns a nonzero status. -.LP -.PN XSetWMProtocols -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.sp -.LP -To read a window's WM_PROTOCOLS property, use -.PN XGetWMProtocols . -.IN "XGetWMProtocols" "" "@DEF@" -.sM -.FD 0 -Status XGetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols_return\fP, \ -\fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Atom **\fIprotocols_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIprotocols_return\fP 1i -Returns the list of protocols. -.ds Cn protocols in the list -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XGetWMProtocols -function returns the list of atoms stored in the WM_PROTOCOLS property -on the specified window. -These atoms describe window manager protocols in which the owner -of this window is willing to participate. -If the property exists, is of type ATOM, is of format 32, -and the atom WM_PROTOCOLS can be interned, -.PN XGetWMProtocols -sets the protocols_return argument to a list of atoms, -sets the count_return argument to the number of elements in the list, -and returns a nonzero status. -Otherwise, it sets neither of the return arguments -and returns a zero status. -To release the list of atoms, use -.PN XFree . -.LP -.PN XGetWMProtocols -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_COLORMAP_WINDOWS Property -.XS -\*(SN Setting and Reading the WM_COLORMAP_WINDOWS Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_COLORMAP_WINDOWS property for a given window. -.sp -.LP -To set a window's WM_COLORMAP_WINDOWS property, use -.PN XSetWMColormapWindows . -.IN "XSetWMColormapWindows" "" "@DEF@" -.sM -.FD 0 -Status XSetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \ -\fIcolormap_windows\fP, \fIcount\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window *\fIcolormap_windows\fP\^; -.br - int \fIcount\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIcolormap_windows\fP 1i -Specifies the list of windows. -.ds Cn windows in the list -.IP \fIcount\fP 1i -Specifies the number of \*(Cn. -.LP -.eM -The -.PN XSetWMColormapWindows -function replaces the WM_COLORMAP_WINDOWS property on the specified -window with the list of windows specified by the colormap_windows argument. -If the property does not already exist, -.PN XSetWMColormapWindows -sets the WM_COLORMAP_WINDOWS property on the specified -window to the list of windows specified by the colormap_windows argument. -The property is stored with a type of WINDOW and a format of 32. -If it cannot intern the WM_COLORMAP_WINDOWS atom, -.PN XSetWMColormapWindows -returns a zero status. -Otherwise, it returns a nonzero status. -.LP -.PN XSetWMColormapWindows -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.sp -.LP -To read a window's WM_COLORMAP_WINDOWS property, use -.PN XGetWMColormapWindows . -.IN "XGetWMColormapWindows" "" "@DEF@" -.sM -.FD 0 -Status XGetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \ -\fIcolormap_windows_return\fP, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window **\fIcolormap_windows_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIcolormap_windows_return\fP 1i -Returns the list of windows. -.ds Cn windows in the list -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XGetWMColormapWindows -function returns the list of window identifiers stored -in the WM_COLORMAP_WINDOWS property on the specified window. -These identifiers indicate the colormaps that the window manager -may need to install for this window. -If the property exists, is of type WINDOW, is of format 32, -and the atom WM_COLORMAP_WINDOWS can be interned, -.PN XGetWMColormapWindows -sets the windows_return argument to a list of window identifiers, -sets the count_return argument to the number of elements in the list, -and returns a nonzero status. -Otherwise, it sets neither of the return arguments -and returns a zero status. -To release the list of window identifiers, use -.PN XFree . -.LP -.PN XGetWMColormapWindows -can generate a -.PN BadWindow -error. -.NH 3 -Setting and Reading the WM_ICON_SIZE Property -.XS -\*(SN Setting and Reading the WM_ICON_SIZE Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_ICON_SIZE property for a given window. -These functions use the -.PN XIconSize -.IN "XIconSize" -structure, which is defined in the -.hN X11/Xutil.h -header file. -.sp -.LP -To allocate an -.PN XIconSize -structure, use -.PN XAllocIconSize . -.IN "XAllocIconSize" "" "@DEF@" -.sM -.FD 0 -XIconSize *XAllocIconSize\^(\|) -.FN -.LP -.eM -The -.PN XAllocIconSize -function allocates and returns a pointer to an -.PN XIconSize -structure. -Note that all fields in the -.PN XIconSize -structure are initially set to zero. -If insufficient memory is available, -.PN XAllocIconSize -returns NULL. -To free the memory allocated to this structure, -use -.PN XFree . -.LP -The -.PN XIconSize -structure contains: -.LP -.sM -.IN "XIconSize" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int min_width, min_height; - int max_width, max_height; - int width_inc, height_inc; -} XIconSize; -.De -.LP -.eM -The width_inc and height_inc members define an arithmetic progression of -sizes (minimum to maximum) that represent the supported icon sizes. -.LP -.sp -To set a window's WM_ICON_SIZE property, use -.PN XSetIconSizes . -.IN "XSetIconSizes" "" "@DEF@" -.sM -.FD 0 -XSetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list\fP, \fIcount\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XIconSize *\fIsize_list\fP\^; -.br - int \fIcount\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIsize_list\fP 1i -Specifies the size list. -.IP \fIcount\fP 1i -Specifies the number of items in the size list. -.LP -.eM -The -.PN XSetIconSizes -function is used only by window managers to set the supported icon sizes. -.LP -.PN XSetIconSizes -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.LP -.sp -To read a window's WM_ICON_SIZE property, use -.PN XGetIconSizes . -.IN "XGetIconSizes" "" "@DEF@" -.sM -.FD 0 -Status XGetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list_return\fP, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XIconSize **\fIsize_list_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIsize_list_return\fP 1i -Returns the size list. -.IP \fIcount_return\fP 1i -Returns the number of items in the size list. -.LP -.eM -The -.PN XGetIconSizes -function returns zero if a window manager has not set icon sizes; -otherwise, it returns nonzero. -.PN XGetIconSizes -should be called by an application that -wants to find out what icon sizes would be most appreciated by the -window manager under which the application is running. -The application -should then use -.PN XSetWMHints -to supply the window manager with an icon pixmap or window in one of the -supported sizes. -To free the data allocated in size_list_return, use -.PN XFree . -.LP -.PN XGetIconSizes -can generate a -.PN BadWindow -error. -.NH 3 -Using Window Manager Convenience Functions -.XS -\*(SN Using Window Manager Convenience Functions -.XE -.LP -The -.PN XmbSetWMProperties -function stores the standard set of window manager properties, -with text properties in standard encodings -for internationalized text communication. -The standard window manager properties for a given window are -WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, -WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. -.IN "XmbSetWMProperties" "" "@DEF@" -.sM -.FD 0 -void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^, -.br - \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char *\fIwindow_name\fP\^; -.br - char *\fIicon_name\fP\^; -.br - char *\fIargv\fP\^[]; -.br - int \fIargc\fP\^; -.br - XSizeHints *\fInormal_hints\fP\^; -.br - XWMHints *\fIwm_hints\fP\^; -.br - XClassHint *\fIclass_hints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwindow_name\fP 1i -Specifies the window name, -which should be a null-terminated string. -.IP \fIicon_name\fP 1i -Specifies the icon name, -which should be a null-terminated string. -.IP \fIargv\fP 1i -Specifies the application's argument list. -.IP \fIargc\fP 1i -Specifies the number of arguments. -.IP \fIhints\fP 1i -Specifies the size hints for the window in its normal state. -.IP \fIwm_hints\fP 1i -Specifies the -.PN XWMHints -structure to be used. -.IP \fIclass_hints\fP 1i -Specifies the -.PN XClassHint -structure to be used. -.LP -.eM -The -.PN XmbSetWMProperties -convenience function provides a simple programming interface -for setting those essential window properties that are used -for communicating with other clients -(particularly window and session managers). -.LP -If the window_name argument is non-NULL, -.PN XmbSetWMProperties -sets the WM_NAME property. -If the icon_name argument is non-NULL, -.PN XmbSetWMProperties -sets the WM_ICON_NAME property. -The window_name and icon_name arguments are null-terminated strings -in the encoding of the current locale. -If the arguments can be fully converted to the STRING encoding, -the properties are created with type ``STRING''; -otherwise, the arguments are converted to Compound Text, -and the properties are created with type ``COMPOUND_TEXT''. -.LP -If the normal_hints argument is non-NULL, -.PN XmbSetWMProperties -calls -.PN XSetWMNormalHints , -which sets the WM_NORMAL_HINTS property (see section 14.1.7). -If the wm_hints argument is non-NULL, -.PN XmbSetWMProperties -calls -.PN XSetWMHints , -which sets the WM_HINTS property (see section 14.1.6). -.LP -If the argv argument is non-NULL, -.PN XmbSetWMProperties -sets the WM_COMMAND property from argv and argc. -An argc of zero indicates a zero-length command. -.LP -The hostname of the machine is stored using -.PN XSetWMClientMachine -(see section 14.2.2). -.LP -If the class_hints argument is non-NULL, -.PN XmbSetWMProperties -sets the WM_CLASS property. -If the res_name member in the -.PN XClassHint -structure is set to the NULL pointer and the RESOURCE_NAME -environment variable is set, -the value of the environment variable is substituted for res_name. -If the res_name member is NULL, -the environment variable is not set, and argv and argv[0] are set, -then the value of argv[0], stripped of any directory prefixes, -is substituted for res_name. -.LP -It is assumed that the supplied class_hints.res_name and argv, -the RESOURCE_NAME environment variable, and the hostname of the machine -are in the encoding of the locale announced for the LC_CTYPE category -(on POSIX-compliant systems, the LC_CTYPE, else LANG environment variable). -The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties -are typed according to the local host locale announcer. -No encoding conversion is performed prior to storage in the properties. -.LP -For clients that need to process the property text in a locale, -.PN XmbSetWMProperties -sets the WM_LOCALE_NAME property to be the name of the current locale. -The name is assumed to be in the Host Portable Character Encoding -and is converted to STRING for storage in the property. -.LP -.PN XmbSetWMProperties -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.sp -.LP -To set a window's standard window manager properties -with strings in client-specified encodings, use -.PN XSetWMProperties . -The standard window manager properties for a given window are -WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, -WM_COMMAND, and WM_CLIENT_MACHINE. -.IN "XSetWMProperties" "" "@DEF@" -.sM -.FD 0 -void XSetWMProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \ -\fIicon_name\fP, \fIargv\fP, \fIargc\fP, \fInormal_hints\fP, \fIwm_hints\fP, \ -\fIclass_hints\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fIwindow_name\fP\^; -.br - XTextProperty *\fIicon_name\fP\^; -.br - char **\fIargv\fP\^; -.br - int \fIargc\fP\^; -.br - XSizeHints *\fInormal_hints\fP\^; -.br - XWMHints *\fIwm_hints\fP\^; -.br - XClassHint *\fIclass_hints\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIwindow_name\fP 1i -Specifies the window name, -which should be a null-terminated string. -.IP \fIicon_name\fP 1i -Specifies the icon name, -which should be a null-terminated string. -.IP \fIargv\fP 1i -Specifies the application's argument list. -.IP \fIargc\fP 1i -Specifies the number of arguments. -.IP \fInormal_hints\fP 1i -Specifies the size hints for the window in its normal state. -.IP \fIwm_hints\fP 1i -Specifies the -.PN XWMHints -structure to be used. -.IP \fIclass_hints\fP 1i -Specifies the -.PN XClassHint -structure to be used. -.LP -.eM -The -.PN XSetWMProperties -convenience function provides a single programming interface -for setting those essential window properties that are used -for communicating with other clients (particularly window and session -managers). -.LP -If the window_name argument is non-NULL, -.PN XSetWMProperties -calls -.PN XSetWMName , -which, in turn, sets the WM_NAME property (see section 14.1.4). -If the icon_name argument is non-NULL, -.PN XSetWMProperties -calls -.PN XSetWMIconName , -which sets the WM_ICON_NAME property (see section 14.1.5). -If the argv argument is non-NULL, -.PN XSetWMProperties -calls -.PN XSetCommand , -which sets the WM_COMMAND property (see section 14.2.1). -Note that an argc of zero is allowed to indicate a zero-length command. -Note also that the hostname of this machine is stored using -.PN XSetWMClientMachine -(see section 14.2.2). -.LP -If the normal_hints argument is non-NULL, -.PN XSetWMProperties -calls -.PN XSetWMNormalHints , -which sets the WM_NORMAL_HINTS property (see section 14.1.7). -If the wm_hints argument is non-NULL, -.PN XSetWMProperties -calls -.PN XSetWMHints , -which sets the WM_HINTS property (see section 14.1.6). -.LP -If the class_hints argument is non-NULL, -.PN XSetWMProperties -calls -.PN XSetClassHint , -which sets the WM_CLASS property (see section 14.1.8). -If the res_name member in the -.PN XClassHint -structure is set to the NULL pointer and the RESOURCE_NAME environment -variable is set, -then the value of the environment variable is substituted for res_name. -If the res_name member is NULL, -the environment variable is not set, -and argv and argv[0] are set, -then the value of argv[0], stripped of -any directory prefixes, is substituted for res_name. -.LP -.PN XSetWMProperties -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.NH 2 -Client to Session Manager Communication -.XS -\*(SN Client to Session Manager Communication -.XE -.LP -This section discusses how to: -.IP \(bu 5 -Set and read the WM_COMMAND property -.IP \(bu 5 -Set and read the WM_CLIENT_MACHINE property -.NH 3 -Setting and Reading the WM_COMMAND Property -.XS -\*(SN Setting and Reading the WM_COMMAND Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_COMMAND property for a given window. -.sp -.LP -To set a window's WM_COMMAND property, use -.PN XSetCommand . -.IN "XSetCommand" "" "@DEF@" -.sM -.FD 0 -XSetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv\fP, \fIargc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char **\fIargv\fP\^; -.br - int \fIargc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIargv\fP 1i -Specifies the application's argument list. -.IP \fIargc\fP 1i -Specifies the number of arguments. -.LP -.eM -The -.PN XSetCommand -function sets the command and arguments used to invoke the -application. -(Typically, argv is the argv array of your main program.) -If the strings are not in the Host Portable Character Encoding, -the result is implementation-dependent. -.LP -.PN XSetCommand -can generate -.PN BadAlloc -and -.PN BadWindow -errors. -.sp -.LP -To read a window's WM_COMMAND property, use -.PN XGetCommand . -.IN "XGetCommand" "" "@DEF@" -.sM -.FD 0 -Status XGetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv_return\fP, \ -\fIargc_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - char ***\fIargv_return\fP\^; -.br - int *\fIargc_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIargv_return\fP 1i -Returns the application's argument list. -.IP \fIargc_return\fP 1i -Returns the number of arguments returned. -.LP -.eM -The -.PN XGetCommand -function reads the WM_COMMAND property from the specified window -and returns a string list. -If the WM_COMMAND property exists, -it is of type STRING and format 8. -If sufficient memory can be allocated to contain the string list, -.PN XGetCommand -fills in the argv_return and argc_return arguments -and returns a nonzero status. -Otherwise, it returns a zero status. -If the data returned by the server is in the Latin Portable Character Encoding, -then the returned strings are in the Host Portable Character Encoding. -Otherwise, the result is implementation-dependent. -To free the memory allocated to the string list, use -.PN XFreeStringList . -.NH 3 -Setting and Reading the WM_CLIENT_MACHINE Property -.XS -\*(SN Setting and Reading the WM_CLIENT_MACHINE Property -.XE -.LP -Xlib provides functions that you can use to set and read -the WM_CLIENT_MACHINE property for a given window. -.sp -.LP -To set a window's WM_CLIENT_MACHINE property, use -.PN XSetWMClientMachine . -.IN "XSetWMClientMachine" "" "@DEF@" -.sM -.FD 0 -void XSetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop\fP 1i -Specifies the -.PN XTextProperty -structure to be used. -.LP -.eM -The -.PN XSetWMClientMachine -convenience function calls -.PN XSetTextProperty -to set the WM_CLIENT_MACHINE property. -.sp -.LP -To read a window's WM_CLIENT_MACHINE property, use -.PN XGetWMClientMachine . -.IN "XGetWMClientMachine" "" "@DEF@" -.sM -.FD 0 -Status XGetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XTextProperty *\fItext_prop_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fItext_prop_return\fP 1i -Returns the -.PN XTextProperty -structure. -.LP -.eM -The -.PN XGetWMClientMachine -convenience function performs an -.PN XGetTextProperty -on the WM_CLIENT_MACHINE property. -It returns a nonzero status on success; -otherwise, it returns a zero status. -.NH 2 -Standard Colormaps -.XS -\*(SN Standard Colormaps -.XE -.LP -Applications with color palettes, smooth-shaded drawings, or digitized -images demand large numbers of colors. -In addition, these applications often require an efficient mapping -from color triples to pixel values that display the appropriate colors. -.LP -As an example, consider a three-dimensional display program that wants -to draw a smoothly shaded sphere. -At each pixel in the image of the sphere, -the program computes the intensity and color of light -reflected back to the viewer. -The result of each computation is a triple of red, green, and blue (RGB) -coefficients in the range 0.0 to 1.0. -To draw the sphere, the program needs a colormap that provides a -large range of uniformly distributed colors. -The colormap should be arranged so that the program can -convert its RGB triples into pixel values very quickly, -because drawing the entire sphere requires many such -conversions. -.LP -On many current workstations, -the display is limited to 256 or fewer colors. -Applications must allocate colors carefully, -not only to make sure they cover the entire range they need -but also to make use of as many of the available colors as possible. -On a typical X display, -many applications are active at once. -Most workstations have only one hardware look-up table for colors, -so only one application colormap can be installed at a given time. -The application using the installed colormap is displayed correctly, -and the other applications go technicolor and are -displayed with false colors. -.LP -As another example, consider a user who is running an -image processing program to display earth-resources data. -The image processing program needs a colormap set up with 8 reds, -8 greens, and 4 blues, for a total of 256 colors. -Because some colors are already in use in the default colormap, -the image processing program allocates and installs a new colormap. -.LP -The user decides to alter some of the colors in the image -by invoking a color palette program to mix and choose colors. -The color palette program also needs a -colormap with eight reds, eight greens, and four blues, so just like -the image processing program, it must allocate and -install a new colormap. -.LP -Because only one colormap can be installed at a time, -the color palette may be displayed incorrectly -whenever the image processing program is active. -Conversely, whenever the palette program is active, -the image may be displayed incorrectly. -The user can never match or compare colors in the palette and image. -Contention for colormap resources can be reduced if applications -with similar color needs share colormaps. -.LP -The image processing program and the color palette program -could share the same colormap if there existed a convention that described -how the colormap was set up. -Whenever either program was active, -both would be displayed correctly. -.LP -The standard colormap properties define a set of commonly used -colormaps. -Applications that share these colormaps and conventions display -true colors more often and provide a better interface to the user. -.LP -Standard colormaps allow applications to share commonly used color -resources. -This allows many applications to be displayed in true colors -simultaneously, even when each application needs an entirely filled -colormap. -.LP -Several standard colormaps are described in this section. -Usually, a window manager creates these colormaps. -Applications should use the standard colormaps if they already exist. -.sp -.LP -To allocate an -.PN XStandardColormap -structure, use -.PN XAllocStandardColormap . -.IN "XAllocStandardColormap" "" "@DEF@" -.sM -.FD 0 -XStandardColormap *XAllocStandardColormap\^(\|) -.FN -.LP -.eM -The -.PN XAllocStandardColormap -function allocates and returns a pointer to an -.PN XStandardColormap -structure. -Note that all fields in the -.PN XStandardColormap -structure are initially set to zero. -If insufficient memory is available, -.PN XAllocStandardColormap -returns NULL. -To free the memory allocated to this structure, -use -.PN XFree . -.LP -The -.PN XStandardColormap -structure contains: -.LP -.sM -/* Hints */ -.TS -lw(.5i) lw(2i) lw(1i). -T{ -#define -T} T{ -.PN ReleaseByFreeingColormap -T} T{ -( (XID) 1L) -T} -.TE -/* Values */ -.IN "XStandardColormap" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - Colormap colormap; - unsigned long red_max; - unsigned long red_mult; - unsigned long green_max; - unsigned long green_mult; - unsigned long blue_max; - unsigned long blue_mult; - unsigned long base_pixel; - VisualID visualid; - XID killid; -} XStandardColormap; -.De -.LP -.eM -The colormap member is the colormap created by the -.PN XCreateColormap -function. -The red_max, green_max, and blue_max members give the maximum -red, green, and blue values, respectively. -Each color coefficient ranges from zero to its max, inclusive. -For example, -a common colormap allocation is 3/3/2 (3 planes for red, 3 -planes for green, and 2 planes for blue). -This colormap would have red_max = 7, green_max = 7, -and blue_max = 3. -An alternate allocation that uses only 216 colors is red_max = 5, -green_max = 5, and blue_max = 5. -.LP -The red_mult, green_mult, and blue_mult members give the -scale factors used to compose a full pixel value. -(See the discussion of the base_pixel members for further information.) -For a 3/3/2 allocation, red_mult might be 32, -green_mult might be 4, and blue_mult might be 1. -For a 6-colors-each allocation, red_mult might be 36, -green_mult might be 6, and blue_mult might be 1. -.LP -The base_pixel member gives the base pixel value used to -compose a full pixel value. -Usually, the base_pixel is obtained from a call to the -.PN XAllocColorPlanes -function. -Given integer red, green, and blue coefficients in their appropriate -ranges, one then can compute a corresponding pixel value by -using the following expression: -.LP -.Ds -.TA .5i 1.5i -.ta .5i 1.5i -(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF -.De -.LP -For -.PN GrayScale -colormaps, -only the colormap, red_max, red_mult, -and base_pixel members are defined. -The other members are ignored. -To compute a -.PN GrayScale -pixel value, use the following expression: -.LP -.Ds -.TA .5i 1.5i -.ta .5i 1.5i -(gray * red_mult + base_pixel) & 0xFFFFFFFF -.De -.LP -Negative multipliers can be represented by converting the 2's -complement representation of the multiplier into an unsigned long and -storing the result in the appropriate _mult field. -The step of masking by 0xFFFFFFFF effectively converts the resulting -positive multiplier into a negative one. -The masking step will take place automatically on many machine architectures, -depending on the size of the integer type used to do the computation. -.LP -The visualid member gives the ID number of the visual from which the -colormap was created. -The killid member gives a resource ID that indicates whether -the cells held by this standard colormap are to be released -by freeing the colormap ID or by calling the -.PN XKillClient -function on the indicated resource. -(Note that this method is necessary for allocating out of an existing colormap.) -.LP -The properties containing the -.PN XStandardColormap -information have -the type RGB_COLOR_MAP. -.LP -The remainder of this section discusses standard colormap properties and atoms -as well as how to manipulate standard colormaps. -.NH 3 -Standard Colormap Properties and Atoms -.XS -\*(SN Standard Colormap Properties and Atoms -.XE -.LP -.IN "Standard Colormaps" -.IN "Colormaps" "standard" -Several standard colormaps are available. -Each standard colormap is defined by a property, -and each such property is identified by an atom. -The following list names the atoms and describes the colormap -associated with each one. -The -.hN X11/Xatom.h -header file contains the definitions for each of the following atoms, -which are prefixed with XA_. -.IP RGB_DEFAULT_MAP 5 -This atom names a property. -The value of the property is an array of -.PN XStandardColormap -structures. -Each entry in the array describes an RGB subset of the default color -map for the Visual specified by visual_id. -.IP -Some applications only need a few RGB colors and -may be able to allocate them from the system default colormap. -This is the ideal situation because the fewer colormaps that are -active in the system the more applications are displayed -with correct colors at all times. -.IP -A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays -is 6 reds, 6 greens, and 6 blues. -This gives 216 uniformly distributed colors -(6 intensities of 36 different hues) and still leaves 40 elements -of a 256-element colormap available for special-purpose colors -for text, borders, and so on. -.IP RGB_BEST_MAP 5 -.br -This atom names a property. -The value of the property is an -.PN XStandardColormap . -.IP -The property defines the best RGB colormap available on -the screen. -(Of course, this is a subjective evaluation.) -Many image processing and three-dimensional applications need to -use all available colormap cells and to distribute as many -perceptually distinct colors as possible over those cells. -This implies that there may be more green values available than -red, as well as more green or red than blue. -.IP -For an 8-plane -.PN PseudoColor -visual, -RGB_BEST_MAP is likely to be a 3/3/2 allocation. -For a 24-plane -.PN DirectColor -visual, -RGB_BEST_MAP is normally an 8/8/8 allocation. -.IP RGB_RED_MAP 5 -.br -.ns -.IP RGB_GREEN_MAP 5 -.br -.ns -.IP RGB_BLUE_MAP 5 -These atoms name properties. -The value of each property is an -.PN XStandardColormap . -.IP -The properties define all-red, all-green, and all-blue -colormaps, respectively. -These maps are used by applications that want to make color-separated -images. -For example, a user might generate a full-color image -on an 8-plane display both by rendering an image three times -(once with high color resolution in red, once with green, -and once with blue) and by multiply exposing a single frame in a camera. -.IP RGB_GRAY_MAP 5 -This atom names a property. -The value of the property is an -.PN XStandardColormap . -.IP -The property describes the best -.PN GrayScale -colormap available on the screen. -As previously mentioned, -only the colormap, red_max, red_mult, and base_pixel members of the -.PN XStandardColormap -structure are used for -.PN GrayScale -colormaps. -.NH 3 -Setting and Obtaining Standard Colormaps -.XS -\*(SN Setting and Obtaining Standard Colormaps -.XE -.LP -Xlib provides functions that you can use to set and obtain an -.PN XStandardColormap -structure. -.sp -.LP -To set an -.PN XStandardColormap -structure, use -.PN XSetRGBColormaps . -.IN "XSetRGBColormaps" "" "@DEF@" -.sM -.FD 0 -void XSetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap\fP, \ -\fIcount\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XStandardColormap *\fIstd_colormap\fP\^; -.br - int \fIcount\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIstd_colormap\fP 1i -Specifies the -.PN XStandardColormap -structure to be used. -.ds Cn colormaps -.IP \fIcount\fP 1i -Specifies the number of \*(Cn. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XSetRGBColormaps -function replaces the RGB colormap definition in the specified property -on the named window. -If the property does not already exist, -.PN XSetRGBColormaps -sets the RGB colormap definition in the specified property -on the named window. -The property is stored with a type of RGB_COLOR_MAP and a format of 32. -Note that it is the caller's responsibility to honor the ICCCM -restriction that only RGB_DEFAULT_MAP contain more than one definition. -.LP -The -.PN XSetRGBColormaps -function usually is only used by window or session managers. -To create a standard colormap, -follow this procedure: -.IP 1. 5 -Open a new connection to the same server. -.IP 2. 5 -Grab the server. -.IP 3. 5 -See if the property is on the property list of the root window for the screen. -.IP 4. 5 -If the desired property is not present: -.RS -.IP \(bu 5 -Create a colormap (unless you are using the default colormap of the screen). -.IP \(bu 5 -Determine the color characteristics of the visual. -.IP \(bu 5 -Allocate cells in the colormap (or create it with -.PN AllocAll ). -.IP \(bu 5 -Call -.PN XStoreColors -to store appropriate color values in the colormap. -.IP \(bu 5 -Fill in the descriptive members in the -.PN XStandardColormap -structure. -.IP \(bu 5 -Attach the property to the root window. -.IP \(bu 5 -Use -.PN XSetCloseDownMode -to make the resource permanent. -.RE -.IP 5. 5 -Ungrab the server. -.LP -.PN XSetRGBColormaps -can generate -.PN BadAlloc , -.PN BadAtom , -and -.PN BadWindow -errors. -.sp -.LP -To obtain the -.PN XStandardColormap -structure associated with the specified property, use -.PN XGetRGBColormaps . -.IN "XGetRGBColormaps" "" "@DEF@" -.sM -.FD 0 -Status XGetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap_return\fP, \ -\fIcount_return\fP, \fIproperty\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - XStandardColormap **\fIstd_colormap_return\fP\^; -.br - int *\fIcount_return\fP\^; -.br - Atom \fIproperty\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIstd_colormap_return\fP 1i -Returns the -.PN XStandardColormap -structure. -.ds Cn colormaps -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.IP \fIproperty\fP 1i -Specifies the property name. -.LP -.eM -The -.PN XGetRGBColormaps -function returns the RGB colormap definitions stored -in the specified property on the named window. -If the property exists, is of type RGB_COLOR_MAP, is of format 32, -and is long enough to contain a colormap definition, -.PN XGetRGBColormaps -allocates and fills in space for the returned colormaps -and returns a nonzero status. -If the visualid is not present, -.PN XGetRGBColormaps -assumes the default visual for the screen on which the window is located; -if the killid is not present, -.PN None -is assumed, which indicates that the resources cannot be released. -Otherwise, -none of the fields are set, and -.PN XGetRGBColormaps -returns a zero status. -Note that it is the caller's responsibility to honor the ICCCM -restriction that only RGB_DEFAULT_MAP contain more than one definition. -.LP -.PN XGetRGBColormaps -can generate -.PN BadAtom -and -.PN BadWindow -errors. -.bp diff --git a/libX11/specs/libX11/CH14.xml b/libX11/specs/libX11/CH14.xml new file mode 100644 index 000000000..dd301bf9f --- /dev/null +++ b/libX11/specs/libX11/CH14.xml @@ -0,0 +1,5190 @@ +<chapter id="inter_client_communication_functions">
+<title>Inter-Client Communication Functions</title>
+<para>
+The Inter-Client Communication Conventions Manual, hereafter referred to as the <acronym>ICCCM</acronym>,
+details the X Consortium approved conventions that govern inter-client communications. These
+conventions ensure peer-to-peer client cooperation in the use of selections, cut buffers, and shared
+resources as well as client cooperation with window and session managers. For further informa-
+tion, see the Inter-Client Communication Conventions Manual.
+</para>
+<para>
+Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym> com-
+pliant. The predefined atoms for some of these properties are defined in the <X11/Xatom.h>
+header file, where to avoid name conflicts with user symbols their #define name has an XA_ pre-
+fix. For further information about atoms and properties, see section 4.3.
+</para>
+<para>
+Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which
+peer client applications communicate with each other (see sections 4.5 and 16.6). The functions
+discussed in this chapter provide the primary programming interfaces by which client applications
+communicate with their window and session managers as well as share standard colormaps.
+</para>
+<para>
+The standard properties that are of special interest for communicating with window and session
+managers are:
+</para>
+
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Format</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>WM_CLASS</entry>
+ <entry>STRING</entry>
+ <entry>8</entry>
+ <entry>Set by application programs to allow
+ window and session managers to
+ obtain the application’s resources
+ from the resource database.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_CLIENT_MACHINE</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The string name of the machine on
+ which the client application is run-
+ ning.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_COLORMAP_WINDOWS</entry>
+ <entry>WINDOWS</entry>
+ <entry>32</entry>
+ <entry>The list of window IDs that may
+ need a different colormap from that
+ of their top-level window.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_COMMAND</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The command and arguments, null-
+ separated, used to invoke the application.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_HINTS</entry>
+ <entry>WM_HINTS</entry>
+ <entry>32</entry>
+ <entry>Additional hints set by the client for
+ use by the window manager. The C
+ type of this property is XWMHints.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_ICON_NAME</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The name to be used in an icon.</entry>
+ </row>
+ <row>
+ <entry>WM_ICON_SIZE</entry>
+ <entry>WM_ICON_SIZE</entry>
+ <entry>32</entry>
+ <entry>The window manager may set this
+ property on the root window to
+ specify the icon sizes it supports.
+ The C type of this property is
+ XIconSize.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_NAME</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The name of the application.</entry>
+ </row>
+ <row>
+ <entry>WM_NORMAL_HINTS</entry>
+ <entry>WM_NORMAL_HINTS</entry>
+ <entry>32</entry>
+ <entry>Size hints for a window in its
+ normal state. The C type of this
+ property is XSizeHints.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_PROTOCOLS</entry>
+ <entry>ATOM</entry>
+ <entry>32</entry>
+ <entry>List of atoms that identify the
+ communications protocols between the
+ client and window manager in
+ which the client is willing to participate.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_STATE</entry>
+ <entry>WM_STATE</entry>
+ <entry>32</entry>
+ <entry>Intended for communication
+ between window and session man-
+ agers only.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_TRANSIENT_FOR</entry>
+ <entry>WINDOW</entry>
+ <entry>32</entry>
+ <entry>Set by application programs to
+ indicate to the window manager that a
+ transient top-level window, such as a
+ dialog box.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The remainder of this chapter discusses:
+</para>
+
+<itemizedlist>
+ <listitem><para>Client to window manager communication</para></listitem>
+ <listitem><para>Client to session manager communication</para></listitem>
+ <listitem><para>Standard colormaps</para></listitem>
+</itemizedlist>
+
+<sect1 id="Client_to_Window_Manager_Communication">
+<title>Client to Window Manager Communication</title>
+<!-- .XS -->
+<!-- (SN Client to Window Manager Communication -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Manipulate top-level windows
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convert string lists
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read text properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_NAME property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_ICON_NAME property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_HINTS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_NORMAL_HINTS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_CLASS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_TRANSIENT_FOR property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_PROTOCOLS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_COLORMAP_WINDOWS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_ICON_SIZE property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use window manager convenience functions
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Manipulating_Top_Level_Windows">
+<title>Manipulating Top-Level Windows</title>
+<!-- .XS -->
+<!-- (SN Manipulating Top-Level Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to change the visibility or size
+of top-level windows (that is, those that were created as children
+of the root window).
+Note that the subwindows that you create are ignored by window managers.
+Therefore,
+you should use the basic window functions described in chapter 3
+to manipulate your application's subwindows.
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be iconified, use
+<function>XIconifyWindow</function>.
+<indexterm significance="preferred"><primary>XIconifyWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XIconifyWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIconifyWindow </function>
+function sends a WM_CHANGE_STATE
+<function>ClientMessage </function>
+event with a format of 32 and a first data element of
+<function>IconicState </function>
+(as described in section 4.1.4 of the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)
+and a window of w
+to the root window of the specified screen
+with an event mask set to
+<function>SubstructureNotifyMask |</function>
+<function>SubstructureRedirectMask</function>.
+Window managers may elect to receive this message and
+if the window is in its normal state,
+may treat it as a request to change the window's state from normal to iconic.
+If the WM_CHANGE_STATE property cannot be interned,
+<function>XIconifyWindow</function>
+does not send a message and returns a zero status.
+It returns a nonzero status if the client message is sent successfully;
+otherwise, it returns a zero status.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be withdrawn, use
+<function>XWithdrawWindow</function>.
+<indexterm significance="preferred"><primary>XWithdrawWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XWithdrawWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWithdrawWindow </function>
+function unmaps the specified window
+and sends a synthetic
+<function>UnmapNotify </function>
+event to the root window of the specified screen.
+Window managers may elect to receive this message
+and may treat it as a request to change the window's state to withdrawn.
+When a window is in the withdrawn state,
+neither its normal nor its iconic representations is visible.
+It returns a nonzero status if the
+<function>UnmapNotify </function>
+event is successfully sent;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XWithdrawWindow</function>
+can generate a
+<function>BadWindow</function>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be reconfigured, use
+<function>XReconfigureWMWindow</function>.
+<indexterm significance="preferred"><primary>XReconfigureWMWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XReconfigureWMWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+ <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>
+ <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWindowChanges </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XReconfigureWMWindow </function>
+function issues a
+<function>ConfigureWindow </function>
+request on the specified top-level window.
+If the stacking mode is changed and the request fails with a
+<function>BadMatch </function>
+error,
+the error is trapped by Xlib and a synthetic
+<function>ConfigureRequestEvent </function>
+containing the same configuration parameters is sent to the root
+of the specified window.
+Window managers may elect to receive this event
+and treat it as a request to reconfigure the indicated window.
+It returns a nonzero status if the request or event is successfully sent;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XReconfigureWMWindow </function>
+can generate
+<function>BadValue </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Converting_String_Lists">
+<title>Converting String Lists</title>
+<!-- .XS -->
+<!-- (SN Converting String Lists -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Many of the text properties allow a variety of types and formats.
+Because the data stored in these properties are not
+simple null-terminated strings, an
+<function>XTextProperty</function>
+structure is used to describe the encoding, type, and length of the text
+as well as its value.
+The
+<function>XTextProperty</function>
+structure contains:
+<indexterm significance="preferred"><primary>XTextProperty</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ unsigned char *value; /* property data */
+ Atom encoding; /* type of property */
+ int format; /* 8, 16, or 32 */
+ unsigned long nitems; /* number of items in value */
+} XTextProperty;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Xlib provides functions to convert localized text to or from encodings
+that support the inter-client communication conventions for text.
+In addition, functions are provided for converting between lists of pointers
+to character strings and text properties in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The functions for localized text return a signed integer error status
+that encodes
+<function>Success</function>
+as zero, specific error conditions as negative numbers, and partial conversion
+as a count of unconvertible characters.
+</para>
+
+<literallayout class="monospaced">
+
+#define #XNoMemory -1
+#define #XLocaleNotSupported -2
+#define #XConverterNotFound -3
+
+typedef enum {
+ XStringStyle, /* STRING */
+ XCompoundTextStyle, /* COMPOUND_TEXT */
+ XTextStyle, /* text in owner's encoding (current locale) */
+ XStdICCTextStyle /* STRING, else COMPOUND_TEXT */
+} XICCEncodingStyle;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To convert a list of text strings to an
+<function>XTextProperty</function>
+structure, use
+<function>XmbTextListToTextProperty</function>
+or
+<function>XwcTextListToTextProperty</function>.
+<indexterm significance="preferred"><primary>XmbTextListToTextProperty</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextListToTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbTextListToTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcTextListToTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>wchar_t<parameter> **list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of null-terminated character strings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of strings specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>style</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the manner in which the property is encoded.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextListToTextProperty</function>
+and
+<function>XwcTextListToTextProperty</function>
+functions set the specified
+<function>XTextProperty</function>
+value to a set of null-separated elements representing the concatenation
+of the specified list of null-terminated text strings.
+A final terminating null is stored at the end of the value field
+of text_prop_return but is not included in the nitems member.
+</para>
+<para>
+<!-- .LP -->
+The functions set the encoding field of text_prop_return to an
+<function>Atom </function>
+for the specified display
+naming the encoding determined by the specified style
+and convert the specified text list to this encoding for storage in
+the text_prop_return value field.
+If the style
+<function>XStringStyle</function>
+or
+<function>XCompoundTextStyle</function>
+is specified,
+this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
+If the style
+<function>XTextStyle</function>
+is specified,
+this encoding is the encoding of the current locale.
+If the style
+<function>XStdICCTextStyle</function>
+is specified,
+this encoding is ``STRING'' if the text is fully convertible to STRING,
+else ``COMPOUND_TEXT''.
+</para>
+<para>
+<!-- .LP -->
+If insufficient memory is available for the new value string,
+the functions return
+<function>XNoMemory</function>.
+If the current locale is not supported,
+the functions return
+<function>XLocaleNotSupported</function>.
+In both of these error cases,
+the functions do not set text_prop_return.
+</para>
+<para>
+<!-- .LP -->
+To determine if the functions are guaranteed not to return
+<function>XLocaleNotSupported</function>,
+use
+<function>XSupportsLocale</function>.
+</para>
+<para>
+<!-- .LP -->
+If the supplied text is not fully convertible to the specified encoding,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to an implementation-defined and
+encoding-specific default string.
+Otherwise, the functions return
+<function>Success</function>.
+Note that full convertibility to all styles except
+<function>XStringStyle</function>
+is guaranteed.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the value field, use
+<function>XFree</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of text strings from an
+<function>XTextProperty </function>
+structure, use
+<function>XmbTextPropertyToTextList</function>
+or
+<function>XwcTextPropertyToTextList</function>.
+<indexterm significance="preferred"><primary>XmbTextPropertyToTextList</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextPropertyToTextList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbTextPropertyToTextList</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>char<parameter> ***list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcTextPropertyToTextList</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>wchar_t<parameter> ***list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+functions return a list of text strings in the current locale representing the
+null-separated elements of the specified
+<function>XTextProperty</function>
+structure.
+The data in text_prop must be format 8.
+</para>
+<para>
+<!-- .LP -->
+Multiple elements of the property (for example, the strings in a disjoint
+text selection) are separated by a null byte.
+The contents of the property are not required to be null-terminated;
+any terminating null should not be included in text_prop.nitems.
+</para>
+<para>
+<!-- .LP -->
+If insufficient memory is available for the list and its elements,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return
+<function>XNoMemory</function>.
+If the current locale is not supported,
+the functions return
+<function>XLocaleNotSupported</function>.
+Otherwise, if the encoding field of text_prop is not convertible
+to the encoding of the current locale,
+the functions return
+<function>XConverterNotFound</function>.
+For supported locales,
+existence of a converter from COMPOUND_TEXT, STRING
+or the encoding of the current locale is guaranteed if
+<function>XSupportsLocale </function>
+returns
+<function>True</function>
+for the current locale (but the actual text
+may contain unconvertible characters).
+Conversion of other encodings is implementation-dependent.
+In all of these error cases,
+the functions do not set any return values.
+</para>
+<para>
+<!-- .LP -->
+Otherwise,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return the list of null-terminated text strings to list_return
+and the number of text strings to count_return.
+</para>
+<para>
+<!-- .LP -->
+If the value field of text_prop is not fully convertible to the encoding of
+the current locale,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to a string in the
+current locale that is specific to the current locale.
+To obtain the value of this string,
+use
+<function>XDefaultString</function>.
+Otherwise,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return
+<function>Success</function>.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the list and its contents returned by
+<function>XmbTextPropertyToTextList</function>,
+use
+<function>XFreeStringList</function>.
+To free the storage for the list and its contents returned by
+<function>XwcTextPropertyToTextList</function>,
+use
+<function>XwcFreeStringList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified
+wide character string list, use
+<function>XwcFreeStringList</function>.
+<indexterm significance="preferred"><primary>XwcFreeStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XwcFreeStringList</function></funcdef>
+ <paramdef>wchar_t<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of strings to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XwcFreeStringList</function>
+function frees memory allocated by
+<function>XwcTextPropertyToTextList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the default string for text conversion in the current locale,
+use</para>
+
+<para>char *XDefaultString()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDefaultString</function>
+function returns the default string used by Xlib for text conversion
+(for example, in
+<function>XmbTextPropertyToTextList</function>).
+The default string is the string in the current locale that is output
+when an unconvertible character is found during text conversion.
+If the string returned by
+<function>XDefaultString</function>
+is the empty string (""),
+no character is output in the converted text.
+<function>XDefaultString</function>
+does not return NULL.
+</para>
+<para>
+<!-- .LP -->
+The string returned by
+<function>XDefaultString</function>
+is independent of the default string for text drawing;
+see
+<function>XCreateFontSet</function>
+to obtain the default string for an
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+The behavior when an invalid codepoint is supplied to any Xlib function is
+undefined.
+</para>
+<para>
+<!-- .LP -->
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It may be freed after the current locale is changed.
+Until freed, it will not be modified by Xlib.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the specified list of strings in the STRING encoding to a
+<function>XTextProperty</function>
+structure, use
+<function>XStringListToTextProperty</function>.
+<indexterm significance="preferred"><primary>XStringListToTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XStringListToTextProperty</function></funcdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStringListToTextProperty </function>
+function sets the specified
+<function>XTextProperty</function>
+to be of type STRING (format 8) with a value representing the
+concatenation of the specified list of null-separated character strings.
+An extra null byte (which is not included in the nitems member)
+is stored at the end of the value field of text_prop_return.
+The strings are assumed (without verification) to be in the STRING encoding.
+If insufficient memory is available for the new value string,
+<function>XStringListToTextProperty</function>
+does not set any fields in the
+<function>XTextProperty</function>
+structure and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the value field, use
+<function>XFree</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of strings from a specified
+<function>XTextProperty</function>
+structure in the STRING encoding, use
+<function>XTextPropertyToStringList</function>.
+<indexterm significance="preferred"><primary>XTextPropertyToStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XTextPropertyToStringList</function></funcdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>char<parameter> ***list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XTextPropertyToStringList </function>
+function returns a list of strings representing the null-separated elements
+of the specified
+<function>XTextProperty</function>
+structure.
+The data in text_prop must be of type STRING and format 8.
+Multiple elements of the property
+(for example, the strings in a disjoint text selection)
+are separated by NULL (encoding 0).
+The contents of the property are not null-terminated.
+If insufficient memory is available for the list and its elements,
+<function>XTextPropertyToStringList</function>
+sets no return values and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the list and its contents, use
+<function>XFreeStringList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified string list, use
+<function>XFreeStringList</function>.
+<indexterm significance="preferred"><primary>XFreeStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XFreeStringList</function></funcdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of strings to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeStringList </function>
+function releases memory allocated by
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XTextPropertyToStringList</function>
+and the missing charset list allocated by
+<function>XCreateFontSet</function>.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_Text_Properties">
+<title>Setting and Reading Text Properties</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading Text Properties -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides two functions that you can use to set and read
+the text properties for a given window.
+You can use these functions to set and read those properties of type TEXT
+(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
+In addition,
+Xlib provides separate convenience functions that you can use to set each
+of these properties.
+For further information about these convenience functions,
+see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set one of a window's text properties, use
+<function>XSetTextProperty</function>.
+<indexterm significance="preferred"><primary>XSetTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetTextProperty</function>
+function replaces the existing specified property for the named window
+with the data, type, format, and number of items determined
+by the value field, the encoding field, the format field,
+and the nitems field, respectively, of the specified
+<function>XTextProperty</function>
+structure.
+If the property does not already exist,
+<function>XSetTextProperty</function>
+sets it for the specified window.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTextProperty</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read one of a window's text properties, use
+<function>XGetTextProperty</function>.
+<indexterm significance="preferred"><primary>XGetTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetTextProperty </function>
+function reads the specified property from the window
+and stores the data in the returned
+<function>XTextProperty</function>
+structure.
+It stores the data in the value field,
+the type of the data in the encoding field,
+the format of the data in the format field,
+and the number of items of data in the nitems field.
+An extra byte containing null (which is not included in the nitems member)
+is stored at the end of the value field of text_prop_return.
+The particular interpretation of the property's encoding
+and data as text is left to the calling application.
+If the specified property does not exist on the window,
+<function>XGetTextProperty</function>
+sets the value field to NULL,
+the encoding field to
+<function>None</function>,
+the format field to zero,
+and the nitems field to zero.
+</para>
+<para>
+<!-- .LP -->
+If it was able to read and store the data in the
+<function>XTextProperty</function>
+structure,
+<function>XGetTextProperty</function>
+returns a nonzero status;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetTextProperty</function>
+can generate
+<function>BadAtom </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_NAME_Property">
+<title>Setting and Reading the WM_NAME Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_NAME Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides convenience functions that you can use to set and read
+the WM_NAME property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_NAME property with the supplied convenience function, use
+<function>XSetWMName</function>.
+<indexterm significance="preferred"><primary>XSetWMName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMName</function>
+convenience function calls
+<function>XSetTextProperty </function>
+to set the WM_NAME property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_NAME property with the supplied convenience function, use
+<function>XGetWMName</function>.
+<indexterm significance="preferred"><primary>XGetWMName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMName </function>
+convenience function calls
+<function>XGetTextProperty </function>
+to obtain the WM_NAME property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+The following two functions have been superseded by
+<function>XSetWMName</function>
+and
+<function>XGetWMName</function>,
+respectively.
+You can use these additional convenience functions
+for window names that are encoded as STRING properties.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To assign a name to a window, use
+<function>XStoreName</function>.
+<indexterm><primary>Window</primary><secondary>name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XStoreName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *window_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreName</function>
+function assigns the name passed to window_name to the specified window.
+A window manager can display the window name in some prominent
+place, such as the title bar, to allow users to identify windows easily.
+Some window managers may display a window's name in the window's icon,
+although they are encouraged to use the window's icon name
+if one is provided by the application.
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreName</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name of a window, use
+<function>XFetchName</function>.
+<indexterm significance="preferred"><primary>XFetchName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XFetchName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> **window_name_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_name_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the window name, which is a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchName</function>
+function returns the name of the specified window.
+If it succeeds,
+it returns a nonzero status;
+otherwise, no name has been set for the window,
+and it returns zero.
+If the WM_NAME property has not been set for this window,
+<function>XFetchName</function>
+sets window_name_return to NULL.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+When finished with it, a client must free
+the window name string using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XFetchName</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_ICON_NAME_Property">
+<title>Setting and Reading the WM_ICON_NAME Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_ICON_NAME Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides convenience functions that you can use to set and read
+the WM_ICON_NAME property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_ICON_NAME property,
+use
+<function>XSetWMIconName</function>.
+<indexterm significance="preferred"><primary>XSetWMIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMIconName</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the WM_ICON_NAME property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_ICON_NAME property,
+use
+<function>XGetWMIconName</function>.
+<indexterm significance="preferred"><primary>XGetWMIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMIconName </function>
+convenience function calls
+<function>XGetTextProperty </function>
+to obtain the WM_ICON_NAME property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+The next two functions have been superseded by
+<function>XSetWMIconName</function>
+and
+<function>XGetWMIconName</function>,
+respectively.
+You can use these additional convenience functions
+for window names that are encoded as STRING properties.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the name to be displayed in a window's icon, use
+<function>XSetIconName</function>.
+<indexterm><primary>Window</primary><secondary>icon name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *icon_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+<function>XSetIconName</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name a window wants displayed in its icon, use
+<function>XGetIconName</function>.
+<indexterm significance="preferred"><primary>XGetIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> **icon_name_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the window's icon name,
+which is a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIconName</function>
+function returns the name to be displayed in the specified window's icon.
+If it succeeds, it returns a nonzero status; otherwise,
+if no icon name has been set for the window,
+it returns zero.
+If you never assigned a name to the window,
+<function>XGetIconName</function>
+sets icon_name_return to NULL.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+When finished with it, a client must free
+the icon name string using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetIconName</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_HINTS_Property">
+<title>Setting and Reading the WM_HINTS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_HINTS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_HINTS property for a given window.
+These functions use the flags and the
+<function>XWMHints </function>
+structure, as defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XWMHints</function>
+structure, use
+<function>XAllocWMHints</function>.
+</para>
+
+<para>
+ XWMHints *XAllocWMHints()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocWMHints</function>
+function allocates and returns a pointer to an
+<function>XWMHints</function>
+structure.
+Note that all fields in the
+<function>XWMHints</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocWMHints</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XWMHints</function>
+structure contains:
+</para>
+
+<literallayout class="monospaced">
+/* Window manager hints mask bits */
+
+#define InputHint (1L<<0)
+#define StateHint (1L<<1)
+#define IconPixmapHint (1L<<2)
+#define IconWindowHint (1L<<3)
+#define IconPositionHint (1L<<4)
+#define IconMaskHint (1L<<5)
+#define WindowGroupHint (1L<<6)
+#define UrgencyHint (1L<<8)
+#define AllHints (InputHint|StateHint|IconPixmapHint|
+ IconWIndowHint|IconPositionHint|
+ IconMaskHint|WindowGroupHint)
+
+
+/* Values */
+
+typedef struct {
+ long flags; /* marks which fields in this structure are defined */
+ Bool input; /* does this application rely on the window manager to
+ get keyboard input? */
+ int initial_state; /* see below */
+ Pixmap icon_pixmap; /* pixmap to be used as icon */
+ Window icon_window; /* window to be used as icon */
+ int icon_x, icon_y; /* initial position of icon */
+ Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */
+ XID window_group; /* id of related window group */
+ /* this structure may be extended in the future */
+} XWMHints;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The input member is used to communicate to the window manager the input focus
+model used by the application.
+Applications that expect input but never explicitly set focus to any
+of their subwindows (that is, use the push model of focus management),
+such as X Version 10 style applications that use real-estate
+driven focus, should set this member to
+<function>True</function>.
+Similarly, applications
+that set input focus to their subwindows only when it is given to their
+top-level window by a window manager should also set this member to
+<function>True</function>.
+Applications that manage their own input focus by explicitly setting
+focus to one of their subwindows whenever they want keyboard input
+(that is, use the pull model of focus management) should set this member to
+<function>False</function>.
+Applications that never expect any keyboard input also should set this member
+to
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+Pull model window managers should make it possible for push model
+applications to get input by setting input focus to the top-level windows of
+applications whose input member is
+<function>True</function>.
+Push model window managers should
+make sure that pull model applications do not break them
+by resetting input focus to
+<function>PointerRoot </function>
+when it is appropriate (for example, whenever an application whose
+input member is
+<function>False </function>
+sets input focus to one of its subwindows).
+</para>
+<para>
+<!-- .LP -->
+The definitions for the initial_state flag are:
+</para>
+
+<literallayout class="monospaced">
+#define WithdrawnState 0
+#define NormalState 1 /* most applications start this way */
+#define IconicState 2 /* application wants to start as an icon */
+
+</literallayout>
+<para>
+The icon_mask specifies which pixels of the icon_pixmap should be used as the
+icon.
+This allows for nonrectangular icons.
+Both icon_pixmap and icon_mask must be bitmaps.
+The icon_window lets an application provide a window for use as an icon
+for window managers that support such use.
+The window_group lets you specify that this window belongs to a group
+of other windows.
+For example, if a single application manipulates multiple
+top-level windows, this allows you to provide enough
+information that a window manager can iconify all of the windows
+rather than just the one window.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>UrgencyHint</function>
+flag, if set in the flags field, indicates that the client deems the window
+contents to be urgent, requiring the timely response of the user. The
+window manager will make some effort to draw the user's attention to this
+window while this flag is set. The client must provide some means by which the
+user can cause the urgency flag to be cleared (either mitigating
+the condition that made the window urgent or merely shutting off the alarm)
+or the window to be withdrawn.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_HINTS property, use
+<function>XSetWMHints</function>.
+<indexterm significance="preferred"><primary>XSetWMHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWMHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XWMHints<parameter> *wmhints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>wmhints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWMHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMHints</function>
+function sets the window manager hints that include icon information and location,
+the initial state of the window, and whether the application relies on the
+window manager to get keyboard input.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMHints</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_HINTS property, use
+<function>XGetWMHints</function>.
+<indexterm significance="preferred"><primary>XGetWMHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XWMHints<function> *XGetWMHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMHints</function>
+function reads the window manager hints and
+returns NULL if no WM_HINTS property was set on the window
+or returns a pointer to an
+<function>XWMHints </function>
+structure if it succeeds.
+When finished with the data,
+free the space used for it by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMHints</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">
+<title>Setting and Reading the WM_NORMAL_HINTS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_NORMAL_HINTS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set or read
+the WM_NORMAL_HINTS property for a given window.
+The functions use the flags and the
+<function>XSizeHints </function>
+structure, as defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+</para>
+<para>
+<!-- .LP -->
+The size of the
+<function>XSizeHints</function>
+structure may grow in future releases, as new components are
+added to support new <acronym>ICCCM</acronym> features.
+Passing statically allocated instances of this structure into
+Xlib may result in memory corruption when running against a
+future release of the library.
+As such, it is recommended that only dynamically allocated
+instances of the structure be used.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XSizeHints</function>
+structure, use
+<function>XAllocSizeHints</function>.
+</para>
+
+<para>
+XSizeHints *XAllocSizeHints()
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocSizeHints</function>
+function allocates and returns a pointer to an
+<function>XSizeHints</function>
+structure.
+Note that all fields in the
+<function>XSizeHints</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocSizeHints</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XSizeHints</function>
+structure contains:
+</para>
+
+
+<literallayout class="monospaced">
+/* Size hints mask bits */
+
+#define USPosition (1L<<0) /* user specified x,y */
+#define USSize (1L<<1) /* user specified width,height */
+#define PPosition (1L<<2) /* program specified posistion */
+#define PSize (1L<<3) /* program specified size */
+#define PMinSize (1L<<4) /* program specified minimum size */
+#define PMaxSize (1L<<5) /* program specified maximum size */
+#define PResizeInc (1L<<5) /* program specified resize increments */
+#define PAspect (1L<<6) /* program specified min and max aspect ratios */
+#define PBaseSize (1L<<8)
+#define PWinGravity (1L<<9)
+#define PAllHints (PPosition|Psize|
+ PMinSize|PMaxSize|
+ PResizeInc|PAspect)
+
+
+/* Values */
+
+typedef struct {
+ long flags; /* marks which fields in this structure are defined */
+ int x, y; /* Obsolete */
+ int width, height; /* Obsolete */
+ int min_width, min_height;
+ int max_width, max_height;
+ int width_inc, height_inc;
+ struct {
+ int x; /* numerator */
+ int y; /* denominator */
+ } min_aspect, max_aspect;
+ int base_width, base_height;
+ int win_gravity;
+ /* this structure may be extended in the future */
+} XSizeHints;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x, y, width, and height members are now obsolete
+and are left solely for compatibility reasons.
+The min_width and min_height members specify the
+minimum window size that still allows the application to be useful.
+The max_width and max_height members specify the maximum window size.
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) into which the window prefers to be resized.
+The min_aspect and max_aspect members are expressed
+as ratios of x and y,
+and they allow an application to specify the range of aspect
+ratios it prefers.
+The base_width and base_height members define the desired size of the window.
+The window manager will interpret the position of the window
+and its border width to position the point of the outer rectangle
+of the overall window specified by the win_gravity member.
+The outer rectangle of the window includes any borders or decorations
+supplied by the window manager.
+In other words,
+if the window manager decides to place the window where the client asked,
+the position on the parent window's border named by the win_gravity
+will be placed where the client window would have been placed
+in the absence of a window manager.
+</para>
+<para>
+<!-- .LP -->
+Note that use of the
+<function>PAllHints</function>
+macro is highly discouraged.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_NORMAL_HINTS property, use
+<function>XSetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XSetWMNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMNormalHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMNormalHints </function>
+function replaces the size hints for the WM_NORMAL_HINTS property
+on the specified window.
+If the property does not already exist,
+<function>XSetWMNormalHints</function>
+sets the size hints for the WM_NORMAL_HINTS property on the specified window.
+The property is stored with a type of WM_SIZE_HINTS and a format of 32.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMNormalHints</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_NORMAL_HINTS property, use
+<function>XGetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XGetWMNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMNormalHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+ <paramdef>long<parameter> *supplied_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>supplied_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the hints that were supplied by the user.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMNormalHints </function>
+function returns the size hints stored in the WM_NORMAL_HINTS property
+on the specified window.
+If the property is of type WM_SIZE_HINTS, is of format 32,
+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>)
+or new size hints structure,
+<function>XGetWMNormalHints</function>
+sets the various fields of the
+<function>XSizeHints</function>
+structure, sets the supplied_return argument to the list of fields
+that were supplied by the user (whether or not they contained defined values),
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XGetWMNormalHints</function>
+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read,
+the supplied_return argument will contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If the property is large enough to contain the base size
+and window gravity fields as well,
+the supplied_return argument will also contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+PBaseSize|PWinGravity
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMNormalHints</function>
+can generate a
+<function>BadWindow</function>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_SIZE_HINTS property, use
+<function>XSetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XSetWMSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMSizeHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XSizeHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMSizeHints </function>
+function replaces the size hints for the specified property
+on the named window.
+If the specified property does not already exist,
+<function>XSetWMSizeHints</function>
+sets the size hints for the specified property
+on the named window.
+The property is stored with a type of WM_SIZE_HINTS and a format of 32.
+To set a window's normal size hints,
+you can use the
+<function>XSetWMNormalHints</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMSizeHints</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_SIZE_HINTS property, use
+<function>XGetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XGetWMSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMSizeHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+ <paramdef>long<parameter> *supplied_return</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XSizeHints</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>supplied_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the hints that were supplied by the user.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMSizeHints</function>
+function returns the size hints stored in the specified property
+on the named window.
+If the property is of type WM_SIZE_HINTS, is of format 32,
+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>)
+or new size hints structure,
+<function>XGetWMSizeHints</function>
+sets the various fields of the
+<function>XSizeHints</function>
+structure, sets the supplied_return argument to the
+list of fields that were supplied by the user
+(whether or not they contained defined values),
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+To get a window's normal size hints,
+you can use the
+<function>XGetWMNormalHints </function>
+function.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XGetWMSizeHints</function>
+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read,
+the supplied_return argument will contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If the property is large enough to contain the base size
+and window gravity fields as well,
+the supplied_return argument will also contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+PBaseSize|PWinGravity
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMSizeHints</function>
+can generate
+<function>BadAtom </function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_CLASS_Property">
+<title>Setting and Reading the WM_CLASS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_CLASS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and get
+the WM_CLASS property for a given window.
+These functions use the
+<function>XClassHint </function>
+structure, which is defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XClassHint</function>
+structure, use
+<function>XAllocClassHint</function>.
+<indexterm significance="preferred"><primary>XAllocClassHint</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+
+ XClassHint *XAllocClassHint()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocClassHint</function>
+function allocates and returns a pointer to an
+<function>XClassHint</function>
+structure.
+Note that the pointer fields in the
+<function>XClassHint</function>
+structure are initially set to NULL.
+If insufficient memory is available,
+<function>XAllocClassHint</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XClassHint</function>
+contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XClassHint</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ char *res_name;
+ char *res_class;
+} XClassHint;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The res_name member contains the application name,
+and the res_class member contains the application class.
+Note that the name set in this property may differ from the name set as WM_NAME.
+That is, WM_NAME specifies what should be displayed in the title bar and,
+therefore, can contain temporal information (for example, the name of
+a file currently in an editor's buffer).
+On the other hand,
+the name specified as part of WM_CLASS is the formal name of the application
+that should be used when retrieving the application's resources from the
+resource database.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_CLASS property, use
+<function>XSetClassHint</function>.
+<indexterm significance="preferred"><primary>XSetClassHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetClassHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XClassHint</function>
+structure that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetClassHint</function>
+function sets the class hint for the specified window.
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClassHint</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_CLASS property, use
+<function>XGetClassHint</function>.
+<indexterm significance="preferred"><primary>XGetClassHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetClassHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XClassHint</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetClassHint</function>
+function returns the class hint of the specified window to the members
+of the supplied structure.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+To free res_name and res_class when finished with the strings,
+use
+<function>XFree</function>
+on each individually.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetClassHint</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">
+<title>Setting and Reading the WM_TRANSIENT_FOR Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_TRANSIENT_FOR Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_TRANSIENT_FOR property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_TRANSIENT_FOR property, use
+<function>XSetTransientForHint</function>.
+<indexterm significance="preferred"><primary>XSetTransientForHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetTransientForHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> prop_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prop_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window that the WM_TRANSIENT_FOR property is to be set to.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetTransientForHint</function>
+function sets the WM_TRANSIENT_FOR property of the specified window to the
+specified prop_window.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTransientForHint</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_TRANSIENT_FOR property, use
+<function>XGetTransientForHint</function>.
+<indexterm significance="preferred"><primary>XGetTransientForHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetTransientForHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> *prop_window_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prop_window_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the WM_TRANSIENT_FOR property of the specified window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetTransientForHint</function>
+function returns the WM_TRANSIENT_FOR property for the specified window.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetTransientForHint</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_PROTOCOLS_Property">
+<title>Setting and Reading the WM_PROTOCOLS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_PROTOCOLS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_PROTOCOLS property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_PROTOCOLS property, use
+<function>XSetWMProtocols</function>.
+<indexterm significance="preferred"><primary>XSetWMProtocols</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XSetWMProtocols</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atom<parameter> *protocols</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>protocols</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of protocols.
+<!-- .ds Cn protocols in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMProtocols </function>
+function replaces the WM_PROTOCOLS property on the specified window
+with the list of atoms specified by the protocols argument.
+If the property does not already exist,
+<function>XSetWMProtocols</function>
+sets the WM_PROTOCOLS property on the specified window
+to the list of atoms specified by the protocols argument.
+The property is stored with a type of ATOM and a format of 32.
+If it cannot intern the WM_PROTOCOLS atom,
+<function>XSetWMProtocols</function>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMProtocols</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_PROTOCOLS property, use
+<function>XGetWMProtocols</function>.
+<indexterm significance="preferred"><primary>XGetWMProtocols</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMProtocols</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atom<parameter> **protocols_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>protocols_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of protocols.
+<!-- .ds Cn protocols in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMProtocols </function>
+function returns the list of atoms stored in the WM_PROTOCOLS property
+on the specified window.
+These atoms describe window manager protocols in which the owner
+of this window is willing to participate.
+If the property exists, is of type ATOM, is of format 32,
+and the atom WM_PROTOCOLS can be interned,
+<function>XGetWMProtocols</function>
+sets the protocols_return argument to a list of atoms,
+sets the count_return argument to the number of elements in the list,
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of atoms, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMProtocols</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">
+<title>Setting and Reading the WM_COLORMAP_WINDOWS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_COLORMAP_WINDOWS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_COLORMAP_WINDOWS property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_COLORMAP_WINDOWS property, use
+<function>XSetWMColormapWindows</function>.
+<indexterm significance="preferred"><primary>XSetWMColormapWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XSetWMColormapWindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> *colormap_windows</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap_windows</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of windows.
+<!-- .ds Cn windows in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMColormapWindows </function>
+function replaces the WM_COLORMAP_WINDOWS property on the specified
+window with the list of windows specified by the colormap_windows argument.
+If the property does not already exist,
+<function>XSetWMColormapWindows</function>
+sets the WM_COLORMAP_WINDOWS property on the specified
+window to the list of windows specified by the colormap_windows argument.
+The property is stored with a type of WINDOW and a format of 32.
+If it cannot intern the WM_COLORMAP_WINDOWS atom,
+<function>XSetWMColormapWindows</function>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMColormapWindows</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_COLORMAP_WINDOWS property, use
+<function>XGetWMColormapWindows</function>.
+<indexterm significance="preferred"><primary>XGetWMColormapWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMColormapWindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> **colormap_windows_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap_windows_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of windows.
+<!-- .ds Cn windows in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMColormapWindows </function>
+function returns the list of window identifiers stored
+in the WM_COLORMAP_WINDOWS property on the specified window.
+These identifiers indicate the colormaps that the window manager
+may need to install for this window.
+If the property exists, is of type WINDOW, is of format 32,
+and the atom WM_COLORMAP_WINDOWS can be interned,
+<function>XGetWMColormapWindows</function>
+sets the windows_return argument to a list of window identifiers,
+sets the count_return argument to the number of elements in the list,
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of window identifiers, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMColormapWindows</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_ICON_SIZE_Property">
+<title>Setting and Reading the WM_ICON_SIZE Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_ICON_SIZE Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_ICON_SIZE property for a given window.
+These functions use the
+<function>XIconSize </function>
+<indexterm><primary>XIconSize</primary></indexterm>
+structure, which is defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XIconSize</function>
+structure, use
+<function>XAllocIconSize</function>.
+</para>
+
+<para>
+ XIconSize *XAllocIconSize()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocIconSize </function>
+function allocates and returns a pointer to an
+<function>XIconSize </function>
+structure.
+Note that all fields in the
+<function>XIconSize</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocIconSize</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIconSize</function>
+structure contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XIconSize</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int min_width, min_height;
+ int max_width, max_height;
+ int width_inc, height_inc;
+} XIconSize;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) that represent the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_ICON_SIZE property, use
+<function>XSetIconSizes</function>.
+<indexterm significance="preferred"><primary>XSetIconSizes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetIconSizes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XIconSize<parameter> *size_list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIconSizes</function>
+function is used only by window managers to set the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetIconSizes</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_ICON_SIZE property, use
+<function>XGetIconSizes</function>.
+<indexterm significance="preferred"><primary>XGetIconSizes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetIconSizes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XIconSize<parameter> **size_list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size_list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of items in the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIconSizes</function>
+function returns zero if a window manager has not set icon sizes;
+otherwise, it returns nonzero.
+<function>XGetIconSizes</function>
+should be called by an application that
+wants to find out what icon sizes would be most appreciated by the
+window manager under which the application is running.
+The application
+should then use
+<function>XSetWMHints</function>
+to supply the window manager with an icon pixmap or window in one of the
+supported sizes.
+To free the data allocated in size_list_return, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetIconSizes</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Using_Window_Manager_Convenience_Functions">
+<title>Using Window Manager Convenience Functions</title>
+<!-- .XS -->
+<!-- (SN Using Window Manager Convenience Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XmbSetWMProperties</function>
+function stores the standard set of window manager properties,
+with text properties in standard encodings
+for internationalized text communication.
+The standard window manager properties for a given window are
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
+WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
+<indexterm significance="preferred"><primary>XmbSetWMProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XmbSetWMProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *window_name</parameter></paramdef>
+ <paramdef>char<parameter> *icon_name</parameter></paramdef>
+ <paramdef>char<parameter> *argv[]</parameter></paramdef>
+ <paramdef>int<parameter> argc</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
+ <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>wm_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWMHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XClassHint</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbSetWMProperties</function>
+convenience function provides a simple programming interface
+for setting those essential window properties that are used
+for communicating with other clients
+(particularly window and session managers).
+</para>
+<para>
+<!-- .LP -->
+If the window_name argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_NAME property.
+If the icon_name argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_ICON_NAME property.
+The window_name and icon_name arguments are null-terminated strings
+in the encoding of the current locale.
+If the arguments can be fully converted to the STRING encoding,
+the properties are created with type ``STRING'';
+otherwise, the arguments are converted to Compound Text,
+and the properties are created with type ``COMPOUND_TEXT''.
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+calls
+<function>XSetWMNormalHints</function>,
+which sets the WM_NORMAL_HINTS property (see section 14.1.7).
+If the wm_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+calls
+<function>XSetWMHints</function>,
+which sets the WM_HINTS property (see section 14.1.6).
+</para>
+<para>
+<!-- .LP -->
+If the argv argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_COMMAND property from argv and argc.
+An argc of zero indicates a zero-length command.
+</para>
+<para>
+<!-- .LP -->
+The hostname of the machine is stored using
+<function>XSetWMClientMachine </function>
+(see section 14.2.2).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_CLASS property.
+If the res_name member in the
+<function>XClassHint</function>
+structure is set to the NULL pointer and the RESOURCE_NAME
+environment variable is set,
+the value of the environment variable is substituted for res_name.
+If the res_name member is NULL,
+the environment variable is not set, and argv and argv[0] are set,
+then the value of argv[0], stripped of any directory prefixes,
+is substituted for res_name.
+</para>
+<para>
+<!-- .LP -->
+It is assumed that the supplied class_hints.res_name and argv,
+the RESOURCE_NAME environment variable, and the hostname of the machine
+are in the encoding of the locale announced for the LC_CTYPE category
+(on <acronym>POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).
+The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties
+are typed according to the local host locale announcer.
+No encoding conversion is performed prior to storage in the properties.
+</para>
+<para>
+<!-- .LP -->
+For clients that need to process the property text in a locale,
+<function>XmbSetWMProperties</function>
+sets the WM_LOCALE_NAME property to be the name of the current locale.
+The name is assumed to be in the Host Portable Character Encoding
+and is converted to STRING for storage in the property.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbSetWMProperties</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's standard window manager properties
+with strings in client-specified encodings, use
+<function>XSetWMProperties</function>.
+The standard window manager properties for a given window are
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
+WM_COMMAND, and WM_CLIENT_MACHINE.
+<indexterm significance="preferred"><primary>XSetWMProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *window_name</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *icon_name</parameter></paramdef>
+ <paramdef>char<parameter> **argv</parameter></paramdef>
+ <paramdef>int<parameter> argc</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
+ <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>normal_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>wm_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWMHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XClassHint</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMProperties </function>
+convenience function provides a single programming interface
+for setting those essential window properties that are used
+for communicating with other clients (particularly window and session
+managers).
+</para>
+<para>
+<!-- .LP -->
+If the window_name argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMName</function>,
+which, in turn, sets the WM_NAME property (see section 14.1.4).
+If the icon_name argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMIconName</function>,
+which sets the WM_ICON_NAME property (see section 14.1.5).
+If the argv argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetCommand</function>,
+which sets the WM_COMMAND property (see section 14.2.1).
+Note that an argc of zero is allowed to indicate a zero-length command.
+Note also that the hostname of this machine is stored using
+<function>XSetWMClientMachine </function>
+(see section 14.2.2).
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMNormalHints</function>,
+which sets the WM_NORMAL_HINTS property (see section 14.1.7).
+If the wm_hints argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMHints</function>,
+which sets the WM_HINTS property (see section 14.1.6).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetClassHint</function>,
+which sets the WM_CLASS property (see section 14.1.8).
+If the res_name member in the
+<function>XClassHint</function>
+structure is set to the NULL pointer and the RESOURCE_NAME environment
+variable is set,
+then the value of the environment variable is substituted for res_name.
+If the res_name member is NULL,
+the environment variable is not set,
+and argv and argv[0] are set,
+then the value of argv[0], stripped of
+any directory prefixes, is substituted for res_name.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMProperties</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Client_to_Session_Manager_Communication">
+<title>Client to Session Manager Communication</title>
+<!-- .XS -->
+<!-- (SN Client to Session Manager Communication -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Set and read the WM_COMMAND property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_CLIENT_MACHINE property
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Setting_and_Reading_the_WM_COMMAND_Property">
+<title>Setting and Reading the WM_COMMAND Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_COMMAND Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_COMMAND property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_COMMAND property, use
+<function>XSetCommand</function>.
+<indexterm significance="preferred"><primary>XSetCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetCommand</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> **argv</parameter></paramdef>
+ <paramdef>int<parameter> argc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetCommand</function>
+function sets the command and arguments used to invoke the
+application.
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetCommand</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_COMMAND property, use
+<function>XGetCommand</function>.
+<indexterm significance="preferred"><primary>XGetCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetCommand</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> ***argv_return</parameter></paramdef>
+ <paramdef>int<parameter> *argc_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of arguments returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetCommand </function>
+function reads the WM_COMMAND property from the specified window
+and returns a string list.
+If the WM_COMMAND property exists,
+it is of type STRING and format 8.
+If sufficient memory can be allocated to contain the string list,
+<function>XGetCommand</function>
+fills in the argv_return and argc_return arguments
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the memory allocated to the string list, use
+<function>XFreeStringList</function>.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">
+<title>Setting and Reading the WM_CLIENT_MACHINE Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_CLIENT_MACHINE Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_CLIENT_MACHINE property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_CLIENT_MACHINE property, use
+<function>XSetWMClientMachine</function>.
+<indexterm significance="preferred"><primary>XSetWMClientMachine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMClientMachine</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMClientMachine</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the WM_CLIENT_MACHINE property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_CLIENT_MACHINE property, use
+<function>XGetWMClientMachine</function>.
+<indexterm significance="preferred"><primary>XGetWMClientMachine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMClientMachine</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMClientMachine</function>
+convenience function performs an
+<function>XGetTextProperty </function>
+on the WM_CLIENT_MACHINE property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Standard_Colormaps">
+<title>Standard Colormaps</title>
+<!-- .XS -->
+<!-- (SN Standard Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications with color palettes, smooth-shaded drawings, or digitized
+images demand large numbers of colors.
+In addition, these applications often require an efficient mapping
+from color triples to pixel values that display the appropriate colors.
+</para>
+<para>
+<!-- .LP -->
+As an example, consider a three-dimensional display program that wants
+to draw a smoothly shaded sphere.
+At each pixel in the image of the sphere,
+the program computes the intensity and color of light
+reflected back to the viewer.
+The result of each computation is a triple of red, green, and blue (<acronym>RGB</acronym>)
+coefficients in the range 0.0 to 1.0.
+To draw the sphere, the program needs a colormap that provides a
+large range of uniformly distributed colors.
+The colormap should be arranged so that the program can
+convert its <acronym>RGB</acronym> triples into pixel values very quickly,
+because drawing the entire sphere requires many such
+conversions.
+</para>
+<para>
+<!-- .LP -->
+On many current workstations,
+the display is limited to 256 or fewer colors.
+Applications must allocate colors carefully,
+not only to make sure they cover the entire range they need
+but also to make use of as many of the available colors as possible.
+On a typical X display,
+many applications are active at once.
+Most workstations have only one hardware look-up table for colors,
+so only one application colormap can be installed at a given time.
+The application using the installed colormap is displayed correctly,
+and the other applications go technicolor and are
+displayed with false colors.
+</para>
+<para>
+<!-- .LP -->
+As another example, consider a user who is running an
+image processing program to display earth-resources data.
+The image processing program needs a colormap set up with 8 reds,
+8 greens, and 4 blues, for a total of 256 colors.
+Because some colors are already in use in the default colormap,
+the image processing program allocates and installs a new colormap.
+</para>
+<para>
+<!-- .LP -->
+The user decides to alter some of the colors in the image
+by invoking a color palette program to mix and choose colors.
+The color palette program also needs a
+colormap with eight reds, eight greens, and four blues, so just like
+the image processing program, it must allocate and
+install a new colormap.
+</para>
+<para>
+<!-- .LP -->
+Because only one colormap can be installed at a time,
+the color palette may be displayed incorrectly
+whenever the image processing program is active.
+Conversely, whenever the palette program is active,
+the image may be displayed incorrectly.
+The user can never match or compare colors in the palette and image.
+Contention for colormap resources can be reduced if applications
+with similar color needs share colormaps.
+</para>
+<para>
+<!-- .LP -->
+The image processing program and the color palette program
+could share the same colormap if there existed a convention that described
+how the colormap was set up.
+Whenever either program was active,
+both would be displayed correctly.
+</para>
+<para>
+<!-- .LP -->
+The standard colormap properties define a set of commonly used
+colormaps.
+Applications that share these colormaps and conventions display
+true colors more often and provide a better interface to the user.
+</para>
+<para>
+<!-- .LP -->
+Standard colormaps allow applications to share commonly used color
+resources.
+This allows many applications to be displayed in true colors
+simultaneously, even when each application needs an entirely filled
+colormap.
+</para>
+<para>
+<!-- .LP -->
+Several standard colormaps are described in this section.
+Usually, a window manager creates these colormaps.
+Applications should use the standard colormaps if they already exist.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XStandardColormap</function>
+structure, use
+<function>XAllocStandardColormap</function>.
+</para>
+
+<para>
+XStandardColormap *XAllocStandardColormap()
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocStandardColormap</function>
+function allocates and returns a pointer to an
+<function>XStandardColormap</function>
+structure.
+Note that all fields in the
+<function>XStandardColormap</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocStandardColormap</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XStandardColormap </function>
+structure contains:
+</para>
+<literallayout class="monospaced">
+/* Hints */
+
+#define ReeaseByFreeingColormap ((XID)1L)
+
+/* Values */
+
+typedef struct {
+ Colormap colormap;
+ unsigned long red_max;
+ unsigned long red_mult;
+ unsigned long green_max;
+ unsigned long green_mult;
+ unsigned long blue_max;
+ unsigned long blue_mult;
+ unsigned long base_pixel;
+ VisualID visualid;
+ XID killid;
+} XStandardColormap;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The colormap member is the colormap created by the
+<function>XCreateColormap</function>
+function.
+The red_max, green_max, and blue_max members give the maximum
+red, green, and blue values, respectively.
+Each color coefficient ranges from zero to its max, inclusive.
+For example,
+a common colormap allocation is 3/3/2 (3 planes for red, 3
+planes for green, and 2 planes for blue).
+This colormap would have red_max = 7, green_max = 7,
+and blue_max = 3.
+An alternate allocation that uses only 216 colors is red_max = 5,
+green_max = 5, and blue_max = 5.
+</para>
+<para>
+<!-- .LP -->
+The red_mult, green_mult, and blue_mult members give the
+scale factors used to compose a full pixel value.
+(See the discussion of the base_pixel members for further information.)
+For a 3/3/2 allocation, red_mult might be 32,
+green_mult might be 4, and blue_mult might be 1.
+For a 6-colors-each allocation, red_mult might be 36,
+green_mult might be 6, and blue_mult might be 1.
+</para>
+<para>
+<!-- .LP -->
+The base_pixel member gives the base pixel value used to
+compose a full pixel value.
+Usually, the base_pixel is obtained from a call to the
+<function>XAllocColorPlanes</function>
+function.
+Given integer red, green, and blue coefficients in their appropriate
+ranges, one then can compute a corresponding pixel value by
+using the following expression:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+For
+<function>GrayScale</function>
+colormaps,
+only the colormap, red_max, red_mult,
+and base_pixel members are defined.
+The other members are ignored.
+To compute a
+<function>GrayScale </function>
+pixel value, use the following expression:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+(gray * red_mult + base_pixel) & 0xFFFFFFFF
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Negative multipliers can be represented by converting the 2's
+complement representation of the multiplier into an unsigned long and
+storing the result in the appropriate _mult field.
+The step of masking by 0xFFFFFFFF effectively converts the resulting
+positive multiplier into a negative one.
+The masking step will take place automatically on many machine architectures,
+depending on the size of the integer type used to do the computation.
+</para>
+<para>
+<!-- .LP -->
+The visualid member gives the ID number of the visual from which the
+colormap was created.
+The killid member gives a resource ID that indicates whether
+the cells held by this standard colormap are to be released
+by freeing the colormap ID or by calling the
+<function>XKillClient</function>
+function on the indicated resource.
+(Note that this method is necessary for allocating out of an existing colormap.)
+</para>
+<para>
+<!-- .LP -->
+The properties containing the
+<function>XStandardColormap </function>
+information have
+the type RGB_COLOR_MAP.
+</para>
+<para>
+<!-- .LP -->
+The remainder of this section discusses standard colormap properties and atoms
+as well as how to manipulate standard colormaps.
+</para>
+<sect2 id="Standard_Colormap_Properties_and_Atoms">
+<title>Standard Colormap Properties and Atoms</title>
+<!-- .XS -->
+<!-- (SN Standard Colormap Properties and Atoms -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Standard Colormaps</primary></indexterm>
+<indexterm><primary>Colormaps</primary><secondary>standard</secondary></indexterm>
+Several standard colormaps are available.
+Each standard colormap is defined by a property,
+and each such property is identified by an atom.
+The following list names the atoms and describes the colormap
+associated with each one.
+The
+<!-- .hN X11/Xatom.h -->
+header file contains the definitions for each of the following atoms,
+which are prefixed with XA_.
+</para>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>RGB_DEFAULT_MAP</term>
+ <listitem>
+ <para>
+This atom names a property.
+The value of the property is an array of
+<function>XStandardColormap</function>
+structures.
+Each entry in the array describes an <acronym>RGB</acronym> subset of the default color
+map for the Visual specified by visual_id.
+ </para>
+ <para>
+Some applications only need a few <acronym>RGB</acronym> colors and
+may be able to allocate them from the system default colormap.
+This is the ideal situation because the fewer colormaps that are
+active in the system the more applications are displayed
+with correct colors at all times.
+ </para>
+ <para>
+A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
+is 6 reds, 6 greens, and 6 blues.
+This gives 216 uniformly distributed colors
+(6 intensities of 36 different hues) and still leaves 40 elements
+of a 256-element colormap available for special-purpose colors
+for text, borders, and so on.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RGB_BEST_MAP</term>
+ <listitem>
+ <para>
+This atom names a property. The value of the property is an
+<function>XStandardColormap</function>.
+ </para>
+ <para>
+The property defines the best <acronym>RGB</acronym> colormap available on
+the screen.
+(Of course, this is a subjective evaluation.)
+Many image processing and three-dimensional applications need to
+use all available colormap cells and to distribute as many
+perceptually distinct colors as possible over those cells.
+This implies that there may be more green values available than
+red, as well as more green or red than blue.
+ </para>
+ <para>
+For an 8-plane
+<function>PseudoColor </function>
+visual,
+RGB_BEST_MAP is likely to be a 3/3/2 allocation.
+For a 24-plane
+<function>DirectColor </function>
+visual,
+RGB_BEST_MAP is normally an 8/8/8 allocation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</term>
+ <listitem>
+ <para>
+These atoms name properties.
+The value of each property is an
+<function>XStandardColormap</function>.
+ </para>
+ <para>
+The properties define all-red, all-green, and all-blue
+colormaps, respectively.
+These maps are used by applications that want to make color-separated
+images.
+For example, a user might generate a full-color image
+on an 8-plane display both by rendering an image three times
+(once with high color resolution in red, once with green,
+and once with blue) and by multiply exposing a single frame in a camera.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RGB_GRAY_MAP</term>
+ <listitem>
+ <para>
+This atom names a property.
+The value of the property is an
+<function>XStandardColormap</function>.
+ </para>
+ <para>
+The property describes the best
+<function>GrayScale </function>
+colormap available on the screen.
+As previously mentioned,
+only the colormap, red_max, red_mult, and base_pixel members of the
+<function>XStandardColormap </function>
+structure are used for
+<function>GrayScale </function>
+colormaps.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="Setting_and_Obtaining_Standard_Colormaps">
+<title>Setting and Obtaining Standard Colormaps</title>
+<!-- .XS -->
+<!-- (SN Setting and Obtaining Standard Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and obtain an
+<function>XStandardColormap</function>
+structure.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set an
+<function>XStandardColormap</function>
+structure, use
+<function>XSetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XSetRGBColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetRGBColormaps</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XStandardColormap<parameter> *std_colormap</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>std_colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XStandardColormap</function>
+structure to be used.
+<!-- .ds Cn colormaps -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetRGBColormaps </function>
+function replaces the <acronym>RGB</acronym> colormap definition in the specified property
+on the named window.
+If the property does not already exist,
+<function>XSetRGBColormaps</function>
+sets the <acronym>RGB</acronym> colormap definition in the specified property
+on the named window.
+The property is stored with a type of RGB_COLOR_MAP and a format of 32.
+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XSetRGBColormaps</function>
+function usually is only used by window or session managers.
+To create a standard colormap,
+follow this procedure:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Open a new connection to the same server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Grab the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+See if the property is on the property list of the root window for the screen.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the desired property is not present:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Create a colormap (unless you are using the default colormap of the screen).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Determine the color characteristics of the visual.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Allocate cells in the colormap (or create it with
+<function>AllocAll</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Call
+<function>XStoreColors</function>
+to store appropriate color values in the colormap.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Fill in the descriptive members in the
+<function>XStandardColormap</function>
+structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Attach the property to the root window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use
+<function>XSetCloseDownMode</function>
+to make the resource permanent.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Ungrab the server.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XSetRGBColormaps</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the
+<function>XStandardColormap </function>
+structure associated with the specified property, use
+<function>XGetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XGetRGBColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetRGBColormaps</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XStandardColormap<parameter> **std_colormap_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+ <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>std_colormap_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XStandardColormap</function>
+structure.
+<!-- .ds Cn colormaps -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetRGBColormaps</function>
+function returns the <acronym>RGB</acronym> colormap definitions stored
+in the specified property on the named window.
+If the property exists, is of type RGB_COLOR_MAP, is of format 32,
+and is long enough to contain a colormap definition,
+<function>XGetRGBColormaps</function>
+allocates and fills in space for the returned colormaps
+and returns a nonzero status.
+If the visualid is not present,
+<function>XGetRGBColormaps </function>
+assumes the default visual for the screen on which the window is located;
+if the killid is not present,
+<function>None</function>
+is assumed, which indicates that the resources cannot be released.
+Otherwise,
+none of the fields are set, and
+<function>XGetRGBColormaps</function>
+returns a zero status.
+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetRGBColormaps</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH15 b/libX11/specs/libX11/CH15 deleted file mode 100644 index a10df0a53..000000000 --- a/libX11/specs/libX11/CH15 +++ /dev/null @@ -1,1628 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 15\fP\s-1 - -\s+1\fBResource Manager Functions\fP\s-1 -.sp 2 -.nr H1 15 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 15: Resource Manager Functions -.XE -A program often needs a variety of options in the X environment -(for example, fonts, colors, icons, and cursors). -Specifying all of these options on the command line is awkward -because users may want to customize many aspects of the program -and need a convenient way to establish these customizations as -the default settings. -The resource manager is provided for this purpose. -Resource specifications are usually stored in human-readable files -and in server properties. -.LP -The resource manager is a database manager with a twist. -In most database systems, -you perform a query using an imprecise specification, -and you get back a set of records. -The resource manager, however, allows you to specify a large -set of values with an imprecise specification, to query the database -with a precise specification, and to get back only a single value. -This should be used by applications that need to know what the -user prefers for colors, fonts, and other resources. -It is this use as a database for dealing with X resources that -inspired the name ``Resource Manager,'' -although the resource manager can be and is used in other ways. -.LP -For example, -a user of your application may want to specify -that all windows should have a blue background -but that all mail-reading windows should have a red background. -With well-engineered and coordinated applications, -a user can define this information using only two lines of specifications. -.LP -As an example of how the resource manager works, -consider a mail-reading application called xmh. -Assume that it is designed so that it uses a -complex window hierarchy all the way down to individual command buttons, -which may be actual small subwindows in some toolkits. -These are often called objects or widgets. -In such toolkit systems, -each user interface object can be composed of other objects -and can be assigned a name and a class. -Fully qualified names or classes can have arbitrary numbers of component names, -but a fully qualified name always has the same number of component names as a -fully qualified class. -This generally reflects the structure of the application as composed -of these objects, starting with the application itself. -.LP -For example, the xmh mail program has a name ``xmh'' and is one -of a class of ``Mail'' programs. -By convention, the first character of class components is capitalized, -and the first letter of name components is in lowercase. -Each name and class finally has an attribute -(for example, ``foreground'' or ``font''). -If each window is properly assigned a name and class, -it is easy for the user to specify attributes of any portion -of the application. -.LP -At the top level, -the application might consist of a paned window (that is, a window divided -into several sections) named ``toc''. -One pane of the paned window is a button box window named ``buttons'' -and is filled with command buttons. -One of these command buttons is used to incorporate -new mail and has the name ``incorporate''. -This window has a fully qualified name, ``xmh.toc.buttons.incorporate'', -and a fully qualified class, ``Xmh.Paned.Box.Command''. -Its fully qualified name is the name of its parent, ``xmh.toc.buttons'', -followed by its name, ``incorporate''. -Its class is the class of its parent, ``Xmh.Paned.Box'', -followed by its particular class, ``Command''. -The fully qualified name of a resource is -the attribute's name appended to the object's fully qualified -name, and the fully qualified class is its class appended to the object's -class. -.LP -The incorporate button might need the following resources: -Title string, -Font, -Foreground color for its inactive state, -Background color for its inactive state, -Foreground color for its active state, and -Background color for its active state. -Each resource is considered -to be an attribute of the button and, as such, has a name and a class. -For example, the foreground color for the button in -its active state might be named ``activeForeground'', -and its class might be ``Foreground''. -.LP -When an application looks up a resource (for example, a color), -it passes the complete name and complete class of the resource -to a look-up routine. -The resource manager compares this complete specification -against the incomplete specifications of entries in the resource -database, finds the best match, and returns the corresponding -value for that entry. -.LP -The definitions for the resource manager are contained in -.hN X11/Xresource.h . -.NH 2 -Resource File Syntax -.XS -\*(SN Resource File Syntax -.XE -.LP -The syntax of a resource file is a sequence of resource lines -terminated by newline characters or the end of the file. -The syntax of an individual resource line is: -.LP -.\" Start marker code here -.Ds 0 -.TA 1.5i 1.75i -.ta 1.5i 1.75i -ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line> -Comment = "!" {<any character except null or newline>} -IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace -FileName = <valid filename for operating system> -ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value -ResourceName = [Binding] {Component Binding} ComponentName -Binding = "\&." | "*" -WhiteSpace = {<space> | <horizontal tab>} -Component = "?" | ComponentName -ComponentName = NameChar {NameChar} -NameChar = "a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-" -Value = {<any character except null or unescaped newline>} -.De -.\" End marker code here -.LP -Elements separated by vertical bar (|) are alternatives. -Curly braces ({\&.\&.\&.}) indicate zero or more repetitions -of the enclosed elements. -Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional. -Quotes ("\&.\&.\&.") are used around literal characters. -.LP -IncludeFile lines are interpreted by replacing the line with the -contents of the specified file. -The word ``include'' must be in lowercase. -The file name is interpreted relative to the directory of the file in -which the line occurs (for example, if the file name contains no -directory or contains a relative directory specification). -.LP -If a ResourceName contains a contiguous sequence of two or more Binding -characters, the sequence will be replaced with a single ``\&.'' character -if the sequence contains only ``\&.'' characters; -otherwise, the sequence will be replaced with a single ``*'' character. -.LP -A resource database never contains more than one entry for a given -ResourceName. If a resource file contains multiple lines with the -same ResourceName, the last line in the file is used. -.LP -Any white space characters before or after the name or colon in a ResourceSpec -are ignored. -To allow a Value to begin with white space, -the two-character sequence ``\^\\\^\fIspace\fP'' (backslash followed by space) -is recognized and replaced by a space character, -and the two-character sequence ``\^\\\^\fItab\fP'' -(backslash followed by horizontal tab) -is recognized and replaced by a horizontal tab character. -To allow a Value to contain embedded newline characters, -the two-character sequence ``\^\\\^n'' is recognized and replaced by a -newline character. -To allow a Value to be broken across multiple lines in a text file, -the two-character sequence ``\^\\\^\fInewline\fP'' -(backslash followed by newline) is -recognized and removed from the value. -To allow a Value to contain arbitrary character codes, -the four-character sequence ``\^\\\^\fInnn\fP'', -where each \fIn\fP is a digit character in the range of ``0''\^\-``7'', -is recognized and replaced with a single byte that contains -the octal value specified by the sequence. -Finally, the two-character sequence ``\^\\\\'' is recognized -and replaced with a single backslash. -.LP -As an example of these sequences, -the following resource line contains a value consisting of four -characters: a backslash, a null, a ``z'', and a newline: -.Ds -magic.values: \\\\\\\^000\^\\ -z\\\^n -.De -.NH 2 -Resource Manager Matching Rules -.XS -\*(SN Resource Manager Matching Rules -.XE -.LP -The algorithm for determining which resource database entry -matches a given query is the heart of the resource manager. -All queries must fully specify the name and class of the desired resource -(use of the characters ``*'' and ``?'' is not permitted). -The library supports up to 100 components in a full name or class. -Resources are stored in the database with only partially specified -names and classes, using pattern matching constructs. -An asterisk (*) is a loose binding and is used to represent any number -of intervening components, including none. -A period (.) is a tight binding and is used to separate immediately -adjacent components. -A question mark (?) is used to match any single component name or class. -A database entry cannot end in a loose binding; -the final component (which cannot be the character ``?'') must be specified. -The lookup algorithm searches the database for the entry that most -closely matches (is most specific for) the full name and class being queried. -When more than one database entry matches the full name and class, -precedence rules are used to select just one. -.LP -The full name and class are scanned from left to right (from highest -level in the hierarchy to lowest), one component at a time. -At each level, the corresponding component and/or binding of each -matching entry is determined, and these matching components and -bindings are compared according to precedence rules. -Each of the rules is applied at each level before moving to the next level, -until a rule selects a single entry over all others. -The rules, in order of precedence, are: -.IP 1. 5 -An entry that contains a matching component (whether name, class, -or the character ``?'') -takes precedence over entries that elide the level (that is, entries -that match the level in a loose binding). -.IP 2. 5 -An entry with a matching name takes precedence over both -entries with a matching class and entries that match using the character ``?''. -An entry with a matching class takes precedence over -entries that match using the character ``?''. -.IP 3. 5 -An entry preceded by a tight binding takes precedence over entries -preceded by a loose binding. -.LP -To illustrate these rules, -consider the following resource database entries: -.Ds -.TA 2.5i 3.5i -.ta 2.5i 3.5i -xmh*Paned*activeForeground: red \fI(entry A)\fP -*incorporate.Foreground: blue \fI(entry B)\fP -xmh.toc*Command*activeForeground: green \fI(entry C)\fP -xmh.toc*?.Foreground: white \fI(entry D)\fP -xmh.toc*Command.activeForeground: black \fI(entry E)\fP -.De -.LP -Consider a query for the resource: -.LP -.Ds -.TA 3.5i -.ta 3.5i -xmh.toc.messagefunctions.incorporate.activeForeground \fI(name)\fP -Xmh.Paned.Box.Command.Foreground \fI(class)\fP -.De -.LP -At the first level (xmh, Xmh), rule 1 eliminates entry B. -At the second level (toc, Paned), rule 2 eliminates entry A. -At the third level (messagefunctions, Box), no entries are eliminated. -At the fourth level (incorporate, Command), rule 2 eliminates entry D. -At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C. -.NH 2 -Quarks -.XS -\*(SN Quarks -.XE -.LP -Most uses of the resource manager involve defining names, -classes, and representation types as string constants. -However, always referring to strings in the resource manager can be slow, -because it is so heavily used in some toolkits. -To solve this problem, -a shorthand for a string is used in place of the string -in many of the resource manager functions. -Simple comparisons can be performed rather than string comparisons. -The shorthand name for a string is called a quark and is the -type -.PN XrmQuark . -On some occasions, -you may want to allocate a quark that has no string equivalent. -.LP -A quark is to a string what an atom is to a string in the server, -but its use is entirely local to your application. -.LP -.sp -To allocate a new quark, use -.PN XrmUniqueQuark . -.IN "XrmUniqueQuark" "" "@DEF@" -.sM -.FD 0 -XrmQuark XrmUniqueQuark\^(\|) -.FN -.LP -.eM -The -.PN XrmUniqueQuark -function allocates a quark that is guaranteed not to represent any string that -is known to the resource manager. -.LP -.sp -Each name, class, and representation type is typedef'd as an -.PN XrmQuark . -.LP -.sM -.Ds 0 -typedef int XrmQuark, *XrmQuarkList; -typedef XrmQuark XrmName; -typedef XrmQuark XrmClass; -typedef XrmQuark XrmRepresentation; -#define NULLQUARK ((XrmQuark) 0) -.De -.LP -.eM -Lists are represented as null-terminated arrays of quarks. -The size of the array must be large enough for the number of components used. -.LP -.sM -.Ds 0 -typedef XrmQuarkList XrmNameList; -typedef XrmQuarkList XrmClassList; -.De -.LP -.eM -.sp -To convert a string to a quark, use -.PN XrmStringToQuark -or -.PN XrmPermStringToQuark . -.IN "XrmStringToQuark" "" "@DEF@" -.IN "XrmPermStringToQuark" "" "@DEF@" -.sM -.FD 0 -#define XrmStringToName(string) XrmStringToQuark(string) -#define XrmStringToClass(string) XrmStringToQuark(string) -#define XrmStringToRepresentation(string) XrmStringToQuark(string) -.sp -XrmQuark XrmStringToQuark\^(\^\fIstring\fP\^) -.br - char *\fIstring\fP\^; -.sp -XrmQuark XrmPermStringToQuark\^(\^\fIstring\fP\^) -.br - char *\fIstring\fP\^; -.FN -.ds Ql -.IP \fIstring\fP 1i -Specifies the string for which a quark\*(Ql is to be allocated. -.LP -.eM -These functions can be used to convert from string to quark representation. -If the string is not in the Host Portable Character Encoding, -the conversion is implementation-dependent. -The string argument to -.PN XrmStringToQuark -need not be permanently allocated storage. -.PN XrmPermStringToQuark -is just like -.PN XrmStringToQuark , -except that Xlib is permitted to assume the string argument is permanently -allocated, -and, hence, that it can be used as the value to be returned by -.PN XrmQuarkToString . -.LP -For any given quark, if -.PN XrmStringToQuark -returns a non-NULL value, -all future calls will return the same value (identical address). -.LP -.sp -To convert a quark to a string, use -.PN XrmQuarkToString . -.IN "XrmQuarkToString" "" "@DEF@" -.sM -.FD 0 -#define XrmNameToString(name) XrmQuarkToString(name) -#define XrmClassToString(class) XrmQuarkToString(class) -#define XrmRepresentationToString(type) XrmQuarkToString(type) -.sp -char *XrmQuarkToString\^(\^\fIquark\fP\^) -.br - XrmQuark \fIquark\fP\^; -.FN -.IP \fIquark\fP 1i -Specifies the quark for which the equivalent string is desired. -.LP -.eM -These functions can be used to convert from quark representation to string. -The string pointed to by the return value must not be modified or freed. -The returned string is byte-for-byte equal to the original -string passed to one of the string-to-quark routines. -If no string exists for that quark, -.PN XrmQuarkToString -returns NULL. -For any given quark, if -.PN XrmQuarkToString -returns a non-NULL value, -all future calls will return the same value (identical address). -.LP -.sp -To convert a string with one or more components to a quark list, use -.PN XrmStringToQuarkList . -.IN "XrmStringToQuarkList" "" "@DEF@" -.sM -.FD 0 -#define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name)) -#define XrmStringToClassList(str, class) XrmStringToQuarkList((str), (class)) -.sp -void XrmStringToQuarkList\^(\^\fIstring\fP, \fIquarks_return\fP\^) -.br - char *\fIstring\fP\^; -.br - XrmQuarkList \fIquarks_return\fP\^; -.FN -.ds Ql \ list -.IP \fIstring\fP 1i -Specifies the string for which a quark\*(Ql is to be allocated. -.IP \fIquarks_return\fP 1i -Returns the list of quarks. -The caller must allocate sufficient space for the quarks list before calling -.PN XrmStringToQuarkList . -.LP -.eM -The -.PN XrmStringToQuarkList -function converts the null-terminated string (generally a fully qualified name) -to a list of quarks. -Note that the string must be in the valid ResourceName format -(see section 15.1). -If the string is not in the Host Portable Character Encoding, -the conversion is implementation-dependent. -.LP -A binding list is a list of type -.PN XrmBindingList -and indicates if components of name or class lists are bound tightly or loosely -(that is, if wildcarding of intermediate components is specified). -.LP -.Ds 0 -typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList; -.De -.LP -.PN XrmBindTightly -indicates that a period separates the components, and -.PN XrmBindLoosely -indicates that an asterisk separates the components. -.LP -.sp -To convert a string with one or more components to a binding list -and a quark list, use -.PN XrmStringToBindingQuarkList . -.IN "XrmStringToBindingQuarkList" "" "@DEF@" -.sM -.FD 0 -XrmStringToBindingQuarkList\^(\^\fIstring\fP, \fIbindings_return\fP, \ -\fIquarks_return\fP\^) -.br - char *\fIstring\fP\^; -.br - XrmBindingList \fIbindings_return\fP\^; -.br - XrmQuarkList \fIquarks_return\fP\^; -.FN -.ds Ql \ list -.IP \fIstring\fP 1i -Specifies the string for which a quark\*(Ql is to be allocated. -.IP \fIbindings_return\fP 1i -Returns the binding list. -The caller must allocate sufficient space for the binding list before calling -.PN XrmStringToBindingQuarkList . -.IP \fIquarks_return\fP 1i -Returns the list of quarks. -The caller must allocate sufficient space for the quarks list before calling -.PN XrmStringToBindingQuarkList . -.LP -.eM -Component names in the list are separated by a period or -an asterisk character. -The string must be in the format of a valid ResourceName (see section 15.1). -If the string does not start with a period or an asterisk, -a tight binding is assumed. -For example, the string ``*a.b*c'' becomes: -.LP -.Ds 0 -.TA .75i 1.5i 2.25i -.ta .75i 1.5i 2.25i -quarks: a b c -bindings: loose tight loose -.De -.NH 2 -Creating and Storing Databases -.XS -\*(SN Creating and Storing Databases -.XE -.LP -.IN "XrmDatabase" "" "@DEF@" -A resource database is an opaque type, -.PN XrmDatabase . -Each database value is stored in an -.PN XrmValue -structure. -This structure consists of a size, an address, and a representation type. -The size is specified in bytes. -The representation type is a way for you to store data tagged by some -application-defined type (for example, the strings ``font'' or ``color''). -It has nothing to do with the C data type or with its class. -The -.PN XrmValue -structure is defined as: -.LP -.IN "XrmValue" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - unsigned int size; - XPointer addr; -} XrmValue, *XrmValuePtr; -.De -.LP -.eM -.sp -To initialize the resource manager, use -.PN XrmInitialize . -.IN "XrmInitialize" "" "@DEF@" -.sM -.FD 0 -void XrmInitialize\^(\|); -.FN -.LP -.eM -To retrieve a database from disk, use -.PN XrmGetFileDatabase . -.IN "XrmGetFileDatabase" "" "@DEF@" -.sM -.FD 0 -XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^) -.br - char *\fIfilename\fP\^; -.FN -.IP \fIfilename\fP 1i -Specifies the resource database file name. -.LP -.eM -The -.PN XrmGetFileDatabase -function opens the specified file, -creates a new resource database, and loads it with the specifications -read in from the specified file. -The specified file should contain a sequence of entries in valid ResourceLine -format (see section 15.1); the database that results from reading a file -with incorrect syntax is implementation-dependent. -The file is parsed in the current locale, -and the database is created in the current locale. -If it cannot open the specified file, -.PN XrmGetFileDatabase -returns NULL. -.LP -.sp -To store a copy of a database to disk, use -.PN XrmPutFileDatabase . -.IN "XrmPutFileDatabase" "" "@DEF@" -.sM -.FD 0 -void XrmPutFileDatabase\^(\^\fIdatabase\fP, \fIstored_db\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.br - char *\fIstored_db\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the database that is to be used. -.IP \fIstored_db\fP 1i -Specifies the file name for the stored database. -.LP -.eM -The -.PN XrmPutFileDatabase -function stores a copy of the specified database in the specified file. -Text is written to the file as a sequence of entries in valid -ResourceLine format (see section 15.1). -The file is written in the locale of the database. -Entries containing resource names that are not in the Host Portable Character -Encoding or containing values that are not in the encoding of the database -locale, are written in an implementation-dependent manner. -The order in which entries are written is implementation-dependent. -Entries with representation types other than ``String'' are ignored. -.LP -.sp -To obtain a pointer to the screen-independent resources of a display, use -.PN XResourceManagerString . -.IN "XResourceManagerString" "" "@DEF@" -.sM -.FD 0 -char *XResourceManagerString\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XResourceManagerString -function returns the RESOURCE_MANAGER property from the server's root -window of screen zero, which was returned when the connection was opened using -.PN XOpenDisplay . -The property is converted from type STRING to the current locale. -The conversion is identical to that produced by -.PN XmbTextPropertyToTextList -for a single element STRING property. -The returned string is owned by Xlib and should not be freed by the client. -The property value must be in a format that is acceptable to -.PN XrmGetStringDatabase . -If no property exists, NULL is returned. -.LP -.sp -To obtain a pointer to the screen-specific resources of a screen, use -.PN XScreenResourceString . -.IN "XScreenResourceString" "" "@DEF@" -.sM -.FD 0 -char *XScreenResourceString\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the screen. -.LP -.eM -The -.PN XScreenResourceString -function returns the SCREEN_RESOURCES property from the root window of the -specified screen. -The property is converted from type STRING to the current locale. -The conversion is identical to that produced by -.PN XmbTextPropertyToTextList -for a single element STRING property. -The property value must be in a format that is acceptable to -.PN XrmGetStringDatabase . -If no property exists, NULL is returned. -The caller is responsible for freeing the returned string by using -.PN XFree . -.LP -.sp -To create a database from a string, use -.PN XrmGetStringDatabase . -.IN "XrmGetStringDatabase" "" "@DEF@" -.sM -.FD 0 -XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^) -.br - char *\fIdata\fP\^; -.FN -.IP \fIdata\fP 1i -Specifies the database contents using a string. -.LP -.eM -The -.PN XrmGetStringDatabase -function creates a new database and stores the resources specified -in the specified null-terminated string. -.PN XrmGetStringDatabase -is similar to -.PN XrmGetFileDatabase -except that it reads the information out of a string instead of out of a file. -The string should contain a sequence of entries in valid ResourceLine -format (see section 15.1) terminated by a null character; -the database that results from using a string -with incorrect syntax is implementation-dependent. -The string is parsed in the current locale, -and the database is created in the current locale. -.LP -.sp -To obtain the locale name of a database, use -.PN XrmLocaleOfDatabase . -.IN "XrmLocaleOfDatabase" "" "@DEF@" -.sM -.FD 0 -char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.LP -.eM -The -.PN XrmLocaleOfDatabase -function returns the name of the locale bound to the specified -database, as a null-terminated string. -The returned locale name string is owned by Xlib and should not be -modified or freed by the client. -Xlib is not permitted to free the string until the database is destroyed. -Until the string is freed, -it will not be modified by Xlib. -.LP -.sp -To destroy a resource database and free its allocated memory, use -.PN XrmDestroyDatabase . -.IN "XrmDestroyDatabase" "" "@DEF@" -.sM -.FD 0 -void XrmDestroyDatabase\^(\^\fIdatabase\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.LP -.eM -If database is NULL, -.PN XrmDestroyDatabase -returns immediately. -.LP -.sp -To associate a resource database with a display, use -.PN XrmSetDatabase . -.IN "XrmSetDatabase" "" "@DEF@" -.sM -.FD 0 -void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XrmDatabase \fIdatabase\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdatabase\fP 1i -Specifies the resource database. -.LP -.eM -The -.PN XrmSetDatabase -function associates the specified resource database (or NULL) -with the specified display. -The database previously associated with the display (if any) is not destroyed. -A client or toolkit may find this function convenient for retaining a database -once it is constructed. -.LP -.sp -To get the resource database associated with a display, use -.PN XrmGetDatabase . -.IN "XrmGetDatabase" "" "@DEF@" -.sM -.FD 0 -XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XrmGetDatabase -function returns the database associated with the specified display. -It returns NULL if a database has not yet been set. -.NH 2 -Merging Resource Databases -.XS -\*(SN Merging Resource Databases -.XE -.LP -To merge the contents of a resource file into a database, use -.PN XrmCombineFileDatabase . -.IN "XrmCombineFileDatabase" "" "@DEF@" -.sM -.FD 0 -Status XrmCombineFileDatabase(\^\fIfilename\fP, \fItarget_db\fP, \fIoverride\fP\^) -.br - char *\fIfilename\fP; -.br - XrmDatabase *\fItarget_db\fP\^; -.br - Bool \fIoverride\fP; -.FN -.IP \fIfilename\fP 1i -Specifies the resource database file name. -.IP \fItarget_db\fP 1i -Specifies the resource database into which the source -database is to be merged. -.IP \fIoverride\fP 1i -Specifies whether source entries override target ones. -.LP -.eM -The -.PN XrmCombineFileDatabase -function merges the contents of a resource file into a database. -If the same specifier is used for an entry in both the file and -the database, -the entry in the file will replace the entry in the database -if override is -.PN True ; -otherwise, the entry in the file is discarded. -The file is parsed in the current locale. -If the file cannot be read, -a zero status is returned; -otherwise, a nonzero status is returned. -If target_db contains NULL, -.PN XrmCombineFileDatabase -creates and returns a new database to it. -Otherwise, the database pointed to by target_db is not destroyed by the merge. -The database entries are merged without changing values or types, -regardless of the locale of the database. -The locale of the target database is not modified. -.LP -.sp -To merge the contents of one database into another database, use -.PN XrmCombineDatabase . -.IN "XrmCombineDatabase" "" "@DEF@" -.sM -.FD 0 -void XrmCombineDatabase(\^\fIsource_db\fP, \fItarget_db\fP, \fIoverride\fP\^) -.br - XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^; -.br - Bool \fIoverride\fP; -.FN -.IP \fIsource_db\fP 1i -Specifies the resource database that is to be merged into the target database. -.IP \fItarget_db\fP 1i -Specifies the resource database into which the source -database is to be merged. -.IP \fIoverride\fP 1i -Specifies whether source entries override target ones. -.LP -.eM -The -.PN XrmCombineDatabase -function merges the contents of one database into another. -If the same specifier is used for an entry in both databases, -the entry in the source_db will replace the entry in the target_db -if override is -.PN True ; -otherwise, the entry in source_db is discarded. -If target_db contains NULL, -.PN XrmCombineDatabase -simply stores source_db in it. -Otherwise, source_db is destroyed by the merge, but the database pointed -to by target_db is not destroyed. -The database entries are merged without changing values or types, -regardless of the locales of the databases. -The locale of the target database is not modified. -.LP -.sp -To merge the contents of one database into another database with override -semantics, use -.PN XrmMergeDatabases . -.IN "XrmMergeDatabases" "" "@DEF@" -.sM -.FD 0 -void XrmMergeDatabases(\^\fIsource_db\fP, \fItarget_db\fP\^) -.br - XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^; -.FN -.IP \fIsource_db\fP 1i -Specifies the resource database that is to be merged into the target database. -.IP \fItarget_db\fP 1i -Specifies the resource database into which the source -database is to be merged. -.LP -.eM -Calling the -.PN XrmMergeDatabases -function is equivalent to calling the -.PN XrmCombineDatabase -function with an override argument of -.PN True . -.NH 2 -Looking Up Resources -.XS -\*(SN Looking Up Resources -.XE -.LP -To retrieve a resource from a resource database, use -.PN XrmGetResource , -.PN XrmQGetResource , -or -.PN XrmQGetSearchResource . -.LP -.sp -.IN "XrmGetResource" "" "@DEF@" -.sM -.FD 0 -Bool XrmGetResource\^(\^\fIdatabase\fP, \fIstr_name\fP, \fIstr_class\fP, \ -\fIstr_type_return\fP, \fIvalue_return\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.br - char *\fIstr_name\fP\^; -.br - char *\fIstr_class\fP\^; -.br - char **\fIstr_type_return\fP\^; -.br - XrmValue *\fIvalue_return\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the database that is to be used. -.IP \fIstr_name\fP 1i -Specifies the fully qualified name of the value being retrieved (as a string). -.IP \fIstr_class\fP 1i -Specifies the fully qualified class of the value being retrieved (as a string). -.IP \fIstr_type_return\fP 1i -Returns the representation type of the destination (as a string). -.IP \fIvalue_return\fP 1i -Returns the value in the database. -.LP -.eM -.sp -.IN "XrmQGetResource" "" "@DEF@" -.sM -.FD 0 -Bool XrmQGetResource\^(\^\fIdatabase\fP, \fIquark_name\fP, \fIquark_class\fP, \ -\fIquark_type_return\fP, \fIvalue_return\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.br - XrmNameList \fIquark_name\fP\^; -.br - XrmClassList \fIquark_class\fP\^; -.br - XrmRepresentation *\fIquark_type_return\fP\^; -.br - XrmValue *\fIvalue_return\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the database that is to be used. -.IP \fIquark_name\fP 1i -Specifies the fully qualified name of the value being retrieved (as a quark). -.IP \fIquark_class\fP 1i -Specifies the fully qualified class of the value being retrieved (as a quark). -.IP \fIquark_type_return\fP 1i -Returns the representation type of the destination (as a quark). -.IP \fIvalue_return\fP 1i -Returns the value in the database. -.LP -.eM -The -.PN XrmGetResource -and -.PN XrmQGetResource -functions retrieve a resource from the specified database. -Both take a fully qualified name/class pair, a destination -resource representation, and the address of a value -(size/address pair). -The value and returned type point into database memory; -therefore, you must not modify the data. -.LP -The database only frees or overwrites entries on -.PN XrmPutResource , -.PN XrmQPutResource , -or -.PN XrmMergeDatabases . -A client that is not storing new values into the database or -is not merging the database should be safe using the address passed -back at any time until it exits. -If a resource was found, both -.PN XrmGetResource -and -.PN XrmQGetResource -return -.PN True ; -otherwise, they return -.PN False . -.LP -.sp -.EQ -delim %% -.EN -Most applications and toolkits do not make random probes -into a resource database to fetch resources. -The X toolkit access pattern for a resource database is quite stylized. -A series of from 1 to 20 probes is made with only the -last name/class differing in each probe. -The -.PN XrmGetResource -function is at worst a %2 sup n% algorithm, -where \fIn\fP is the length of the name/class list. -This can be improved upon by the application programmer by prefetching a list -of database levels that might match the first part of a name/class list. -.LP -.sp -To obtain a list of database levels, use -.PN XrmQGetSearchList . -.IN "XrmQGetSearchList" "" "@DEF@" -.sM -.FD 0 -typedef XrmHashTable *XrmSearchList; -.sp -Bool XrmQGetSearchList\^(\^\fIdatabase\fP, \fInames\fP, \fIclasses\fP, \ -\fIlist_return\fP, \fIlist_length\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.br - XrmNameList \fInames\fP\^; -.br - XrmClassList \fIclasses\fP\^; -.br - XrmSearchList \fIlist_return\fP\^; -.br - int \fIlist_length\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the database that is to be used. -.IP \fInames\fP 1i -Specifies a list of resource names. -.IP \fIclasses\fP 1i -Specifies a list of resource classes. -.IP \fIlist_return\fP 1i -Returns a search list for further use. -The caller must allocate sufficient space for the list before calling -.PN XrmQGetSearchList . -.IP \fIlist_length\fP 1i -Specifies the number of entries (not the byte size) allocated for list_return. -.LP -.eM -The -.PN XrmQGetSearchList -function takes a list of names and classes -and returns a list of database levels where a match might occur. -The returned list is in best-to-worst order and -uses the same algorithm as -.PN XrmGetResource -for determining precedence. -If list_return was large enough for the search list, -.PN XrmQGetSearchList -returns -.PN True ; -otherwise, it returns -.PN False . -.LP -The size of the search list that the caller must allocate is -dependent upon the number of levels and wildcards in the resource specifiers -that are stored in the database. -The worst case length is %3 sup n%, -where \fIn\fP is the number of name or class components in names or classes. -.LP -When using -.PN XrmQGetSearchList -followed by multiple probes for resources with a common name and class prefix, -only the common prefix should be specified in the name and class list to -.PN XrmQGetSearchList . -.LP -.sp -To search resource database levels for a given resource, use -.PN XrmQGetSearchResource . -.IN "XrmQGetSearchResource" "" "@DEF@" -.sM -.FD 0 -Bool XrmQGetSearchResource\^(\^\fIlist\fP, \fIname\fP, \fIclass\fP, \ -\fItype_return\fP, \fIvalue_return\fP\^) -.br - XrmSearchList \fIlist\fP\^; -.br - XrmName \fIname\fP\^; -.br - XrmClass \fIclass\fP\^; -.br - XrmRepresentation *\fItype_return\fP\^; -.br - XrmValue *\fIvalue_return\fP\^; -.FN -.IP \fIlist\fP 1i -Specifies the search list returned by -.PN XrmQGetSearchList . -.IP \fIname\fP 1i -Specifies the resource name. -.IP \fIclass\fP 1i -Specifies the resource class. -.IP \fItype_return\fP 1i -Returns data representation type. -.IP \fIvalue_return\fP 1i -Returns the value in the database. -.LP -.eM -The -.PN XrmQGetSearchResource -function searches the specified database levels for the resource -that is fully identified by the specified name and class. -The search stops with the first match. -.PN XrmQGetSearchResource -returns -.PN True -if the resource was found; -otherwise, it returns -.PN False . -.LP -A call to -.PN XrmQGetSearchList -with a name and class list containing all but the last component -of a resource name followed by a call to -.PN XrmQGetSearchResource -with the last component name and class returns the same database entry as -.PN XrmGetResource -and -.PN XrmQGetResource -with the fully qualified name and class. -.NH 2 -Storing into a Resource Database -.XS -\*(SN Storing into a Resource Database -.XE -.LP -To store resources into the database, use -.PN XrmPutResource -or -.PN XrmQPutResource . -Both functions take a partial resource specification, a -representation type, and a value. -This value is copied into the specified database. -.LP -.sp -.IN "XrmPutResource" "" "@DEF@" -.sM -.FD 0 -void XrmPutResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fItype\fP, \fIvalue\fP\^) -.br - XrmDatabase *\fIdatabase\fP\^; -.br - char *\fIspecifier\fP\^; -.br - char *\fItype\fP\^; -.br - XrmValue *\fIvalue\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fIspecifier\fP 1i -Specifies a complete or partial specification of the resource. -.IP \fItype\fP 1i -Specifies the type of the resource. -.IP \fIvalue\fP 1i -Specifies the value of the resource, which is specified as a string. -.LP -.eM -If database contains NULL, -.PN XrmPutResource -creates a new database and returns a pointer to it. -.PN XrmPutResource -is a convenience function that calls -.PN XrmStringToBindingQuarkList -followed by: -.LP -.Ds -XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value) -.De -If the specifier and type are not in the Host Portable Character Encoding, -the result is implementation-dependent. -The value is stored in the database without modification. -.LP -.sp -.IN "XrmQPutResource" "" "@DEF@" -.sM -.FD 0 -void XrmQPutResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \ -\fItype\fP, \fIvalue\fP\^) -.br - XrmDatabase *\fIdatabase\fP\^; -.br - XrmBindingList \fIbindings\fP\^; -.br - XrmQuarkList \fIquarks\fP\^; -.br - XrmRepresentation \fItype\fP\^; -.br - XrmValue *\fIvalue\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fIbindings\fP 1i -Specifies a list of bindings. -.IP \fIquarks\fP 1i -Specifies the complete or partial name or the class list of the resource. -.IP \fItype\fP 1i -Specifies the type of the resource. -.IP \fIvalue\fP 1i -Specifies the value of the resource, which is specified as a string. -.LP -.eM -If database contains NULL, -.PN XrmQPutResource -creates a new database and returns a pointer to it. -If a resource entry with the identical bindings and quarks already -exists in the database, the previous type and value are replaced by the new -specified type and value. -The value is stored in the database without modification. -.LP -.sp -To add a resource that is specified as a string, use -.PN XrmPutStringResource . -.IN "XrmPutStringResource" "" "@DEF@" -.sM -.FD 0 -void XrmPutStringResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fIvalue\fP\^) -.br - XrmDatabase *\fIdatabase\fP\^; -.br - char *\fIspecifier\fP\^; -.br - char *\fIvalue\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fIspecifier\fP 1i -Specifies a complete or partial specification of the resource. -.IP \fIvalue\fP 1i -Specifies the value of the resource, which is specified as a string. -.LP -.eM -If database contains NULL, -.PN XrmPutStringResource -creates a new database and returns a pointer to it. -.PN XrmPutStringResource -adds a resource with the specified value to the specified database. -.PN XrmPutStringResource -is a convenience function that first calls -.PN XrmStringToBindingQuarkList -on the specifier and then calls -.PN XrmQPutResource , -using a ``String'' representation type. -If the specifier is not in the Host Portable Character Encoding, -the result is implementation-dependent. -The value is stored in the database without modification. -.LP -.sp -To add a string resource using quarks as a specification, use -.PN XrmQPutStringResource . -.IN "XrmQPutStringResource" "" "@DEF@" -.sM -.FD 0 -void XrmQPutStringResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \ -\fIvalue\fP\^) -.br - XrmDatabase *\fIdatabase\fP\^; -.br - XrmBindingList \fIbindings\fP\^; -.br - XrmQuarkList \fIquarks\fP\^; -.br - char *\fIvalue\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fIbindings\fP 1i -Specifies a list of bindings. -.IP \fIquarks\fP 1i -Specifies the complete or partial name or the class list of the resource. -.IP \fIvalue\fP 1i -Specifies the value of the resource, which is specified as a string. -.LP -.eM -If database contains NULL, -.PN XrmQPutStringResource -creates a new database and returns a pointer to it. -.PN XrmQPutStringResource -is a convenience routine that constructs an -.PN XrmValue -for the value string (by calling -.PN strlen -to compute the size) and -then calls -.PN XrmQPutResource , -using a ``String'' representation type. -The value is stored in the database without modification. -.LP -.sp -To add a single resource entry that is specified as a string that contains -both a name and a value, use -.PN XrmPutLineResource . -.IN "XrmPutLineResource" "" "@DEF@" -.sM -.FD 0 -void XrmPutLineResource\^(\^\fIdatabase\fP, \fIline\fP\^) -.br - XrmDatabase *\fIdatabase\fP\^; -.br - char *\fIline\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fIline\fP 1i -Specifies the resource name and value pair as a single string. -.LP -.eM -If database contains NULL, -.PN XrmPutLineResource -creates a new database and returns a pointer to it. -.PN XrmPutLineResource -adds a single resource entry to the specified database. -The line should be in valid ResourceLine format (see section 15.1) -terminated by a newline or null character; -the database that results from using a string -with incorrect syntax is implementation-dependent. -The string is parsed in the locale of the database. -If the -.PN ResourceName -is not in the Host Portable Character Encoding, -the result is implementation-dependent. -Note that comment lines are not stored. -.NH 2 -Enumerating Database Entries -.XS -\*(SN Enumerating Database Entries -.XE -.LP -To enumerate the entries of a database, use -.PN XrmEnumerateDatabase . -.IN "XrmEnumerateDatabase" "" "@DEF@" -.sM -.TS -lw(.5i) lw(2i) lw(2.5i). -T{ -#define -T} T{ -.PN XrmEnumAllLevels -T} T{ -0 -T} -T{ -#define -T} T{ -.PN XrmEnumOneLevel -T} T{ -1 -T} -.TE -.FD 0 -Bool XrmEnumerateDatabase\^(\^\fIdatabase\fP, \fIname_prefix\fP, \fIclass_prefix\fP, \fImode\fP, \fIproc\fP, \fIarg\fP\^) -.br - XrmDatabase \fIdatabase\fP\^; -.br - XrmNameList \fIname_prefix\fP\^; -.br - XrmClassList \fIclass_prefix\fP\^; -.br - int \fImode\fP\^; -.br - Bool (\^*\fIproc\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fIname_prefix\fP 1i -Specifies the resource name prefix. -.IP \fIclass_prefix\fP 1i -Specifies the resource class prefix. -.IP \fImode\fP 1i -Specifies the number of levels to enumerate. -.IP \fIproc\fP 1i -Specifies the procedure that is to be called for each matching entry. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the procedure. -.LP -.eM -The -.PN XrmEnumerateDatabase -function calls the specified procedure for each resource in the database -that would match some completion of the given name/class resource prefix. -The order in which resources are found is implementation-dependent. -If mode is -.PN XrmEnumOneLevel , -a resource must match the given name/class prefix with -just a single name and class appended. If mode is -.PN XrmEnumAllLevels , -the resource must match the given name/class prefix with one or more names and -classes appended. -If the procedure returns -.PN True , -the enumeration terminates and the function returns -.PN True . -If the procedure always returns -.PN False , -all matching resources are enumerated and the function returns -.PN False . -.LP -The procedure is called with the following arguments: -.LP -.\" Start marker code here -.Ds 0 -.TA .5i 3i -.ta .5i 3i -(*\fIproc\fP\^)(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \fItype\fP, \fIvalue\fP, \fIarg\fP\^) - XrmDatabase *\fIdatabase\fP\^; - XrmBindingList \fIbindings\fP\^; - XrmQuarkList \fIquarks\fP\^; - XrmRepresentation *\fItype\fP\^; - XrmValue *\fIvalue\fP\^; - XPointer \fIarg\fP\^; -.De -.\" End marker code here -.LP -The bindings and quarks lists are terminated by -.PN NULLQUARK . -Note that pointers -to the database and type are passed, but these values should not be modified. -.LP -The procedure must not modify the database. -If Xlib has been initialized for threads, the procedure is called with -the database locked and the result of a call by the procedure to any -Xlib function using the same database is not defined. -.NH 2 -Parsing Command Line Options -.XS -\*(SN Parsing Command Line Options -.XE -.LP -The -.PN XrmParseCommand -function can be used to parse the command line arguments to a program -and modify a resource database with selected entries from the command line. -.LP -.IN "XrmOptionKind" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef enum { - XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value */ - XrmoptionIsArg, /* Value is the option string itself */ - XrmoptionStickyArg, /* Value is characters immediately following option */ - XrmoptionSepArg, /* Value is next argument in argv */ - XrmoptionResArg, /* Resource and value in next argument in argv */ - XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ - XrmoptionSkipLine, /* Ignore this option and the rest of argv */ - XrmoptionSkipNArgs /* Ignore this option and the next - \ \ \ XrmOptionDescRec.value arguments in argv */ -} XrmOptionKind; -.De -.LP -.eM -Note that -.PN XrmoptionSkipArg -is equivalent to -.PN XrmoptionSkipNArgs -with the -.PN XrmOptionDescRec.value -field containing the value one. -Note also that the value zero for -.PN XrmoptionSkipNArgs -indicates that only the option itself is to be skipped. -.LP -.IN "XrmOptionDescRec" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - char *option; /* Option specification string in argv */ - char *specifier; /* Binding and resource name (sans application name) */ - XrmOptionKind argKind; /* Which style of option it is */ - XPointer value; /* Value to provide if XrmoptionNoArg or - \ \ \ XrmoptionSkipNArgs */ -} XrmOptionDescRec, *XrmOptionDescList; -.De -.LP -.eM -.sp -To load a resource database from a C command line, use -.PN XrmParseCommand . -.IN "XrmParseCommand" "" "@DEF@" -.sM -.FD 0 -void XrmParseCommand\^(\^\fIdatabase\fP\^, \^\fItable\fP\^, \^\fItable_count\fP\^, \ -\^\fIname\fP\^, \^\fIargc_in_out\fP\^, \^\fIargv_in_out\fP\^) -.br - XrmDatabase *\fIdatabase\fP\^; -.br - XrmOptionDescList \fItable\fP\^; -.br - int \fItable_count\fP\^; -.br - char *\fIname\fP\^; -.br - int *\fIargc_in_out\fP\^; -.br - char **\fIargv_in_out\fP\^; -.FN -.IP \fIdatabase\fP 1i -Specifies the resource database. -.IP \fItable\fP 1i -Specifies the table of command line arguments to be parsed. -.IP \fItable_count\fP 1i -Specifies the number of entries in the table. -.IP \fIname\fP 1i -Specifies the application name. -.IP \fIargc_in_out\fP 1i -Specifies the number of arguments and returns the number of remaining arguments. -.IP \fIargv_in_out\fP 1i -Specifies the command line arguments -and returns the remaining arguments. -.LP -.eM -The -.PN XrmParseCommand -function parses an (argc, argv) pair according to the specified option table, -loads recognized options into the specified database with type ``String,'' -and modifies the (argc, argv) pair to remove all recognized options. -If database contains NULL, -.PN XrmParseCommand -creates a new database and returns a pointer to it. -Otherwise, entries are added to the database specified. -If a database is created, it is created in the current locale. -.LP -The specified table is used to parse the command line. -Recognized options in the table are removed from argv, -and entries are added to the specified resource database -in the order they occur in argv. -The table entries contain information on the option string, -the option name, the style of option, -and a value to provide if the option kind is -.PN XrmoptionNoArg . -The option names are compared byte-for-byte to arguments in argv, -independent of any locale. -The resource values given in the table are stored in the resource database -without modification. -All resource database entries are created -using a ``String'' representation type. -The argc argument specifies the number of arguments in argv -and is set on return to the remaining number of arguments that were not parsed. -The name argument should be the name of your application -for use in building the database entry. -The name argument is prefixed to the resourceName in the option table -before storing a database entry. -The name argument is treated as a single component, even if it -has embedded periods. -No separating (binding) character is inserted, -so the table must contain either a period (.) or an asterisk (*) -as the first character in each resourceName entry. -To specify a more completely qualified resource name, -the resourceName entry can contain multiple components. -If the name argument and the resourceNames are not in the -Host Portable Character Encoding, -the result is implementation-dependent. -.LP -The following provides a sample option table: -.LP -.Ds 0 -.TA 1.25i 3.25i 4.75i -.ta 1.25i 3.25i 4.75i -static XrmOptionDescRec opTable[] = { -{"\-background", "*background", XrmoptionSepArg, (XPointer) NULL}, -{"\-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL}, -{"\-bg", "*background", XrmoptionSepArg, (XPointer) NULL}, -{"\-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL}, -{"\-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL}, -{"\-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL}, -{"\-display", ".display", XrmoptionSepArg, (XPointer) NULL}, -{"\-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL}, -{"\-fn", "*font", XrmoptionSepArg, (XPointer) NULL}, -{"\-font", "*font", XrmoptionSepArg, (XPointer) NULL}, -{"\-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL}, -{"\-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL}, -{"\-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"}, -{"\-name", ".name", XrmoptionSepArg, (XPointer) NULL}, -{"\-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"}, -{"\-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"}, -{"\-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"}, -{"\-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL}, -{"\-xrm", NULL, XrmoptionResArg, (XPointer) NULL}, -}; -.De -.LP -In this table, if the \-background (or \-bg) option is used to set -background colors, the stored resource specifier matches all -resources of attribute background. -If the \-borderwidth option is used, -the stored resource specifier applies only to border width -attributes of class TopLevelShell (that is, outer-most windows, including -pop-up windows). -If the \-title option is used to set a window name, -only the topmost application windows receive the resource. -.LP -When parsing the command line, -any unique unambiguous abbreviation for an option name in the table is -considered a match for the option. -Note that uppercase and lowercase matter. -.bp diff --git a/libX11/specs/libX11/CH15.xml b/libX11/specs/libX11/CH15.xml new file mode 100644 index 000000000..299a1196f --- /dev/null +++ b/libX11/specs/libX11/CH15.xml @@ -0,0 +1,2485 @@ +<chapter id="resource_manager_functions">
+<title>Resource Manager Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 15 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 15: Resource Manager Functions -->
+<!-- .XE -->
+A program often needs a variety of options in the X environment
+(for example, fonts, colors, icons, and cursors).
+Specifying all of these options on the command line is awkward
+because users may want to customize many aspects of the program
+and need a convenient way to establish these customizations as
+the default settings.
+The resource manager is provided for this purpose.
+Resource specifications are usually stored in human-readable files
+and in server properties.
+</para>
+<para>
+<!-- .LP -->
+The resource manager is a database manager with a twist.
+In most database systems,
+you perform a query using an imprecise specification,
+and you get back a set of records.
+The resource manager, however, allows you to specify a large
+set of values with an imprecise specification, to query the database
+with a precise specification, and to get back only a single value.
+This should be used by applications that need to know what the
+user prefers for colors, fonts, and other resources.
+It is this use as a database for dealing with X resources that
+inspired the name "Resource Manager,"
+although the resource manager can be and is used in other ways.
+</para>
+<para>
+<!-- .LP -->
+For example,
+a user of your application may want to specify
+that all windows should have a blue background
+but that all mail-reading windows should have a red background.
+With well-engineered and coordinated applications,
+a user can define this information using only two lines of specifications.
+</para>
+<para>
+<!-- .LP -->
+As an example of how the resource manager works,
+consider a mail-reading application called xmh.
+Assume that it is designed so that it uses a
+complex window hierarchy all the way down to individual command buttons,
+which may be actual small subwindows in some toolkits.
+These are often called objects or widgets.
+In such toolkit systems,
+each user interface object can be composed of other objects
+and can be assigned a name and a class.
+Fully qualified names or classes can have arbitrary numbers of component names,
+but a fully qualified name always has the same number of component names as a
+fully qualified class.
+This generally reflects the structure of the application as composed
+of these objects, starting with the application itself.
+</para>
+<para>
+<!-- .LP -->
+For example, the xmh mail program has a name "xmh" and is one
+of a class of "Mail" programs.
+By convention, the first character of class components is capitalized,
+and the first letter of name components is in lowercase.
+Each name and class finally has an attribute
+(for example, "foreground" or "font").
+If each window is properly assigned a name and class,
+it is easy for the user to specify attributes of any portion
+of the application.
+</para>
+<para>
+<!-- .LP -->
+At the top level,
+the application might consist of a paned window (that is, a window divided
+into several sections) named "toc".
+One pane of the paned window is a button box window named "buttons"
+and is filled with command buttons.
+One of these command buttons is used to incorporate
+new mail and has the name "incorporate".
+This window has a fully qualified name, "xmh.toc.buttons.incorporate",
+and a fully qualified class, "Xmh.Paned.Box.Command".
+Its fully qualified name is the name of its parent, "xmh.toc.buttons",
+followed by its name, "incorporate".
+Its class is the class of its parent, "Xmh.Paned.Box",
+followed by its particular class, "Command".
+The fully qualified name of a resource is
+the attribute's name appended to the object's fully qualified
+name, and the fully qualified class is its class appended to the object's
+class.
+</para>
+<para>
+<!-- .LP -->
+The incorporate button might need the following resources:
+Title string,
+Font,
+Foreground color for its inactive state,
+Background color for its inactive state,
+Foreground color for its active state, and
+Background color for its active state.
+Each resource is considered
+to be an attribute of the button and, as such, has a name and a class.
+For example, the foreground color for the button in
+its active state might be named "activeForeground",
+and its class might be "Foreground".
+</para>
+<para>
+<!-- .LP -->
+When an application looks up a resource (for example, a color),
+it passes the complete name and complete class of the resource
+to a look-up routine.
+The resource manager compares this complete specification
+against the incomplete specifications of entries in the resource
+database, finds the best match, and returns the corresponding
+value for that entry.
+</para>
+<para>
+<!-- .LP -->
+The definitions for the resource manager are contained in
+<!-- .hN X11/Xresource.h . -->
+</para>
+<sect1 id="Resource_File_Syntax">
+<title>Resource File Syntax</title>
+<!-- .XS -->
+<!-- (SN Resource File Syntax -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The syntax of a resource file is a sequence of resource lines
+terminated by newline characters or the end of the file.
+The syntax of an individual resource line is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA 1.5i 1.75i -->
+<!-- .ta 1.5i 1.75i -->
+ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
+Comment = "!" {<any character except null or newline>}
+IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
+FileName = <valid filename for operating system>
+ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
+ResourceName = [Binding] {Component Binding} ComponentName
+Binding = "." | "*"
+WhiteSpace = {<space> | <horizontal tab>}
+Component = "?" | ComponentName
+ComponentName = NameChar {NameChar}
+NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
+Value = {<any character except null or unescaped newline>}
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Elements separated by vertical bar (|) are alternatives.
+Curly braces ({......}) indicate zero or more repetitions
+of the enclosed elements.
+Square brackets ([......]) indicate that the enclosed element is optional.
+Quotes ("......") are used around literal characters.
+</para>
+<para>
+<!-- .LP -->
+IncludeFile lines are interpreted by replacing the line with the
+contents of the specified file.
+The word "include" must be in lowercase.
+The file name is interpreted relative to the directory of the file in
+which the line occurs (for example, if the file name contains no
+directory or contains a relative directory specification).
+</para>
+<para>
+<!-- .LP -->
+If a ResourceName contains a contiguous sequence of two or more Binding
+characters, the sequence will be replaced with a single ".." character
+if the sequence contains only ".." characters;
+otherwise, the sequence will be replaced with a single "*" character.
+</para>
+<para>
+<!-- .LP -->
+A resource database never contains more than one entry for a given
+ResourceName. If a resource file contains multiple lines with the
+same ResourceName, the last line in the file is used.
+</para>
+<para>
+<!-- .LP -->
+Any white space characters before or after the name or colon in a ResourceSpec
+are ignored.
+To allow a Value to begin with white space,
+the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)
+is recognized and replaced by a space character,
+and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"
+(backslash followed by horizontal tab)
+is recognized and replaced by a horizontal tab character.
+To allow a Value to contain embedded newline characters,
+the two-character sequence "\\n" is recognized and replaced by a
+newline character.
+To allow a Value to be broken across multiple lines in a text file,
+the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"
+(backslash followed by newline) is
+recognized and removed from the value.
+To allow a Value to contain arbitrary character codes,
+the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",
+where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",
+is recognized and replaced with a single byte that contains
+the octal value specified by the sequence.
+Finally, the two-character sequence "\newline" is recognized
+and replaced with a single backslash.
+</para>
+<para>
+<!-- .LP -->
+As an example of these sequences,
+the following resource line contains a value consisting of four
+characters: a backslash, a null, a "z", and a newline:
+<literallayout class="monospaced">
+magic.values: \\000\
+z\n
+</literallayout>
+</para>
+</sect1>
+<sect1 id="Resource_Manager_Matching_Rules">
+<title>Resource Manager Matching Rules</title>
+<!-- .XS -->
+<!-- (SN Resource Manager Matching Rules -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The algorithm for determining which resource database entry
+matches a given query is the heart of the resource manager.
+All queries must fully specify the name and class of the desired resource
+(use of the characters "*" and "?" is not permitted).
+The library supports up to 100 components in a full name or class.
+Resources are stored in the database with only partially specified
+names and classes, using pattern matching constructs.
+An asterisk (*) is a loose binding and is used to represent any number
+of intervening components, including none.
+A period (.) is a tight binding and is used to separate immediately
+adjacent components.
+A question mark (?) is used to match any single component name or class.
+A database entry cannot end in a loose binding;
+the final component (which cannot be the character "?") must be specified.
+The lookup algorithm searches the database for the entry that most
+closely matches (is most specific for) the full name and class being queried.
+When more than one database entry matches the full name and class,
+precedence rules are used to select just one.
+</para>
+<para>
+<!-- .LP -->
+The full name and class are scanned from left to right (from highest
+level in the hierarchy to lowest), one component at a time.
+At each level, the corresponding component and/or binding of each
+matching entry is determined, and these matching components and
+bindings are compared according to precedence rules.
+Each of the rules is applied at each level before moving to the next level,
+until a rule selects a single entry over all others.
+The rules, in order of precedence, are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+An entry that contains a matching component (whether name, class,
+or the character "?")
+takes precedence over entries that elide the level (that is, entries
+that match the level in a loose binding).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An entry with a matching name takes precedence over both
+entries with a matching class and entries that match using the character "?".
+An entry with a matching class takes precedence over
+entries that match using the character "?".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An entry preceded by a tight binding takes precedence over entries
+preceded by a loose binding.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To illustrate these rules,
+consider the following resource database entries:
+<literallayout class="monospaced">
+<!-- .TA 2.5i 3.5i -->
+<!-- .ta 2.5i 3.5i -->
+xmh*Paned*activeForeground: red <emphasis remap='I'>(entry A)</emphasis>
+*incorporate.Foreground: blue <emphasis remap='I'>(entry B)</emphasis>
+xmh.toc*Command*activeForeground: green <emphasis remap='I'>(entry C)</emphasis>
+xmh.toc*?.Foreground: white <emphasis remap='I'>(entry D)</emphasis>
+xmh.toc*Command.activeForeground: black <emphasis remap='I'>(entry E)</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Consider a query for the resource:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 3.5i -->
+<!-- .ta 3.5i -->
+xmh.toc.messagefunctions.incorporate.activeForeground <emphasis remap='I'>(name)</emphasis>
+Xmh.Paned.Box.Command.Foreground <emphasis remap='I'>(class)</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+At the first level (xmh, Xmh), rule 1 eliminates entry B.
+At the second level (toc, Paned), rule 2 eliminates entry A.
+At the third level (messagefunctions, Box), no entries are eliminated.
+At the fourth level (incorporate, Command), rule 2 eliminates entry D.
+At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
+</para>
+</sect1>
+<sect1 id="Quarks">
+<title>Quarks</title>
+<!-- .XS -->
+<!-- (SN Quarks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Most uses of the resource manager involve defining names,
+classes, and representation types as string constants.
+However, always referring to strings in the resource manager can be slow,
+because it is so heavily used in some toolkits.
+To solve this problem,
+a shorthand for a string is used in place of the string
+in many of the resource manager functions.
+Simple comparisons can be performed rather than string comparisons.
+The shorthand name for a string is called a quark and is the
+type
+<function>XrmQuark</function>.
+On some occasions,
+you may want to allocate a quark that has no string equivalent.
+</para>
+<para>
+<!-- .LP -->
+A quark is to a string what an atom is to a string in the server,
+but its use is entirely local to your application.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a new quark, use
+<function>XrmUniqueQuark</function>.
+</para>
+<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>
+<!-- .sM -->
+<para>XrmQuark XrmUniqueQuark()</para>
+<!-- .FN -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmUniqueQuark</function>
+function allocates a quark that is guaranteed not to represent any string that
+is known to the resource manager.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Each name, class, and representation type is typedef'd as an
+<function>XrmQuark</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef int XrmQuark, *XrmQuarkList;
+typedef XrmQuark XrmName;
+typedef XrmQuark XrmClass;
+typedef XrmQuark XrmRepresentation;
+#define NULLQUARK ((XrmQuark) 0)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Lists are represented as null-terminated arrays of quarks.
+The size of the array must be large enough for the number of components used.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef XrmQuarkList XrmNameList;
+typedef XrmQuarkList XrmClassList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To convert a string to a quark, use
+<function>XrmStringToQuark</function>
+or
+<function>XrmPermStringToQuark</function>.
+</para>
+<literallayout class="monospaced">
+#define XrmStringToName(string) XrmStringToQuark(string)
+#define XrmStringToClass(string) XrmStringToQuark(string)
+#define XrmStringToRepresentation(string) XrmStringToQuark(string)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>
+<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string for which a quark(Ql is to be allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+These functions can be used to convert from string to quark representation.
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+The string argument to
+<function>XrmStringToQuark</function>
+need not be permanently allocated storage.
+<function>XrmPermStringToQuark</function>
+is just like
+<function>XrmStringToQuark</function>,
+except that Xlib is permitted to assume the string argument is permanently
+allocated,
+and, hence, that it can be used as the value to be returned by
+<function>XrmQuarkToString</function>.
+</para>
+<para>
+<!-- .LP -->
+For any given quark, if
+<function>XrmStringToQuark</function>
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a quark to a string, use
+<function>XrmQuarkToString</function>.
+</para>
+
+<literallayout class="monospaced">
+#define XrmNameToString(name) XrmQuarkToString(name)
+#define XrmClassToString(class) XrmQuarkToString(name)
+#define XrmRepresentationToString(type) XrmQuarkToString(type)
+</literallayout>
+<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char <function> *XrmQuarkToString</function></funcdef>
+ <paramdef>XrmQuark<parameter> quark</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the quark for which the equivalent string is desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->
+<para>
+These functions can be used to convert from quark representation to string.
+The string pointed to by the return value must not be modified or freed.
+The returned string is byte-for-byte equal to the original
+string passed to one of the string-to-quark routines.
+If no string exists for that quark,
+<function>XrmQuarkToString</function>
+returns NULL.
+For any given quark, if
+<function>XrmQuarkToString</function>
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a string with one or more components to a quark list, use
+<function>XrmStringToQuarkList</function>.
+</para>
+
+<literallayout class="monospaced">
+#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name))
+#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
+</literallayout>
+
+<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmStringToQuarkList</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql \ list -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string for which a quark(Ql is to be allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling
+<function>XrmStringToQuarkList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmStringToQuarkList</function>
+function converts the null-terminated string (generally a fully qualified name)
+to a list of quarks.
+Note that the string must be in the valid ResourceName format
+(see section 15.1).
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+A binding list is a list of type
+<function>XrmBindingList</function>
+and indicates if components of name or class lists are bound tightly or loosely
+(that is, if wildcarding of intermediate components is specified).
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XrmBindTightly</function>
+indicates that a period separates the components, and
+<function>XrmBindLoosely</function>
+indicates that an asterisk separates the components.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a string with one or more components to a binding list
+and a quark list, use
+<function>XrmStringToBindingQuarkList</function>.
+<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XrmStringToBindingQuarkList</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql \ list -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string for which a quark(Ql is to be allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bindings_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the binding list.
+The caller must allocate sufficient space for the binding list before calling
+<function>XrmStringToBindingQuarkList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling
+<function>XrmStringToBindingQuarkList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Component names in the list are separated by a period or
+an asterisk character.
+The string must be in the format of a valid ResourceName (see section 15.1).
+If the string does not start with a period or an asterisk,
+a tight binding is assumed.
+For example, the string ``*a.b*c'' becomes:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .75i 1.5i 2.25i -->
+<!-- .ta .75i 1.5i 2.25i -->
+quarks: a b c
+bindings: loose tight loose
+</literallayout>
+</para>
+</sect1>
+<sect1 id="Creating_and_Storing_Databases">
+<title>Creating and Storing Databases</title>
+<!-- .XS -->
+<!-- (SN Creating and Storing Databases -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>
+A resource database is an opaque type,
+<function>XrmDatabase</function>.
+Each database value is stored in an
+<function>XrmValue </function>
+structure.
+This structure consists of a size, an address, and a representation type.
+The size is specified in bytes.
+The representation type is a way for you to store data tagged by some
+application-defined type (for example, the strings ``font'' or ``color'').
+It has nothing to do with the C data type or with its class.
+The
+<function>XrmValue </function>
+structure is defined as:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ unsigned int size;
+ XPointer addr;
+} XrmValue, *XrmValuePtr;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To initialize the resource manager, use
+<function>XrmInitialize</function>.
+<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmInitialize</function></funcdef>
+ <paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To retrieve a database from disk, use
+<function>XrmGetFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XrmDatabase <function> XrmGetFileDatabase</function></funcdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database file name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetFileDatabase</function>
+function opens the specified file,
+creates a new resource database, and loads it with the specifications
+read in from the specified file.
+The specified file should contain a sequence of entries in valid ResourceLine
+format (see section 15.1); the database that results from reading a file
+with incorrect syntax is implementation-dependent.
+The file is parsed in the current locale,
+and the database is created in the current locale.
+If it cannot open the specified file,
+<function>XrmGetFileDatabase</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a copy of a database to disk, use
+<function>XrmPutFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmPutFileDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>char<parameter> *stored_db</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stored_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file name for the stored database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmPutFileDatabase</function>
+function stores a copy of the specified database in the specified file.
+Text is written to the file as a sequence of entries in valid
+ResourceLine format (see section 15.1).
+The file is written in the locale of the database.
+Entries containing resource names that are not in the Host Portable Character
+Encoding or containing values that are not in the encoding of the database
+locale, are written in an implementation-dependent manner.
+The order in which entries are written is implementation-dependent.
+Entries with representation types other than ``String'' are ignored.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pointer to the screen-independent resources of a display, use
+<function>XResourceManagerString</function>.
+<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XResourceManagerString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XResourceManagerString</function>
+function returns the RESOURCE_MANAGER property from the server's root
+window of screen zero, which was returned when the connection was opened using
+<function>XOpenDisplay</function>.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by
+<function>XmbTextPropertyToTextList</function>
+for a single element STRING property.
+The returned string is owned by Xlib and should not be freed by the client.
+The property value must be in a format that is acceptable to
+<function>XrmGetStringDatabase</function>.
+If no property exists, NULL is returned.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pointer to the screen-specific resources of a screen, use
+<function>XScreenResourceString</function>.
+<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XScreenResourceString</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XScreenResourceString</function>
+function returns the SCREEN_RESOURCES property from the root window of the
+specified screen.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by
+<function>XmbTextPropertyToTextList</function>
+for a single element STRING property.
+The property value must be in a format that is acceptable to
+<function>XrmGetStringDatabase</function>.
+If no property exists, NULL is returned.
+The caller is responsible for freeing the returned string by using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a database from a string, use
+<function>XrmGetStringDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XrmDatabase <function> XrmGetStringDatabase</function></funcdef>
+ <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database contents using a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetStringDatabase</function>
+function creates a new database and stores the resources specified
+in the specified null-terminated string.
+<function>XrmGetStringDatabase</function>
+is similar to
+<function>XrmGetFileDatabase</function>
+except that it reads the information out of a string instead of out of a file.
+The string should contain a sequence of entries in valid ResourceLine
+format (see section 15.1) terminated by a null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the current locale,
+and the database is created in the current locale.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the locale name of a database, use
+<function>XrmLocaleOfDatabase</function>.
+<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XrmLocaleOfDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmLocaleOfDatabase</function>
+function returns the name of the locale bound to the specified
+database, as a null-terminated string.
+The returned locale name string is owned by Xlib and should not be
+modified or freed by the client.
+Xlib is not permitted to free the string until the database is destroyed.
+Until the string is freed,
+it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a resource database and free its allocated memory, use
+<function>XrmDestroyDatabase</function>.
+<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmDestroyDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database is NULL,
+<function>XrmDestroyDatabase</function>
+returns immediately.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To associate a resource database with a display, use
+<function>XrmSetDatabase</function>.
+<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmSetDatabase</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmSetDatabase</function>
+function associates the specified resource database (or NULL)
+with the specified display.
+The database previously associated with the display (if any) is not destroyed.
+A client or toolkit may find this function convenient for retaining a database
+once it is constructed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the resource database associated with a display, use
+<function>XrmGetDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XrmDatabase <function> XrmGetDatabase</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetDatabase</function>
+function returns the database associated with the specified display.
+It returns NULL if a database has not yet been set.
+</para>
+</sect1>
+<sect1 id="Merging_Resource_Databases">
+<title>Merging Resource Databases</title>
+<!-- .XS -->
+<!-- (SN Merging Resource Databases -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To merge the contents of a resource file into a database, use
+<function>XrmCombineFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function> XrmCombineFileDatabase</function></funcdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>
+ <paramdef>Bool<parameter> override</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database file name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database into which the source
+database is to be merged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>override</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether source entries override target ones.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmCombineFileDatabase</function>
+function merges the contents of a resource file into a database.
+If the same specifier is used for an entry in both the file and
+the database,
+the entry in the file will replace the entry in the database
+if override is
+<function>True</function>;
+otherwise, the entry in the file is discarded.
+The file is parsed in the current locale.
+If the file cannot be read,
+a zero status is returned;
+otherwise, a nonzero status is returned.
+If target_db contains NULL,
+<function>XrmCombineFileDatabase</function>
+creates and returns a new database to it.
+Otherwise, the database pointed to by target_db is not destroyed by the merge.
+The database entries are merged without changing values or types,
+regardless of the locale of the database.
+The locale of the target database is not modified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To merge the contents of one database into another database, use
+<function>XrmCombineDatabase</function>.
+<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmCombineDatabase</function></funcdef>
+ <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
+ <paramdef>Bool<parameter> override</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database that is to be merged into the target database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database into which the source
+database is to be merged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>override</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether source entries override target ones.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmCombineDatabase</function>
+function merges the contents of one database into another.
+If the same specifier is used for an entry in both databases,
+the entry in the source_db will replace the entry in the target_db
+if override is
+<function>True</function>;
+otherwise, the entry in source_db is discarded.
+If target_db contains NULL,
+<function>XrmCombineDatabase</function>
+simply stores source_db in it.
+Otherwise, source_db is destroyed by the merge, but the database pointed
+to by target_db is not destroyed.
+The database entries are merged without changing values or types,
+regardless of the locales of the databases.
+The locale of the target database is not modified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To merge the contents of one database into another database with override
+semantics, use
+<function>XrmMergeDatabases</function>.
+<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmMergeDatabases</function></funcdef>
+ <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database that is to be merged into the target database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database into which the source
+database is to be merged.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Calling the
+<function>XrmMergeDatabases</function>
+function is equivalent to calling the
+<function>XrmCombineDatabase</function>
+function with an override argument of
+<function>True</function>.
+</para>
+</sect1>
+<sect1 id="Looking_Up_Resources">
+<title>Looking Up Resources</title>
+<!-- .XS -->
+<!-- (SN Looking Up Resources -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To retrieve a resource from a resource database, use
+<function>XrmGetResource</function>,
+<function>XrmQGetResource</function>,
+or
+<function>XrmQGetSearchResource</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XrmGetResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>char<parameter> *str_name</parameter></paramdef>
+ <paramdef>char<parameter> *str_class</parameter></paramdef>
+ <paramdef>char<parameter> **str_type_return</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>str_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified name of the value being retrieved (as a string).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>str_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified class of the value being retrieved (as a string).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>str_type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the representation type of the destination (as a string).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XrmQGetResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>
+ <paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>
+ <paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified name of the value being retrieved (as a quark).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified class of the value being retrieved (as a quark).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark_type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the representation type of the destination (as a quark).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetResource </function>
+and
+<function>XrmQGetResource </function>
+functions retrieve a resource from the specified database.
+Both take a fully qualified name/class pair, a destination
+resource representation, and the address of a value
+(size/address pair).
+The value and returned type point into database memory;
+therefore, you must not modify the data.
+</para>
+<para>
+<!-- .LP -->
+The database only frees or overwrites entries on
+<function>XrmPutResource</function>,
+<function>XrmQPutResource</function>,
+or
+<function>XrmMergeDatabases</function>.
+A client that is not storing new values into the database or
+is not merging the database should be safe using the address passed
+back at any time until it exits.
+If a resource was found, both
+<function>XrmGetResource </function>
+and
+<function>XrmQGetResource </function>
+return
+<function>True</function>;
+otherwise, they return
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .EQ -->
+<!-- delim %% -->
+<!-- .EN -->
+Most applications and toolkits do not make random probes
+into a resource database to fetch resources.
+The X toolkit access pattern for a resource database is quite stylized.
+A series of from 1 to 20 probes is made with only the
+last name/class differing in each probe.
+The
+<function>XrmGetResource </function>
+function is at worst a %2 sup n% algorithm, <!-- FIXME: log(n) ? -->
+where <emphasis remap='I'>n</emphasis> is the length of the name/class list.
+This can be improved upon by the application programmer by prefetching a list
+of database levels that might match the first part of a name/class list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of database levels, use
+<function>XrmQGetSearchList</function>.
+<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XrmQGetSearchResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>XrmNameList<parameter> names</parameter></paramdef>
+ <paramdef>XrmClassList<parameter> classes</parameter></paramdef>
+ <paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>
+ <paramdef>int<parameter> list_length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of resource names.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>classes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of resource classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a search list for further use.
+The caller must allocate sufficient space for the list before calling
+<function>XrmQGetSearchList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries (not the byte size) allocated for list_return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmQGetSearchList</function>
+function takes a list of names and classes
+and returns a list of database levels where a match might occur.
+The returned list is in best-to-worst order and
+uses the same algorithm as
+<function>XrmGetResource </function>
+for determining precedence.
+If list_return was large enough for the search list,
+<function>XrmQGetSearchList</function>
+returns
+<function>True</function>;
+otherwise, it returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+The size of the search list that the caller must allocate is
+dependent upon the number of levels and wildcards in the resource specifiers
+that are stored in the database.
+The worst case length is %3 sup n%,
+where <emphasis remap='I'>n</emphasis> is the number of name or class components in names or classes.
+</para>
+<para>
+<!-- .LP -->
+When using
+<function>XrmQGetSearchList </function>
+followed by multiple probes for resources with a common name and class prefix,
+only the common prefix should be specified in the name and class list to
+<function>XrmQGetSearchList</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To search resource database levels for a given resource, use
+<function>XrmQGetSearchResource</function>.
+<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XrmQGetSearchResource</function></funcdef>
+ <paramdef>XrmSearchList<parameter> list</parameter></paramdef>
+ <paramdef>XrmName<parameter> name</parameter></paramdef>
+ <paramdef>XrmClass<parameter> class</parameter></paramdef>
+ <paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the search list returned by
+<function>XrmQGetSearchList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns data representation type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmQGetSearchResource</function>
+function searches the specified database levels for the resource
+that is fully identified by the specified name and class.
+The search stops with the first match.
+<function>XrmQGetSearchResource</function>
+returns
+<function>True </function>
+if the resource was found;
+otherwise, it returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+A call to
+<function>XrmQGetSearchList </function>
+with a name and class list containing all but the last component
+of a resource name followed by a call to
+<function>XrmQGetSearchResource </function>
+with the last component name and class returns the same database entry as
+<function>XrmGetResource </function>
+and
+<function>XrmQGetResource </function>
+with the fully qualified name and class.
+</para>
+</sect1>
+<sect1 id="Storing_into_a_Resource_Database">
+<title>Storing into a Resource Database</title>
+<!-- .XS -->
+<!-- (SN Storing into a Resource Database -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To store resources into the database, use
+<function>XrmPutResource </function>
+or
+<function>XrmQPutResource</function>.
+Both functions take a partial resource specification, a
+representation type, and a value.
+This value is copied into the specified database.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmPutResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>char<parameter> *specifier</parameter></paramdef>
+ <paramdef>char<parameter> *type</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>specifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a complete or partial specification of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutResource</function>
+is a convenience function that calls
+<function>XrmStringToBindingQuarkList</function>
+followed by:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
+</literallayout>
+If the specifier and type are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmQPutResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
+ <paramdef>XrmRepresentation<parameter> type</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bindings</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of bindings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the complete or partial name or the class list of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmQPutResource</function>
+creates a new database and returns a pointer to it.
+If a resource entry with the identical bindings and quarks already
+exists in the database, the previous type and value are replaced by the new
+specified type and value.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a resource that is specified as a string, use
+<function>XrmPutStringResource</function>.
+<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmPutStringResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>char<parameter> *specifier</parameter></paramdef>
+ <paramdef>char<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>specifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a complete or partial specification of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutStringResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutStringResource</function>
+adds a resource with the specified value to the specified database.
+<function>XrmPutStringResource</function>
+is a convenience function that first calls
+<function>XrmStringToBindingQuarkList</function>
+on the specifier and then calls
+<function>XrmQPutResource</function>,
+using a ``String'' representation type.
+If the specifier is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a string resource using quarks as a specification, use
+<function>XrmQPutStringResource</function>.
+<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmQPutStringResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
+ <paramdef>char<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bindings</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of bindings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the complete or partial name or the class list of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmQPutStringResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmQPutStringResource</function>
+is a convenience routine that constructs an
+<function>XrmValue</function>
+for the value string (by calling
+<function>strlen</function>
+to compute the size) and
+then calls
+<function>XrmQPutResource</function>,
+using a ``String'' representation type.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a single resource entry that is specified as a string that contains
+both a name and a value, use
+<function>XrmPutLineResource</function>.
+<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmPutLineResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>char<parameter> *line</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>line</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name and value pair as a single string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutLineResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutLineResource</function>
+adds a single resource entry to the specified database.
+The line should be in valid ResourceLine format (see section 15.1)
+terminated by a newline or null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the locale of the database.
+If the
+<function>ResourceName</function>
+is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Note that comment lines are not stored.
+</para>
+</sect1>
+<sect1 id="Enumerating_Database_Entries">
+<title>Enumerating Database Entries</title>
+<!-- .XS -->
+<!-- (SN Enumerating Database Entries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To enumerate the entries of a database, use
+<function>XrmEnumerateDatabase</function>.
+<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+#define XrmEnumAllLevels 0
+#define XrmEnumOneLevel 0
+</literallayout>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XrmEnumerateDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>
+ <paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+ <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name_prefix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name prefix.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_prefix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class prefix.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of levels to enumerate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called for each matching entry.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmEnumerateDatabase</function>
+function calls the specified procedure for each resource in the database
+that would match some completion of the given name/class resource prefix.
+The order in which resources are found is implementation-dependent.
+If mode is
+<function>XrmEnumOneLevel</function>,
+a resource must match the given name/class prefix with
+just a single name and class appended. If mode is
+<function>XrmEnumAllLevels</function>,
+the resource must match the given name/class prefix with one or more names and
+classes appended.
+If the procedure returns
+<function>True</function>,
+the enumeration terminates and the function returns
+<function>True</function>.
+If the procedure always returns
+<function>False</function>,
+all matching resources are enumerated and the function returns
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+The procedure is called with the following arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)
+ XrmDatabase *<emphasis remap='I'>database</emphasis>;
+ XrmBindingList <emphasis remap='I'>bindings</emphasis>;
+ XrmQuarkList <emphasis remap='I'>quarks</emphasis>;
+ XrmRepresentation *<emphasis remap='I'>type</emphasis>;
+ XrmValue *<emphasis remap='I'>value</emphasis>;
+ XPointer <emphasis remap='I'>arg</emphasis>;
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The bindings and quarks lists are terminated by
+<function>NULLQUARK</function>.
+Note that pointers
+to the database and type are passed, but these values should not be modified.
+</para>
+<para>
+<!-- .LP -->
+The procedure must not modify the database.
+If Xlib has been initialized for threads, the procedure is called with
+the database locked and the result of a call by the procedure to any
+Xlib function using the same database is not defined.
+</para>
+</sect1>
+<sect1 id="Parsing_Command_Line_Options">
+<title>Parsing Command Line Options</title>
+<!-- .XS -->
+<!-- (SN Parsing Command Line Options -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XrmParseCommand</function>
+function can be used to parse the command line arguments to a program
+and modify a resource database with selected entries from the command line.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+ XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value */
+ XrmoptionIsArg, /* Value is the option string itself */
+ XrmoptionStickyArg, /* Value is characters immediately following option */
+ XrmoptionSepArg, /* Value is next argument in argv */
+ XrmoptionResArg, /* Resource and value in next argument in argv */
+ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
+ XrmoptionSkipLine, /* Ignore this option and the rest of argv */
+ XrmoptionSkipNArgs /* Ignore this option and the next
+ \ \ \ XrmOptionDescRec.value arguments in argv */
+} XrmOptionKind;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Note that
+<function>XrmoptionSkipArg</function>
+is equivalent to
+<function>XrmoptionSkipNArgs</function>
+with the
+<function>XrmOptionDescRec.value</function>
+field containing the value one.
+Note also that the value zero for
+<function>XrmoptionSkipNArgs</function>
+indicates that only the option itself is to be skipped.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ char *option; /* Option specification string in argv */
+ char *specifier; /* Binding and resource name (sans application name) */
+ XrmOptionKind argKind; /* Which style of option it is */
+ XPointer value; /* Value to provide if XrmoptionNoArg or
+ \ \ \ XrmoptionSkipNArgs */
+} XrmOptionDescRec, *XrmOptionDescList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To load a resource database from a C command line, use
+<function>XrmParseCommand</function>.
+<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XrmParseCommand</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>
+ <paramdef>int<parameter> table_count</parameter></paramdef>
+ <paramdef>char<parameter> *name</parameter></paramdef>
+ <paramdef>int<parameter> *argc_in_out</parameter></paramdef>
+ <paramdef>char<parameter> **argv_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the table of command line arguments to be parsed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments and returns the number of remaining arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line arguments
+and returns the remaining arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmParseCommand</function>
+function parses an (argc, argv) pair according to the specified option table,
+loads recognized options into the specified database with type ``String,''
+and modifies the (argc, argv) pair to remove all recognized options.
+If database contains NULL,
+<function>XrmParseCommand</function>
+creates a new database and returns a pointer to it.
+Otherwise, entries are added to the database specified.
+If a database is created, it is created in the current locale.
+</para>
+<para>
+<!-- .LP -->
+The specified table is used to parse the command line.
+Recognized options in the table are removed from argv,
+and entries are added to the specified resource database
+in the order they occur in argv.
+The table entries contain information on the option string,
+the option name, the style of option,
+and a value to provide if the option kind is
+<function>XrmoptionNoArg</function>.
+The option names are compared byte-for-byte to arguments in argv,
+independent of any locale.
+The resource values given in the table are stored in the resource database
+without modification.
+All resource database entries are created
+using a ``String'' representation type.
+The argc argument specifies the number of arguments in argv
+and is set on return to the remaining number of arguments that were not parsed.
+The name argument should be the name of your application
+for use in building the database entry.
+The name argument is prefixed to the resourceName in the option table
+before storing a database entry.
+The name argument is treated as a single component, even if it
+has embedded periods.
+No separating (binding) character is inserted,
+so the table must contain either a period (.) or an asterisk (*)
+as the first character in each resourceName entry.
+To specify a more completely qualified resource name,
+the resourceName entry can contain multiple components.
+If the name argument and the resourceNames are not in the
+Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The following provides a sample option table:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 1.25i 3.25i 4.75i -->
+<!-- .ta 1.25i 3.25i 4.75i -->
+static XrmOptionDescRec opTable[] = {
+{"-background", "*background", XrmoptionSepArg, (XPointer) NULL},
+{"-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
+{"-bg", "*background", XrmoptionSepArg, (XPointer) NULL},
+{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
+{"-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
+{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
+{"-display", ".display", XrmoptionSepArg, (XPointer) NULL},
+{"-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL},
+{"-fn", "*font", XrmoptionSepArg, (XPointer) NULL},
+{"-font", "*font", XrmoptionSepArg, (XPointer) NULL},
+{"-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL},
+{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL},
+{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"},
+{"-name", ".name", XrmoptionSepArg, (XPointer) NULL},
+{"-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
+{"-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
+{"-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"},
+{"-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL},
+{"-xrm", NULL, XrmoptionResArg, (XPointer) NULL},
+};
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+In this table, if the -background (or -bg) option is used to set
+background colors, the stored resource specifier matches all
+resources of attribute background.
+If the -borderwidth option is used,
+the stored resource specifier applies only to border width
+attributes of class TopLevelShell (that is, outer-most windows, including
+pop-up windows).
+If the -title option is used to set a window name,
+only the topmost application windows receive the resource.
+</para>
+<para>
+<!-- .LP -->
+When parsing the command line,
+any unique unambiguous abbreviation for an option name in the table is
+considered a match for the option.
+Note that uppercase and lowercase matter.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH16 b/libX11/specs/libX11/CH16 deleted file mode 100644 index 3a21a2290..000000000 --- a/libX11/specs/libX11/CH16 +++ /dev/null @@ -1,2364 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 16\fP\s-1 - -\s+1\fBApplication Utility Functions\fP\s-1 -.sp 2 -.nr H1 16 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 16: Application Utility Functions -.XE -Once you have initialized the X system, -you can use the Xlib utility functions to: -.IP \(bu 5 -Use keyboard utility functions -.IP \(bu 5 -Use Latin-1 keyboard event functions -.IP \(bu 5 -Allocate permanent storage -.IP \(bu 5 -Parse the window geometry -.IP \(bu 5 -Manipulate regions -.IP \(bu 5 -Use cut buffers -.IP \(bu 5 -Determine the appropriate visual type -.IP \(bu 5 -Manipulate images -.IP \(bu 5 -Manipulate bitmaps -.IP \(bu 5 -Use the context manager -.LP -As a group, -the functions discussed in this chapter provide the functionality that -is frequently needed and that spans toolkits. -Many of these functions do not generate actual protocol requests to the server. -.NH 2 -Using Keyboard Utility Functions -.XS -\*(SN Using Keyboard Utility Functions -.XE -.LP -This section discusses mapping between KeyCodes and KeySyms, -classifying KeySyms, and mapping between KeySyms and string names. -The first three functions in this section operate on a cached copy of the -server keyboard mapping. -The first four KeySyms for each KeyCode -are modified according to the rules given in section 12.7. -To obtain the untransformed KeySyms defined for a key, -use the functions described in section 12.7. -.LP -.sp -To obtain a KeySym for the KeyCode of an event, use -.PN XLookupKeysym . -.IN "XLookupKeysym" "" "@DEF@" -.sM -.FD 0 -KeySym XLookupKeysym(\^\fIkey_event\fP, \fIindex\fP\^) -.br - XKeyEvent *\fIkey_event\fP\^; -.br - int \fIindex\fP\^; -.FN -.IP \fIkey_event\fP 1i -Specifies the -.PN KeyPress -or -.PN KeyRelease -event. -.IP \fIindex\fP 1i -Specifies the index into the KeySyms list for the event's KeyCode. -.LP -.eM -The -.PN XLookupKeysym -function uses a given keyboard event and the index you specified to return -the KeySym from the list that corresponds to the KeyCode member in the -.PN XKeyPressedEvent -or -.PN XKeyReleasedEvent -structure. -If no KeySym is defined for the KeyCode of the event, -.PN XLookupKeysym -returns -.PN NoSymbol . -.LP -.sp -To obtain a KeySym for a specific KeyCode, use -.PN XKeycodeToKeysym . -.IN "XKeycodeToKeysym" "" "@DEF@" -.sM -.FD 0 -KeySym XKeycodeToKeysym\^(\^\fIdisplay\fP, \fIkeycode\fP, \fIindex\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - KeyCode \fIkeycode\fP\^; -.br - int \fIindex\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIkeycode\fP 1i -Specifies the KeyCode. -.IP \fIindex\fP 1i -Specifies the element of KeyCode vector. -.LP -.eM -The -.PN XKeycodeToKeysym -function uses internal Xlib tables -and returns the KeySym defined for the specified KeyCode and -the element of the KeyCode vector. -If no symbol is defined, -.PN XKeycodeToKeysym -returns -.PN NoSymbol . -.LP -.sp -To obtain a KeyCode for a key having a specific KeySym, use -.PN XKeysymToKeycode . -.IN "XKeysymToKeycode" "" "@DEF@" -.sM -.FD 0 -KeyCode XKeysymToKeycode\^(\^\fIdisplay\fP, \fIkeysym\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - KeySym \fIkeysym\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be searched for. -.LP -.eM -If the specified KeySym is not defined for any KeyCode, -.PN XKeysymToKeycode -returns zero. -.LP -.sp -The mapping between KeyCodes and KeySyms is cached internal to Xlib. -When this information is changed at the server, an Xlib function must -be called to refresh the cache. -To refresh the stored modifier and keymap information, use -.PN XRefreshKeyboardMapping . -.IN "XRefreshKeyboardMapping" "" "@DEF@" -.sM -.FD 0 -XRefreshKeyboardMapping(\^\fIevent_map\fP\^) -.br - XMappingEvent *\fIevent_map\fP\^; -.FN -.IP \fIevent_map\fP 1i -Specifies the mapping event that is to be used. -.LP -.eM -The -.PN XRefreshKeyboardMapping -function refreshes the stored modifier and keymap information. -You usually call this function when a -.PN MappingNotify -event with a request member of -.PN MappingKeyboard -or -.PN MappingModifier -occurs. -The result is to update Xlib's knowledge of the keyboard. -.LP -.sp -To obtain the uppercase and lowercase forms of a KeySym, use -.PN XConvertCase . -.IN "XConvertCase" "" "@DEF@" -.sM -.FD 0 -void XConvertCase(\^\fIkeysym\fP, \fIlower_return\fP, \fIupper_return\fP\^) -.br - KeySym \fIkeysym\fP\^; -.br - KeySym *\fIlower_return\fP\^; -.br - KeySym *\fIupper_return\fP\^; -.FN -.ds Fn converted -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.IP \fIlower_return\fP 1i -Returns the lowercase form of keysym, or keysym. -.IP \fIupper_return\fP 1i -Returns the uppercase form of keysym, or keysym. -.LP -.eM -The -.PN XConvertCase -function returns the uppercase and lowercase forms of the specified Keysym, -if the KeySym is subject to case conversion; -otherwise, the specified KeySym is returned to both lower_return and -upper_return. -Support for conversion of other than Latin and Cyrillic KeySyms is -implementation-dependent. -.LP -.sp -KeySyms have string names as well as numeric codes. -To convert the name of the KeySym to the KeySym code, use -.PN XStringToKeysym . -.IN "XStringToKeysym" "" "@DEF@" -.sM -.FD 0 -KeySym XStringToKeysym\^(\^\fIstring\fP\^) -.br - char *\fIstring\fP\^; -.FN -.IP \fIstring\fP 1i -Specifies the name of the KeySym that is to be converted. -.LP -.eM -Standard KeySym names are obtained from -.hN X11/keysymdef.h -by removing the XK_ prefix from each name. -KeySyms that are not part of the Xlib standard also may be obtained -with this function. -The set of KeySyms that are available in this manner -and the mechanisms by which Xlib obtains them is implementation-dependent. -.LP -If the KeySym name is not in the Host Portable Character Encoding, -the result is implementation-dependent. -If the specified string does not match a valid KeySym, -.PN XStringToKeysym -returns -.PN NoSymbol . -.LP -.sp -To convert a KeySym code to the name of the KeySym, use -.PN XKeysymToString . -.IN "XKeysymToString" "" "@DEF@" -.sM -.FD 0 -char *XKeysymToString\^(\^\fIkeysym\fP\^) -.br - KeySym \fIkeysym\fP\^; -.FN -.ds Fn converted -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -The returned string is in a static area and must not be modified. -The returned string is in the Host Portable Character Encoding. -If the specified KeySym is not defined, -.PN XKeysymToString -returns a NULL. -.NH 3 -KeySym Classification Macros -.XS -\*(SN KeySym Classification Macros -.XE -.LP -You may want to test if a KeySym is, for example, -on the keypad or on one of the function keys. -You can use KeySym macros to perform the following tests. -.LP -.sp -.sM -.FD 0 -IsCursorKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsCursorKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a cursor key. -.LP -.sp -.sM -.FD 0 -IsFunctionKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsFunctionKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a function key. -.LP -.sp -.sM -.FD 0 -IsKeypadKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsKeypadKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a standard keypad key. -.LP -.sp -.sM -.FD 0 -IsPrivateKeypadKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsPrivateKeypadKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a vendor-private keypad key. -.LP -.sp -.sM -.FD 0 -IsMiscFunctionKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsMiscFunctionKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a miscellaneous function key. -.LP -.sp -.sM -.FD 0 -IsModifierKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsModifierKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a modifier key. -.LP -.sp -.sM -.FD 0 -IsPFKey\^(\^\fIkeysym\fP\^) -.FN -.ds Fn tested -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.LP -.eM -.IN "IsPFKey" "" "@DEF@" -Returns -.PN True -if the specified KeySym is a PF key. -.NH 2 -Using Latin-1 Keyboard Event Functions -.XS -\*(SN Using Latin-1 Keyboard Event Functions -.XE -.LP -Chapter 13 describes internationalized text input facilities, -but sometimes it is expedient to write an application that -only deals with Latin-1 characters and ASCII controls, -so Xlib provides a simple function for that purpose. -.PN XLookupString -handles the standard modifier semantics described in section 12.7. -This function does not use any of the input method facilities -described in chapter 13 and does not depend on the current locale. -.LP -.sp -To map a key event to an ISO Latin-1 string, use -.PN XLookupString . -.IN "XLookupString" "" "@DEF@" -.sM -.FD 0 -int XLookupString(\^\fIevent_struct\fP, \fIbuffer_return\fP,\ - \fIbytes_buffer\fP, \fIkeysym_return\fP, \fIstatus_in_out\fP\^) -.br - XKeyEvent *\fIevent_struct\fP\^; -.br - char *\fIbuffer_return\fP\^; -.br - int \fIbytes_buffer\fP\^; -.br - KeySym *\fIkeysym_return\fP\^; -.br - XComposeStatus *\fIstatus_in_out\fP\^; -.FN -.IP \fIevent_struct\fP 1i -Specifies the key event structure to be used. -You can pass -.PN XKeyPressedEvent -or -.PN XKeyReleasedEvent . -.IP \fIbuffer_return\fP 1i -Returns the translated characters. -.IP \fIbytes_buffer\fP 1i -Specifies the length of the buffer. -No more than bytes_buffer of translation are returned. -.IP \fIkeysym_return\fP 1i -Returns the KeySym computed from the event if this argument is not NULL. -.IP \fIstatus_in_out\fP 1i -Specifies or returns the -.PN XComposeStatus -structure or NULL. -.LP -.eM -The -.PN XLookupString -function translates a key event to a KeySym and a string. -The KeySym is obtained by using the standard interpretation of the -.PN Shift , -.PN Lock , -group, and numlock modifiers as defined in the X Protocol specification. -If the KeySym has been rebound (see -.PN XRebindKeysym ), -the bound string will be stored in the buffer. -Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character -or (if the Control modifier is on) to an ASCII control character, -and that character is stored in the buffer. -.PN XLookupString -returns the number of characters that are stored in the buffer. -.LP -If present (non-NULL), -the -.PN XComposeStatus -structure records the state, -which is private to Xlib, -that needs preservation across calls to -.PN XLookupString -to implement compose processing. -The creation of -.PN XComposeStatus -structures is implementation-dependent; -a portable program must pass NULL for this argument. -.LP -.PN XLookupString -depends on the cached keyboard information mentioned in the -previous section, so it is necessary to use -.PN XRefreshKeyboardMapping -to keep this information up-to-date. -.LP -.sp -To rebind the meaning of a KeySym for -.PN XLookupString , -use -.PN XRebindKeysym . -.IN "XRebindKeysym" "" "@DEF@" -.sM -.FD 0 -XRebindKeysym(\^\fIdisplay\fP, \fIkeysym\fP, \fIlist\fP, \fImod_count\fP, \fIstring\fP, \fInum_bytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - KeySym \fIkeysym\fP\^; -.br - KeySym \fIlist\fP\^[\^]\^; -.br - int \fImod_count\fP\^; -.br - unsigned char *\fIstring\fP\^; -.br - int \fInum_bytes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Fn rebound -.IP \fIkeysym\fP 1i -Specifies the KeySym that is to be \*(Fn. -.IP \fIlist\fP 1i -Specifies the KeySyms to be used as modifiers. -.IP \fImod_count\fP 1i -Specifies the number of modifiers in the modifier list. -.IP \fIstring\fP 1i -Specifies the string that is copied and will be returned by -.PN XLookupString . -.IP \fInum_bytes\fP 1i -Specifies the number of bytes in the string argument. -.LP -.eM -The -.PN XRebindKeysym -function can be used to rebind the meaning of a KeySym for the client. -It does not redefine any key in the X server but merely -provides an easy way for long strings to be attached to keys. -.PN XLookupString -returns this string when the appropriate set of -modifier keys are pressed and when the KeySym would have been used for -the translation. -No text conversions are performed; -the client is responsible for supplying appropriately encoded strings. -Note that you can rebind a KeySym that may not exist. -.NH 2 -Allocating Permanent Storage -.XS -\*(SN Allocating Permanent Storage -.XE -.LP -To allocate some memory you will never give back, use -.PN Xpermalloc . -.IN "Xpermalloc" "" "@DEF@" -.sM -.FD 0 -char *Xpermalloc\^(\^\fIsize\fP\^) -.br - unsigned int \fIsize\fP\^; -.FN -.LP -.eM -The -.PN Xpermalloc -function allocates storage that can never be freed for the life of the -program. The memory is allocated with alignment for the C type double. -This function may provide some performance and space savings over -the standard operating system memory allocator. -.NH 2 -Parsing the Window Geometry -.XS -\*(SN Parsing the Window Geometry -.XE -.LP -To parse standard window geometry strings, use -.PN XParseGeometry . -.IN "Window" "determining location" -.IN "XParseGeometry" "" "@DEF@" -.LP -.sM -.FD 0 -int XParseGeometry\^(\^\fIparsestring\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) -.br - char *\fIparsestring\fP\^; -.br - int *\fIx_return\fP\^, *\fIy_return\fP\^; -.br - unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; -.FN -.IP \fIparsestring\fP 1i -Specifies the string you want to parse. -.IP \fIx_return\fP 1i -.br -.ns -.IP \fIy_return\fP 1i -Return the x and y offsets. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height determined. -.LP -.eM -By convention, -X applications use a standard string to indicate window size and placement. -.PN XParseGeometry -makes it easier to conform to this standard because it allows you -to parse the standard window geometry. -Specifically, this function lets you parse strings of the form: -.LP -.\" Start marker code here -.Ds -[=][<\fIwidth\fP>{xX}<\fIheight\fP>][{+-}<\fIxoffset\fP>{+-}<\fIyoffset\fP>] -.De -.\" End marker code here -.LP -The fields map into the arguments associated with this function. -(Items enclosed in <\^> are integers, items in [\^] are optional, and -items enclosed in {\^} indicate ``choose one of.'' -Note that the brackets should not appear in the actual string.) -If the string is not in the Host Portable Character Encoding, -the result is implementation-dependent. -.LP -The -.PN XParseGeometry -function returns a bitmask that indicates which of the four values (width, -height, xoffset, and yoffset) were actually found in the string -and whether the x and y values are negative. -By convention, \-0 is not equal to +0, because the user needs to -be able to say ``position the window relative to the right or bottom edge.'' -For each value found, the corresponding argument is updated. -For each value not found, the argument is left unchanged. -The bits are represented by -.PN XValue , -.PN YValue , -.PN WidthValue , -.PN HeightValue , -.PN XNegative , -or -.PN YNegative -and are defined in -.hN X11/Xutil.h . -They will be set whenever one of the values is defined -or one of the signs is set. -.LP -If the function returns either the -.PN XValue -or -.PN YValue -flag, -you should place the window at the requested position. -.sp -.LP -To construct a window's geometry information, use -.PN XWMGeometry . -.IN "XWMGeometry" "" "@DEF@" -.sM -.FD 0 -int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \ -\fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP, -.br - \fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen\fP\^; -.br - char *\fIuser_geom\fP\^; -.br - char *\fIdef_geom\fP\^; -.br - unsigned int \fIbwidth\fP\^; -.br - XSizeHints *\fIhints\fP\^; -.br - int *\fIx_return\fP, *\fIy_return\fP\^; -.br - int *\fIwidth_return\fP\^; -.br - int *\fIheight_return\fP\^; -.br - int *\fIgravity_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen\fP 1i -Specifies the screen. -.IP \fIuser_geom\fP 1i -Specifies the user-specified geometry or NULL. -.IP \fIdef_geom\fP 1i -Specifies the application's default geometry or NULL. -.IP \fIbwidth\fP 1i -Specifies the border width. -.IP \fIhints\fP 1i -Specifies the size hints for the window in its normal state. -.IP \fIx_return\fP 1i -.br -.ns -.IP \fIy_return\fP 1i -Return the x and y offsets. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height determined. -.IP \fIgravity_return\fP 1i -Returns the window gravity. -.LP -.eM -The -.PN XWMGeometry -function combines any geometry information (given in the format used by -.PN XParseGeometry ) -specified by the user and by the calling program with size hints -(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, -size, and gravity -.Pn ( NorthWestGravity , -.PN NorthEastGravity , -.PN SouthEastGravity , -or -.PN SouthWestGravity ) -that describe the window. -If the base size is not set in the -.PN XSizeHints -structure, -the minimum size is used if set. -Otherwise, a base size of zero is assumed. -If no minimum size is set in the hints structure, -the base size is used. -A mask (in the form returned by -.PN XParseGeometry ) -that describes which values came from the user specification -and whether or not the position coordinates are relative -to the right and bottom edges is returned. -Note that these coordinates will have already been accounted for -in the x_return and y_return values. -.LP -Note that invalid geometry specifications can cause a width or height -of zero to be returned. -The caller may pass the address of the hints win_gravity field -as gravity_return to update the hints directly. -.NH 2 -Manipulating Regions -.XS -\*(SN Manipulating Regions -.XE -.LP -Regions are arbitrary sets of pixel locations. -Xlib provides functions for manipulating regions. -The opaque type -.PN Region -is defined in -.hN X11/Xutil.h . -Xlib provides functions that you can use to manipulate regions. -This section discusses how to: -.IP \(bu 5 -Create, copy, or destroy regions -.IP \(bu 5 -Move or shrink regions -.IP \(bu 5 -Compute with regions -.IP \(bu 5 -Determine if regions are empty or equal -.IP \(bu 5 -Locate a point or rectangle in a region -.NH 3 -Creating, Copying, or Destroying Regions -.XS -\*(SN Creating, Copying, or Destroying Regions -.XE -.LP -To create a new empty region, use -.PN XCreateRegion . -.IN "XCreateRegion" "" "@DEF@" -.sM -.FD 0 -Region XCreateRegion\^() -.FN -.LP -.eM -.sp -To generate a region from a polygon, use -.PN XPolygonRegion . -.IN "XPolygonRegion" "" "@DEF@" -.sM -.FD 0 -Region XPolygonRegion\^(\^\fIpoints\fP\^, \fIn\fP\^, \fIfill_rule\fP\^) -.br - XPoint \fIpoints[]\fP\^; -.br - int \fIn\fP\^; -.br - int \fIfill_rule\fP\^; -.FN -.IP \fIpoints\fP 1i -Specifies an array of points. -.IP \fIn\fP 1i -Specifies the number of points in the polygon. -.IP \fIfill_rule\fP 1i -Specifies the fill-rule you want to set for the specified GC. -You can pass -.PN EvenOddRule -or -.PN WindingRule . -.LP -.eM -The -.PN XPolygonRegion -function returns a region for the polygon defined by the points array. -For an explanation of fill_rule, -see -.PN XCreateGC . -.LP -.sp -To set the clip-mask of a GC to a region, use -.PN XSetRegion . -.IN "XSetRegion" "" "@DEF@" -.sM -.FD 0 -XSetRegion\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIr\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - GC \fIgc\fP\^; -.br - Region \fIr\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIgc\fP 1i -Specifies the GC. -.IP \fIr\fP 1i -Specifies the region. -.LP -.eM -The -.PN XSetRegion -function sets the clip-mask in the GC to the specified region. -The region is specified relative to the drawable's origin. -The resulting GC clip origin is implementation-dependent. -Once it is set in the GC, -the region can be destroyed. -.LP -.sp -To deallocate the storage associated with a specified region, use -.PN XDestroyRegion . -.IN "XDestroyRegion" "" "@DEF@" -.sM -.FD 0 -XDestroyRegion\^(\^\fIr\fP\^) -.br - Region \fIr\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.LP -.eM -.NH 3 -Moving or Shrinking Regions -.XS -\*(SN Moving or Shrinking Regions -.XE -.LP -To move a region by a specified amount, use -.PN XOffsetRegion . -.IN "XOffsetRegion" "" "@DEF@" -.sM -.FD 0 -XOffsetRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^) -.br - Region \fIr\fP\^; -.br - int \fIdx\fP\^, \fIdy\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.ds Dy move -.IP \fIdx\fP 1i -.br -.ns -.IP \fIdy\fP 1i -Specify the x and y coordinates, -which define the amount you want to \*(Dy the specified region. -.LP -.eM -.sp -To reduce a region by a specified amount, use -.PN XShrinkRegion . -.IN "XShrinkRegion" "" "@DEF@" -.sM -.FD 0 -XShrinkRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^) -.br - Region \fIr\fP\^; -.br - int \fIdx\fP\^, \fIdy\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.ds Dy shrink -.IP \fIdx\fP 1i -.br -.ns -.IP \fIdy\fP 1i -Specify the x and y coordinates, -which define the amount you want to \*(Dy the specified region. -.LP -.eM -Positive values shrink the size of the region, -and negative values expand the region. -.NH 3 -Computing with Regions -.XS -\*(SN Computing with Regions -.XE -.LP -.sp -To generate the smallest rectangle enclosing a region, use -.PN XClipBox . -.IN "XClipBox" "" "@DEF@" -.sM -.FD 0 -XClipBox\^(\^\fIr\fP\^, \fIrect_return\fP\^) -.br - Region \fIr\fP\^; -.br - XRectangle *\fIrect_return\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.IP \fIrect_return\fP 1i -Returns the smallest enclosing rectangle. -.LP -.eM -The -.PN XClipBox -function returns the smallest rectangle enclosing the specified region. -.sp -.LP -To compute the intersection of two regions, use -.PN XIntersectRegion . -.IN "XIntersectRegion" "" "@DEF@" -.sM -.FD 0 -XIntersectRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) -.br - Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; -.FN -.IP \fIsra\fP 1i -.br -.ns -.IP \fIsrb\fP 1i -Specify the two regions with which you want to perform the computation. -.IP \fIdr_return\fP 1i -Returns the result of the computation. -.LP -.eM -.sp -To compute the union of two regions, use -.PN XUnionRegion . -.IN "XUnionRegion" "" "@DEF@" -.sM -.FD 0 -XUnionRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) -.br - Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; -.FN -.IP \fIsra\fP 1i -.br -.ns -.IP \fIsrb\fP 1i -Specify the two regions with which you want to perform the computation. -.IP \fIdr_return\fP 1i -Returns the result of the computation. -.LP -.eM -.sp -To create a union of a source region and a rectangle, use -.PN XUnionRectWithRegion . -.IN "XUnionRectWithRegion" "" "@DEF@" -.sM -.FD 0 -XUnionRectWithRegion\^(\^\fIrectangle\fP, \fIsrc_region\fP, \ -\fIdest_region_return\fP\^) -.br - XRectangle *\fIrectangle\fP\^; -.br - Region \fIsrc_region\fP\^; -.br - Region \fIdest_region_return\fP\^; -.FN -.IP \fIrectangle\fP 1i -Specifies the rectangle. -.IP \fIsrc_region\fP 1i -Specifies the source region to be used. -.IP \fIdest_region_return\fP 1i -Returns the destination region. -.LP -.eM -The -.PN XUnionRectWithRegion -function updates the destination region from a union of the specified rectangle -and the specified source region. -.LP -.sp -To subtract two regions, use -.PN XSubtractRegion . -.IN "XSubtractRegion" "" "@DEF@" -.sM -.FD 0 -XSubtractRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) -.br - Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; -.FN -.IP \fIsra\fP 1i -.br -.ns -.IP \fIsrb\fP 1i -Specify the two regions with which you want to perform the computation. -.IP \fIdr_return\fP 1i -Returns the result of the computation. -.LP -.eM -The -.PN XSubtractRegion -function subtracts srb from sra and stores the results in dr_return. -.LP -.sp -To calculate the difference between the union and intersection -of two regions, use -.PN XXorRegion . -.IN "XXorRegion" "" "@DEF@" -.sM -.FD 0 -XXorRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) -.br - Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; -.FN -.IP \fIsra\fP 1i -.br -.ns -.IP \fIsrb\fP 1i -Specify the two regions with which you want to perform the computation. -.IP \fIdr_return\fP 1i -Returns the result of the computation. -.LP -.eM -.NH 3 -Determining if Regions Are Empty or Equal -.XS -\*(SN Determining if Regions Are Empty or Equal -.XE -.LP -To determine if the specified region is empty, use -.PN XEmptyRegion . -.IN "XEmptyRegion" "" "@DEF@" -.sM -.FD 0 -Bool XEmptyRegion\^(\^\fIr\fP\^) -.br - Region \fIr\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.LP -.eM -The -.PN XEmptyRegion -function returns -.PN True -if the region is empty. -.LP -.sp -To determine if two regions have the same offset, size, and shape, use -.PN XEqualRegion . -.IN "XEqualRegion" "" "@DEF@" -.sM -.FD 0 -Bool XEqualRegion\^(\^\fIr1\fP\^, \fIr2\fP\^) -.br - Region \fIr1\fP\^, \fIr2\fP\^; -.FN -.IP \fIr1\fP 1i -.br -.ns -.IP \fIr2\fP 1i -Specify the two regions. -.LP -.eM -The -.PN XEqualRegion -function returns -.PN True -if the two regions have the same offset, size, and shape. -.NH 3 -Locating a Point or a Rectangle in a Region -.XS -\*(SN Locating a Point or a Rectangle in a Region -.XE -.LP -To determine if a specified point resides in a specified region, use -.PN XPointInRegion . -.IN "XPointInRegion" "" "@DEF@" -.sM -.FD 0 -Bool XPointInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Region \fIr\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.ds Xy , which define the point -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.LP -.eM -The -.PN XPointInRegion -function returns -.PN True -if the point (x, y) is contained in the region r. -.LP -.sp -To determine if a specified rectangle is inside a region, use -.PN XRectInRegion . -.IN "XRectInRegion" "" "@DEF@" -.sM -.FD 0 -int XRectInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) -.br - Region \fIr\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.FN -.IP \fIr\fP 1i -Specifies the region. -.ds Xy , which define the coordinates of the upper-left corner of the rectangle -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.ds Wh , which define the rectangle -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.LP -.eM -The -.PN XRectInRegion -function returns -.PN RectangleIn -if the rectangle is entirely in the specified region, -.PN RectangleOut -if the rectangle is entirely out of the specified region, -and -.PN RectanglePart -if the rectangle is partially in the specified region. -.NH 2 -Using Cut Buffers -.XS -\*(SN Using Cut Buffers -.XE -.LP -.IN "Cut Buffers" -Xlib provides functions to manipulate cut buffers, -a very simple form of cut-and-paste inter-client communication. -Selections are a much more powerful and useful mechanism for -interchanging data between clients (see section 4.5) -and generally should be used instead of cut buffers. -.LP -Cut buffers are implemented as properties on the first root window -of the display. -The buffers can only contain text, in the STRING encoding. -The text encoding is not changed by Xlib when fetching or storing. -Eight buffers are provided -and can be accessed as a ring or as explicit buffers (numbered 0 through 7). -.LP -.sp -To store data in cut buffer 0, use -.PN XStoreBytes . -.IN "XStoreBytes" "" "@DEF@" -.sM -.FD 0 -XStoreBytes\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIbytes\fP\^; -.br - int \^\fInbytes\fP\^; -.br -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIbytes\fP 1i -Specifies the bytes, which are not necessarily ASCII or null-terminated. -.IP \fInbytes\fP 1i -Specifies the number of bytes to be stored. -.LP -.eM -The data can have embedded null characters -and need not be null-terminated. -The cut buffer's contents can be retrieved later by -any client calling -.PN XFetchBytes . -.LP -.PN XStoreBytes -can generate a -.PN BadAlloc -error. -.LP -.sp -To store data in a specified cut buffer, use -.PN XStoreBuffer . -.IN "XStoreBuffer" "" "@DEF@" -.sM -.FD 0 -XStoreBuffer\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^, \fIbuffer\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIbytes\fP\^; -.br - int \^\fInbytes\fP\^; -.br - int \fIbuffer\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIbytes\fP 1i -Specifies the bytes, which are not necessarily ASCII or null-terminated. -.IP \fInbytes\fP 1i -Specifies the number of bytes to be stored. -.ds Fn in which you want to store the bytes -.IP \fIbuffer\fP 1i -Specifies the buffer \*(Fn. -.LP -.eM -If an invalid buffer is specified, the call has no effect. -The data can have embedded null characters -and need not be null-terminated. -.LP -.PN XStoreBuffer -can generate a -.PN BadAlloc -error. -.LP -.sp -To return data from cut buffer 0, use -.PN XFetchBytes . -.IN "XFetchBytes" "" "@DEF@" -.sM -.FD 0 -char *XFetchBytes\^(\^\fIdisplay\fP, \fInbytes_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInbytes_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInbytes_return\fP 1i -Returns the number of bytes in the buffer. -.LP -.eM -The -.PN XFetchBytes -function -returns the number of bytes in the nbytes_return argument, -if the buffer contains data. -Otherwise, the function -returns NULL and sets nbytes to 0. -The appropriate amount of storage is allocated and the pointer returned. -The client must free this storage when finished with it by calling -.PN XFree . -.LP -.sp -To return data from a specified cut buffer, use -.PN XFetchBuffer . -.IN "XFetchBuffer" "" "@DEF@" -.sM -.FD 0 -char *XFetchBuffer\^(\^\fIdisplay\fP, \fInbytes_return\fP\^, \fIbuffer\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInbytes_return\fP\^; -.br - int \fIbuffer\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInbytes_return\fP 1i -Returns the number of bytes in the buffer. -.ds Fn from which you want the stored data returned -.IP \fIbuffer\fP 1i -Specifies the buffer \*(Fn. -.LP -.eM -The -.PN XFetchBuffer -function returns zero to the nbytes_return argument -if there is no data in the buffer or if an invalid -buffer is specified. -.LP -.sp -To rotate the cut buffers, use -.PN XRotateBuffers . -.IN "XRotateBuffers" "" "@DEF@" -.sM -.FD 0 -XRotateBuffers\^(\^\fIdisplay\fP, \fIrotate\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIrotate\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIrotate\fP 1i -Specifies how much to rotate the cut buffers. -.LP -.eM -The -.PN XRotateBuffers -function rotates the cut -buffers, such that buffer 0 becomes buffer n, -buffer 1 becomes n + 1 mod 8, and so on. -This cut buffer numbering is global to the display. -Note that -.PN XRotateBuffers -generates -.PN BadMatch -errors if any of the eight buffers have not been created. -.NH 2 -Determining the Appropriate Visual Type -.XS -\*(SN Determining the Appropriate Visual Type -.XE -.LP -A single display can support multiple screens. -Each screen can have several different visual types supported -at different depths. -You can use the functions described in this section to determine -which visual to use for your application. -.LP -The functions in this section use the visual information masks and the -.PN XVisualInfo -structure, -which is defined in -.hN X11/Xutil.h -and contains: -.sM -.LP -/* Visual information mask bits */ -.TS -lw(.5i) lw(2.5i) lw(.8i). -T{ -#define -T} T{ -.PN VisualNoMask -T} T{ -0x0 -T} -T{ -#define -T} T{ -.PN VisualIDMask -T} T{ -0x1 -T} -T{ -#define -T} T{ -.PN VisualScreenMask -T} T{ -0x2 -T} -T{ -#define -T} T{ -.PN VisualDepthMask -T} T{ -0x4 -T} -T{ -#define -T} T{ -.PN VisualClassMask -T} T{ -0x8 -T} -T{ -#define -T} T{ -.PN VisualRedMaskMask -T} T{ -0x10 -T} -T{ -#define -T} T{ -.PN VisualGreenMaskMask -T} T{ -0x20 -T} -T{ -#define -T} T{ -.PN VisualBlueMaskMask -T} T{ -0x40 -T} -T{ -#define -T} T{ -.PN VisualColormapSizeMask -T} T{ -0x80 -T} -T{ -#define -T} T{ -.PN VisualBitsPerRGBMask -T} T{ -0x100 -T} -T{ -#define -T} T{ -.PN VisualAllMask -T} T{ -0x1FF -T} -.TE -.IN "XVisualInfo" "" "@DEF@" -.Ds 0 -.TA .5i 3i -.ta .5i 3i -/* Values */ - -typedef struct { - Visual *visual; - VisualID visualid; - int screen; - unsigned int depth; - int class; - unsigned long red_mask; - unsigned long green_mask; - unsigned long blue_mask; - int colormap_size; - int bits_per_rgb; -} XVisualInfo; -.De -.LP -.eM -To obtain a list of visual information structures that match a specified -template, use -.PN XGetVisualInfo . -.IN "XGetVisualInfo" "" "@DEF@" -.sM -.FD 0 -XVisualInfo *XGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - long \fIvinfo_mask\fP\^; -.br - XVisualInfo *\fIvinfo_template\fP\^; -.br - int *\fInitems_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIvinfo_mask\fP 1i -Specifies the visual mask value. -.IP \fIvinfo_template\fP 1i -Specifies the visual attributes that are to be used in matching the visual -structures. -.IP \fInitems_return\fP 1i -Returns the number of matching visual structures. -.LP -.eM -The -.PN XGetVisualInfo -function returns a list of visual structures that have attributes -equal to the attributes specified by vinfo_template. -If no visual structures match the template using the specified vinfo_mask, -.PN XGetVisualInfo -returns a NULL. -To free the data returned by this function, use -.PN XFree . -.LP -.sp -To obtain the visual information that matches the specified depth and -class of the screen, use -.PN XMatchVisualInfo . -.IN "XMatchVisualInfo" "" "@DEF@" -.sM -.FD 0 -Status XMatchVisualInfo\^(\^\fIdisplay\fP, \fIscreen\fP, \fIdepth\fP, \fIclass\fP, \fIvinfo_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen\fP\^; -.br - int \fIdepth\fP\^; -.br - int \fIclass\fP\^; -.br - XVisualInfo *\fIvinfo_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen\fP 1i -Specifies the screen. -.IP \fIdepth\fP 1i -Specifies the depth of the screen. -.IP \fIclass\fP 1i -Specifies the class of the screen. -.IP \fIvinfo_return\fP 1i -Returns the matched visual information. -.LP -.eM -The -.PN XMatchVisualInfo -function returns the visual information for a visual that matches the specified -depth and class for a screen. -Because multiple visuals that match the specified depth and class can exist, -the exact visual chosen is undefined. -If a visual is found, -.PN XMatchVisualInfo -returns nonzero and the information on the visual to vinfo_return. -Otherwise, when a visual is not found, -.PN XMatchVisualInfo -returns zero. -.NH 2 -Manipulating Images -.XS -\*(SN Manipulating Images -.XE -.LP -Xlib provides several functions that perform basic operations on images. -All operations on images are defined using an -.PN XImage -structure, -as defined in -.hN X11/Xlib.h . -Because the number of different types of image formats can be very large, -this hides details of image storage properly from applications. -.LP -This section describes the functions for generic operations on images. -Manufacturers can provide very fast implementations of these for the -formats frequently encountered on their hardware. -These functions are neither sufficient nor desirable to use for general image -processing. -Rather, they are here to provide minimal functions on screen format -images. -The basic operations for getting and putting images are -.PN XGetImage -and -.PN XPutImage . -.LP -Note that no functions have been defined, as yet, to read and write images -to and from disk files. -.LP -The -.PN XImage -structure describes an image as it exists in the client's memory. -The user can request that some of the members such as height, width, -and xoffset be changed when the image is sent to the server. -Note that bytes_per_line in concert with offset can be used to -extract a subset of the image. -Other members (for example, byte order, bitmap_unit, and so forth) -are characteristics of both the image and the server. -If these members -differ between the image and the server, -.PN XPutImage -makes the appropriate conversions. -The first byte of the first line of -plane n must be located at the address (data + (n * height * bytes_per_line)). -For a description of the -.PN XImage -structure, -see section 8.7. -.LP -.sp -To allocate an -.PN XImage -structure and initialize it with image format values from a display, use -.PN XCreateImage . -.IN "XCreateImage" "" "@DEF@" -.sM -.FD 0 -XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP, -.br - \fIbytes_per_line\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Visual *\fIvisual\fP\^; -.br - unsigned int \fIdepth\fP\^; -.br - int \fIformat\fP\^; -.br - int \fIoffset\fP\^; -.br - char *\fIdata\fP\^; -.br - unsigned int \fIwidth\fP\^; -.br - unsigned int \fIheight\fP\^; -.br - int \fIbitmap_pad\fP\^; -.br - int \fIbytes_per_line\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIvisual\fP 1i -Specifies the -.PN Visual -structure. -.IP \fIdepth\fP 1i -Specifies the depth of the image. -.IP \fIformat\fP 1i -Specifies the format for the image. -You can pass -.PN XYBitmap , -.PN XYPixmap , -or -.PN ZPixmap . -.IP \fIoffset\fP 1i -Specifies the number of pixels to ignore at the beginning of the scanline. -.IP \fIdata\fP 1i -Specifies the image data. -.IP \fIwidth\fP 1i -Specifies the width of the image, in pixels. -.IP \fIheight\fP 1i -Specifies the height of the image, in pixels. -.IP \fIbitmap_pad\fP 1i -Specifies the quantum of a scanline (8, 16, or 32). -In other words, the start of one scanline is separated in client memory from -the start of the next scanline by an integer multiple of this many bits. -.IP \fIbytes_per_line\fP 1i -Specifies the number of bytes in the client image between -the start of one scanline and the start of the next. -.LP -.eM -The -.PN XCreateImage -function allocates the memory needed for an -.PN XImage -structure for the -specified display but does not allocate space for the image itself. -Rather, it initializes the structure byte-order, bit-order, and bitmap-unit -values from the display and returns a pointer to the -.PN XImage -structure. -The red, green, and blue mask values are defined for Z format images only -and are derived from the -.PN Visual -structure passed in. -Other values also are passed in. -The offset permits the rapid displaying of the image without requiring each -scanline to be shifted into position. -If you pass a zero value in bytes_per_line, -Xlib assumes that the scanlines are contiguous -in memory and calculates the value of bytes_per_line itself. -.LP -Note that when the image is created using -.PN XCreateImage , -.PN XGetImage , -or -.PN XSubImage , -the destroy procedure that the -.PN XDestroyImage -function calls frees both the image structure -and the data pointed to by the image structure. -.LP -The basic functions used to get a pixel, set a pixel, create a subimage, -and add a constant value to an image are defined in the image object. -The functions in this section are really macro invocations of the functions -in the image object and are defined in -.hN X11/Xutil.h . -.LP -.sp -To obtain a pixel value in an image, use -.PN XGetPixel . -.IN "XGetPixel" "" "@DEF@" -.sM -.FD 0 -unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^) -.br - XImage *\fIximage\fP\^; -.br - int \fIx\fP\^; -.br - int \fIy\fP\^; -.FN -.IP \fIximage\fP 1i -Specifies the image. -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates. -.LP -.eM -The -.PN XGetPixel -function returns the specified pixel from the named image. -The pixel value is returned in normalized format (that is, -the least significant byte of the long is the least significant byte -of the pixel). -The image must contain the x and y coordinates. -.LP -.sp -To set a pixel value in an image, use -.PN XPutPixel . -.IN "XPutPixel" "" "@DEF@" -.sM -.FD 0 -XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^) -.br - XImage *\fIximage\fP\^; -.br - int \fIx\fP\^; -.br - int \fIy\fP\^; -.br - unsigned long \fIpixel\fP\^; -.FN -.IP \fIximage\fP 1i -Specifies the image. -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates. -.IP \fIpixel\fP 1i -Specifies the new pixel value. -.LP -.eM -The -.PN XPutPixel -function overwrites the pixel in the named image with the specified pixel value. -The input pixel value must be in normalized format -(that is, the least significant byte of the long is the least significant -byte of the pixel). -The image must contain the x and y coordinates. -.LP -.sp -To create a subimage, use -.PN XSubImage . -.IN "XSubImage" "" "@DEF@" -.sM -.FD 0 -XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^) -.br - XImage *\fIximage\fP\^; -.br - int \fIx\fP\^; -.br - int \fIy\fP\^; -.br - unsigned int \fIsubimage_width\fP\^; -.br - unsigned int \fIsubimage_height\fP\^; -.FN -.IP \fIximage\fP 1i -Specifies the image. -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates. -.IP \fIsubimage_width\fP 1i -Specifies the width of the new subimage, in pixels. -.IP \fIsubimage_height\fP 1i -Specifies the height of the new subimage, in pixels. -.LP -.eM -The -.PN XSubImage -function creates a new image that is a subsection of an existing one. -It allocates the memory necessary for the new -.PN XImage -structure -and returns a pointer to the new image. -The data is copied from the source image, -and the image must contain the rectangle defined by x, y, subimage_width, -and subimage_height. -.LP -.sp -To increment each pixel in an image by a constant value, use -.PN XAddPixel . -.IN "XAddPixel" "" "@DEF@" -.sM -.FD 0 -XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^) -.br - XImage *\fIximage\fP\^; -.br - long \fIvalue\fP\^; -.FN -.IP \fIximage\fP 1i -Specifies the image. -.IP \fIvalue\fP 1i -Specifies the constant value that is to be added. -.LP -.eM -The -.PN XAddPixel -function adds a constant value to every pixel in an image. -It is useful when you have a base pixel value from allocating -color resources and need to manipulate the image to that form. -.LP -.sp -To deallocate the memory allocated in a previous call to -.PN XCreateImage , -use -.PN XDestroyImage . -.IN "XDestroyImage" "" "@DEF@" -.sM -.FD 0 -XDestroyImage\^(\^\fIximage\fP\^) -.br - XImage *\^\fIximage\fP\^; -.FN -.IP \fIximage\fP 1i -Specifies the image. -.LP -.eM -The -.PN XDestroyImage -function deallocates the memory associated with the -.PN XImage -structure. -.LP -Note that when the image is created using -.PN XCreateImage , -.PN XGetImage , -or -.PN XSubImage , -the destroy procedure that this macro calls -frees both the image structure and the data pointed to by the image structure. -.NH 2 -Manipulating Bitmaps -.XS -\*(SN Manipulating Bitmaps -.XE -.LP -Xlib provides functions that you can use to read a bitmap from a file, -save a bitmap to a file, or create a bitmap. -This section describes those functions that transfer bitmaps to and -from the client's file system, thus allowing their reuse in a later -connection (for example, from an entirely different client or to a -different display or server). -.LP -The X version 11 bitmap file format is: -.LP -.sM -.Ds 0 -#define \fIname\fP_width \fIwidth\fP -#define \fIname\fP_height \fIheight\fP -#define \fIname\fP_x_hot \fIx\fP -#define \fIname\fP_y_hot \fIy\fP -static unsigned char \fIname\fP_bits[] = { 0x\fINN\fP,... } -.De -.LP -.eM -The lines for the variables ending with _x_hot and _y_hot suffixes are optional -because they are present only if a hotspot has been defined for this bitmap. -The lines for the other variables are required. -The word ``unsigned'' is optional; -that is, the type of the _bits array can be ``char'' or ``unsigned char''. -The _bits array must be large enough to contain the size bitmap. -The bitmap unit is 8. -.LP -.sp -To read a bitmap from a file and store it in a pixmap, use -.PN XReadBitmapFile . -.IN "XReadBitmapFile" "" "@DEF@" -.sM -.FD 0 -int XReadBitmapFile(\^\fIdisplay\fP, \fId\fP, \fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIbitmap_return\fP, \fIx_hot_return\fP, -.br - \fIy_hot_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - char *\fIfilename\fP\^; -.br - unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; -.br - Pixmap *\fIbitmap_return\fP\^; -.br - int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Dr \ that indicates the screen -.IP \fId\fP 1i -Specifies the drawable\*(Dr. -.IP \fIfilename\fP 1i -Specifies the file name to use. -The format of the file name is operating-system dependent. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height values of the read in bitmap file. -.IP \fIbitmap_return\fP 1i -Returns the bitmap that is created. -.IP \fIx_hot_return\fP 1i -.br -.ns -.IP \fIy_hot_return\fP 1i -Return the hotspot coordinates. -.LP -.eM -The -.PN XReadBitmapFile -function reads in a file containing a bitmap. -The file is parsed in the encoding of the current locale. -The ability to read other than the standard format -is implementation-dependent. -If the file cannot be opened, -.PN XReadBitmapFile -returns -.PN BitmapOpenFailed . -If the file can be opened but does not contain valid bitmap data, -it returns -.PN BitmapFileInvalid . -If insufficient working storage is allocated, -it returns -.PN BitmapNoMemory . -If the file is readable and valid, -it returns -.PN BitmapSuccess . -.LP -.PN XReadBitmapFile -returns the bitmap's height and width, as read -from the file, to width_return and height_return. -It then creates a pixmap of the appropriate size, -reads the bitmap data from the file into the pixmap, -and assigns the pixmap to the caller's variable bitmap. -The caller must free the bitmap using -.PN XFreePixmap -when finished. -If \fIname\fP_x_hot and \fIname\fP_y_hot exist, -.PN XReadBitmapFile -returns them to x_hot_return and y_hot_return; -otherwise, it returns \-1,\-1. -.LP -.PN XReadBitmapFile -can generate -.PN BadAlloc , -.PN BadDrawable , -and -.PN BadGC -errors. -.LP -.sp -To read a bitmap from a file and return it as data, use -.PN XReadBitmapFileData . -.IN "XReadBitmapFileData" "" "@DEF@" -.sM -.FD 0 -int XReadBitmapFileData(\^\fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIdata_return\fP, \fIx_hot_return\fP, \fIy_hot_return\fP\^) -.br - char *\fIfilename\fP\^; -.br - unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; -.br - unsigned char *\fIdata_return\fP\^; -.br - int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^; -.FN -.IP \fIfilename\fP 1i -Specifies the file name to use. -The format of the file name is operating-system dependent. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the width and height values of the read in bitmap file. -.IP \fIdata_return\fP 1i -Returns the bitmap data. -.IP \fIx_hot_return\fP 1i -.br -.ns -.IP \fIy_hot_return\fP 1i -Return the hotspot coordinates. -.LP -.eM -The -.PN XReadBitmapFileData -function reads in a file containing a bitmap, in the same manner as -.PN XReadBitmapFile , -but returns the data directly rather than creating a pixmap in the server. -The bitmap data is returned in data_return; the client must free this -storage when finished with it by calling -.PN XFree . -The status and other return values are the same as for -.PN XReadBitmapFile . -.LP -.sp -To write out a bitmap from a pixmap to a file, use -.PN XWriteBitmapFile . -.IN "XWriteBitmapFile" "" "@DEF@" -.sM -.FD 0 -int XWriteBitmapFile(\^\fIdisplay\fP, \fIfilename\fP, \fIbitmap\fP, \fIwidth\fP, \fIheight\fP, \fIx_hot\fP, \fIy_hot\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIfilename\fP\^; -.br - Pixmap \fIbitmap\fP\^; -.br - unsigned int \fIwidth\fP, \fIheight\fP\^; -.br - int \fIx_hot\fP, \fIy_hot\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfilename\fP 1i -Specifies the file name to use. -The format of the file name is operating-system dependent. -.IP \fIbitmap\fP 1i -Specifies the bitmap. -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height. -.IP \fIx_hot\fP 1i -.br -.ns -.IP \fIy_hot\fP 1i -Specify where to place the hotspot coordinates (or \-1,\-1 if none are present) -in the file. -.LP -.eM -The -.PN XWriteBitmapFile -function writes a bitmap out to a file in the X Version 11 format. -The name used in the output file is derived from the file name -by deleting the directory prefix. -The file is written in the encoding of the current locale. -If the file cannot be opened for writing, -it returns -.PN BitmapOpenFailed . -If insufficient memory is allocated, -.PN XWriteBitmapFile -returns -.PN BitmapNoMemory ; -otherwise, on no error, -it returns -.PN BitmapSuccess . -If x_hot and y_hot are not \-1, \-1, -.PN XWriteBitmapFile -writes them out as the hotspot coordinates for the bitmap. -.LP -.PN XWriteBitmapFile -can generate -.PN BadDrawable -and -.PN BadMatch -errors. -.LP -.sp -To create a pixmap and then store bitmap-format data into it, use -.PN XCreatePixmapFromBitmapData . -.IN "XCreatePixmapFromBitmapData" "" "@DEF@" -.sM -.FD 0 -Pixmap XCreatePixmapFromBitmapData\^(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP, \fIfg\fP, \fIbg\fP, \fIdepth\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - char *\fIdata\fP\^; -.br - unsigned int \fIwidth\fP, \fIheight\fP\^; -.br - unsigned long \fIfg\fP, \fIbg\fP\^; -.br - unsigned int \fIdepth\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Dr \ that indicates the screen -.IP \fId\fP 1i -Specifies the drawable\*(Dr. -.IP \fIdata\fP 1i -Specifies the data in bitmap format. -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height. -.IP \fIfg\fP 1i -.br -.ns -.IP \fIbg\fP 1i -Specify the foreground and background pixel values to use. -.IP \fIdepth\fP 1i -Specifies the depth of the pixmap. -.LP -.eM -The -.PN XCreatePixmapFromBitmapData -function creates a pixmap of the given depth and then does a bitmap-format -.PN XPutImage -of the data into it. -The depth must be supported by the screen of the specified drawable, -or a -.PN BadMatch -error results. -.LP -.PN XCreatePixmapFromBitmapData -can generate -.PN BadAlloc , -.PN BadDrawable , -.PN BadGC , -and -.PN BadValue -errors. -.LP -.sp -To include a bitmap written out by -.PN XWriteBitmapFile -.IN "XWriteBitmapFile" -in a program directly, as opposed to reading it in every time at run time, use -.PN XCreateBitmapFromData . -.IN "XCreateBitmapFromData" "" "@DEF@" -.sM -.FD 0 -Pixmap XCreateBitmapFromData(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - char *\fIdata\fP\^; -.br - unsigned int \fIwidth\fP, \fIheight\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Dr \ that indicates the screen -.IP \fId\fP 1i -Specifies the drawable\*(Dr. -.IP \fIdata\fP 1i -Specifies the location of the bitmap data. -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height. -.LP -.eM -The -.PN XCreateBitmapFromData -function allows you to include in your C program (using -.PN #include ) -a bitmap file that was written out by -.PN XWriteBitmapFile -(X version 11 format only) without reading in the bitmap file. -The following example creates a gray bitmap: -.LP -.Ds 0 -#include "gray.bitmap" -.sp 6p -Pixmap bitmap; -bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height); -.De -.LP -If insufficient working storage was allocated, -.PN XCreateBitmapFromData -returns -.PN None . -It is your responsibility to free the -bitmap using -.PN XFreePixmap -when finished. -.LP -.PN XCreateBitmapFromData -can generate -.PN BadAlloc -and -.PN BadGC -errors. -.NH 2 -Using the Context Manager -.XS -\*(SN Using the Context Manager -.XE -.LP -The context manager provides a way of associating data with an X resource ID -(mostly typically a window) in your program. -Note that this is local to your program; -the data is not stored in the server on a property list. -Any amount of data in any number of pieces can be associated with a -resource ID, -and each piece of data has a type associated with it. -The context manager requires knowledge of the resource ID -and type to store or retrieve data. -.LP -Essentially, the context manager can be viewed as a two-dimensional, -sparse array: one dimension is subscripted by the X resource ID -and the other by a context type field. -Each entry in the array contains a pointer to the data. -Xlib provides context management functions with which you can -save data values, get data values, delete entries, and create a unique -context type. -The symbols used are in -.hN X11/Xutil.h . -.LP -.sp -To save a data value that corresponds to a resource ID and context type, use -.PN XSaveContext . -.IN "XSaveContext" "" "@DEF@" -.sM -.FD 0 -int XSaveContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIrid\fP\^; -.br - XContext \fIcontext\fP\^; -.br - XPointer \fIdata\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIrid\fP 1i -Specifies the resource ID with which the data is associated. -.IP \fIcontext\fP 1i -Specifies the context type to which the data belongs. -.IP \fIdata\fP 1i -Specifies the data to be associated with the window and type. -.LP -.eM -If an entry with the specified resource ID and type already exists, -.PN XSaveContext -overrides it with the specified context. -The -.PN XSaveContext -function returns a nonzero error code if an error has occurred -and zero otherwise. -Possible errors are -.PN XCNOMEM -(out of memory). -.LP -.sp -To get the data associated with a resource ID and type, use -.PN XFindContext . -.IN "XFindContext" "" "@DEF@" -.sM -.FD 0 -int XFindContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIrid\fP\^; -.br - XContext \fIcontext\fP\^; -.br - XPointer *\fIdata_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIrid\fP 1i -Specifies the resource ID with which the data is associated. -.IP \fIcontext\fP 1i -Specifies the context type to which the data belongs. -.IP \fIdata_return\fP 1i -Returns the data. -.LP -.eM -Because it is a return value, -the data is a pointer. -The -.PN XFindContext -function returns a nonzero error code if an error has occurred -and zero otherwise. -Possible errors are -.PN XCNOENT -(context-not-found). -.LP -.sp -To delete an entry for a given resource ID and type, use -.PN XDeleteContext . -.IN "XDeleteContext" "" "@DEF@" -.sM -.FD 0 -int XDeleteContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIrid\fP; -.br - XContext \fIcontext\fP; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIrid\fP 1i -Specifies the resource ID with which the data is associated. -.IP \fIcontext\fP 1i -Specifies the context type to which the data belongs. -.LP -.eM -The -.PN XDeleteContext -function deletes the entry for the given resource ID -and type from the data structure. -This function returns the same error codes that -.PN XFindContext -returns if called with the same arguments. -.PN XDeleteContext -does not free the data whose address was saved. -.LP -.sp -To create a unique context type that may be used in subsequent calls to -.PN XSaveContext -and -.PN XFindContext , -use -.PN XUniqueContext . -.IN "XUniqueContext" "" "@DEF@" -.sM -.FD 0 -XContext XUniqueContext(\^) -.FN -.LP -.eM -.bp diff --git a/libX11/specs/libX11/CH16.xml b/libX11/specs/libX11/CH16.xml new file mode 100644 index 000000000..7575c4a61 --- /dev/null +++ b/libX11/specs/libX11/CH16.xml @@ -0,0 +1,4136 @@ +<chapter id="application_utility_functions">
+<title>Application Utility Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 16 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 16: Application Utility Functions -->
+<!-- .XE -->
+Once you have initialized the X system,
+you can use the Xlib utility functions to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Use keyboard utility functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use Latin-1 keyboard event functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Allocate permanent storage
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Parse the window geometry
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manipulate regions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use cut buffers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Determine the appropriate visual type
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manipulate images
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manipulate bitmaps
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use the context manager
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+As a group,
+the functions discussed in this chapter provide the functionality that
+is frequently needed and that spans toolkits.
+Many of these functions do not generate actual protocol requests to the server.
+</para>
+<sect1 id="Using_Keyboard_Utility_Functions">
+<title>Using Keyboard Utility Functions</title>
+<!-- .XS -->
+<!-- (SN Using Keyboard Utility Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses mapping between KeyCodes and KeySyms,
+classifying KeySyms, and mapping between KeySyms and string names.
+The first three functions in this section operate on a cached copy of the
+server keyboard mapping.
+The first four KeySyms for each KeyCode
+are modified according to the rules given in section 12.7.
+To obtain the untransformed KeySyms defined for a key,
+use the functions described in section 12.7.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a KeySym for the KeyCode of an event, use
+<function>XLookupKeysym</function>.
+<indexterm significance="preferred"><primary>XLookupKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>KeySym <function> XLookupKeysym</function></funcdef>
+ <paramdef>XKeyEvent<parameter> *key_event</parameter></paramdef>
+ <paramdef>int<parameter> index</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>key_event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>index</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the index into the KeySyms list for the event's KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookupKeysym</function>
+function uses a given keyboard event and the index you specified to return
+the KeySym from the list that corresponds to the KeyCode member in the
+<function>XKeyPressedEvent</function>
+or
+<function>XKeyReleasedEvent</function>
+structure.
+If no KeySym is defined for the KeyCode of the event,
+<function>XLookupKeysym</function>
+returns
+<function>NoSymbol</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a KeySym for a specific KeyCode, use
+<function>XKeycodeToKeysym</function>.
+<indexterm significance="preferred"><primary>XKeycodeToKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>KeySym <function> XKeycodeToKeysym</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>KeyCode<parameter> keycode</parameter></paramdef>
+ <paramdef>int<parameter> index</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>index</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the element of KeyCode vector.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XKeycodeToKeysym</function>
+function uses internal Xlib tables
+and returns the KeySym defined for the specified KeyCode and
+the element of the KeyCode vector.
+If no symbol is defined,
+<function>XKeycodeToKeysym</function>
+returns
+<function>NoSymbol</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a KeyCode for a key having a specific KeySym, use
+<function>XKeysymToKeycode</function>.
+<indexterm significance="preferred"><primary>XKeysymToKeycode</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>KeyCode <function> XKeysymToKeycode</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be searched for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified KeySym is not defined for any KeyCode,
+<function>XKeysymToKeycode</function>
+returns zero.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The mapping between KeyCodes and KeySyms is cached internal to Xlib.
+When this information is changed at the server, an Xlib function must
+be called to refresh the cache.
+To refresh the stored modifier and keymap information, use
+<function>XRefreshKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XRefreshKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRefreshKeyboardMapping</function></funcdef>
+ <paramdef>XMappingEvent<parameter> *event_map</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_map</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mapping event that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRefreshKeyboardMapping</function>
+function refreshes the stored modifier and keymap information.
+You usually call this function when a
+<function>MappingNotify</function>
+event with a request member of
+<function>MappingKeyboard</function>
+or
+<function>MappingModifier</function>
+occurs.
+The result is to update Xlib's knowledge of the keyboard.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the uppercase and lowercase forms of a KeySym, use
+<function>XConvertCase</function>.
+<indexterm significance="preferred"><primary>XConvertCase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> XConvertCase</function></funcdef>
+ <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+ <paramdef>KeySym<parameter> *lower_return</parameter></paramdef>
+ <paramdef>KeySym<parameter> *upper_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Fn converted -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lower_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the lowercase form of keysym, or keysym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>upper_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the uppercase form of keysym, or keysym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XConvertCase</function>
+function returns the uppercase and lowercase forms of the specified Keysym,
+if the KeySym is subject to case conversion;
+otherwise, the specified KeySym is returned to both lower_return and
+upper_return.
+Support for conversion of other than Latin and Cyrillic KeySyms is
+implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+KeySyms have string names as well as numeric codes.
+To convert the name of the KeySym to the KeySym code, use
+<function>XStringToKeysym</function>.
+<indexterm significance="preferred"><primary>XStringToKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>KeySym <function> XStringToKeysym</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the KeySym that is to be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Standard KeySym names are obtained from
+<!-- .hN X11/keysymdef.h -->
+by removing the XK_ prefix from each name.
+KeySyms that are not part of the Xlib standard also may be obtained
+with this function.
+The set of KeySyms that are available in this manner
+and the mechanisms by which Xlib obtains them is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+If the KeySym name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+If the specified string does not match a valid KeySym,
+<function>XStringToKeysym</function>
+returns
+<function>NoSymbol</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a KeySym code to the name of the KeySym, use
+<function>XKeysymToString</function>.
+<indexterm significance="preferred"><primary>XKeysymToString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XKeysymToString</function></funcdef>
+ <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Fn converted -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The returned string is in a static area and must not be modified.
+The returned string is in the Host Portable Character Encoding.
+If the specified KeySym is not defined,
+<function>XKeysymToString</function>
+returns a NULL.
+</para>
+<sect2 id="KeySym_Classification_Macros">
+<title>KeySym Classification Macros</title>
+<!-- .XS -->
+<!-- (SN KeySym Classification Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You may want to test if a KeySym is, for example,
+on the keypad or on one of the function keys.
+You can use KeySym macros to perform the following tests.
+</para>
+<para>IsCursorKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be tested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsCursorKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a cursor key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be tested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsFunctionKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a function key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsKeypadKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a standard keypad key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsPrivateKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsPrivateKeypadKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a vendor-private keypad key.
+</para>
+
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsMiscFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsMiscFunctionKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a miscellaneous function key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsModifierKey(<emphasis remap='I'>keysym</emphasis>)</para>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be tested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsModifierKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a modifier key.
+</para>
+
+<para>IsPFKey(<emphasis remap='I'>keysym</emphasis>)</para>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be tested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsPFKey</primary></indexterm>
+Returns
+<function>True</function>
+if the specified KeySym is a PF key.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Using_Latin_Keyboard_Event_Functions">
+<title>Using Latin-1 Keyboard Event Functions</title>
+<!-- .XS -->
+<!-- (SN Using Latin-1 Keyboard Event Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Chapter 13 describes internationalized text input facilities,
+but sometimes it is expedient to write an application that
+only deals with Latin-1 characters and ASCII controls,
+so Xlib provides a simple function for that purpose.
+<function>XLookupString</function>
+handles the standard modifier semantics described in section 12.7.
+This function does not use any of the input method facilities
+described in chapter 13 and does not depend on the current locale.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a key event to an ISO Latin-1 string, use
+<function>XLookupString</function>.
+<indexterm significance="preferred"><primary>XLookupString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XLookupString</function></funcdef>
+ <paramdef>XKeyEvent<parameter> *event_struct</parameter></paramdef>
+ <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> bytes_buffer</parameter></paramdef>
+ <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
+ <paramdef>XComposeStatus<parameter> *status_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_struct</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the key event structure to be used.
+You can pass
+<function>XKeyPressedEvent</function>
+or
+<function>XKeyReleasedEvent</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the translated characters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes_buffer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the buffer.
+No more than bytes_buffer of translation are returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the KeySym computed from the event if this argument is not NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>status_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies or returns the
+<function>XComposeStatus </function>
+structure or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookupString</function>
+function translates a key event to a KeySym and a string.
+The KeySym is obtained by using the standard interpretation of the
+<function>Shift</function>,
+<function>Lock</function>,
+group, and numlock modifiers as defined in the X Protocol specification.
+If the KeySym has been rebound (see
+<function>XRebindKeysym</function>),
+the bound string will be stored in the buffer.
+Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
+or (if the Control modifier is on) to an ASCII control character,
+and that character is stored in the buffer.
+<function>XLookupString</function>
+returns the number of characters that are stored in the buffer.
+</para>
+<para>
+<!-- .LP -->
+If present (non-NULL),
+the
+<function>XComposeStatus</function>
+structure records the state,
+which is private to Xlib,
+that needs preservation across calls to
+<function>XLookupString</function>
+to implement compose processing.
+The creation of
+<function>XComposeStatus</function>
+structures is implementation-dependent;
+a portable program must pass NULL for this argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XLookupString</function>
+depends on the cached keyboard information mentioned in the
+previous section, so it is necessary to use
+<function>XRefreshKeyboardMapping</function>
+to keep this information up-to-date.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rebind the meaning of a KeySym for
+<function>XLookupString</function>,
+use
+<function>XRebindKeysym</function>.
+<indexterm significance="preferred"><primary>XRebindKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRebindKeysym</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+ <paramdef>KeySym<parameter> list[\^]\^</parameter></paramdef>
+ <paramdef>int<parameter> mod_count</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> *string</parameter></paramdef>
+ <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Fn rebound -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym that is to be (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySyms to be used as modifiers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mod_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of modifiers in the modifier list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string that is copied and will be returned by
+<function>XLookupString</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the string argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRebindKeysym</function>
+function can be used to rebind the meaning of a KeySym for the client.
+It does not redefine any key in the X server but merely
+provides an easy way for long strings to be attached to keys.
+<function>XLookupString</function>
+returns this string when the appropriate set of
+modifier keys are pressed and when the KeySym would have been used for
+the translation.
+No text conversions are performed;
+the client is responsible for supplying appropriately encoded strings.
+Note that you can rebind a KeySym that may not exist.
+</para>
+</sect1>
+<sect1 id="Allocating_Permanent_Storage">
+<title>Allocating Permanent Storage</title>
+<!-- .XS -->
+<!-- (SN Allocating Permanent Storage -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To allocate some memory you will never give back, use
+<function>Xpermalloc</function>.
+<indexterm significance="preferred"><primary>Xpermalloc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> Xpermalloc</function></funcdef>
+ <paramdef>unsignedint<parameter> size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>Xpermalloc</function>
+function allocates storage that can never be freed for the life of the
+program. The memory is allocated with alignment for the C type double.
+This function may provide some performance and space savings over
+the standard operating system memory allocator.
+</para>
+</sect1>
+<sect1 id="Parsing_the_Window_Geometry">
+<title>Parsing the Window Geometry</title>
+<!-- .XS -->
+<!-- (SN Parsing the Window Geometry -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To parse standard window geometry strings, use
+<function>XParseGeometry</function>.
+<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>
+<indexterm significance="preferred"><primary>XParseGeometry</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XParseGeometry</function></funcdef>
+ <paramdef>char<parameter> *parsestring</parameter></paramdef>
+ <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parsestring</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string you want to parse.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the x and y offsets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height determined.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+By convention,
+X applications use a standard string to indicate window size and placement.
+<function>XParseGeometry</function>
+makes it easier to conform to this standard because it allows you
+to parse the standard window geometry.
+Specifically, this function lets you parse strings of the form:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+[=][<<emphasis remap='I'>width</emphasis>>{xX}<<emphasis remap='I'>height</emphasis>>][{+-}<<emphasis remap='I'>xoffset</emphasis>>{+-}<<emphasis remap='I'>yoffset</emphasis>>]
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The fields map into the arguments associated with this function.
+(Items enclosed in <\^> are integers, items in [\^] are optional, and
+items enclosed in {\^} indicate ``choose one of.''
+Note that the brackets should not appear in the actual string.)
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XParseGeometry</function>
+function returns a bitmask that indicates which of the four values (width,
+height, xoffset, and yoffset) were actually found in the string
+and whether the x and y values are negative.
+By convention, \-0 is not equal to +0, because the user needs to
+be able to say ``position the window relative to the right or bottom edge.''
+For each value found, the corresponding argument is updated.
+For each value not found, the argument is left unchanged.
+The bits are represented by
+<function>XValue</function>,
+<function>YValue</function>,
+<function>WidthValue</function>,
+<function>HeightValue</function>,
+<function>XNegative</function>,
+or
+<function>YNegative</function>
+and are defined in
+<!-- .hN X11/Xutil.h . -->
+They will be set whenever one of the values is defined
+or one of the signs is set.
+</para>
+<para>
+<!-- .LP -->
+If the function returns either the
+<function>XValue </function>
+or
+<function>YValue </function>
+flag,
+you should place the window at the requested position.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To construct a window's geometry information, use
+<function>XWMGeometry</function>.
+<indexterm significance="preferred"><primary>XWMGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XWMGeometry</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen</parameter></paramdef>
+ <paramdef>char<parameter> *user_geom</parameter></paramdef>
+ <paramdef>char<parameter> *def_geom</parameter></paramdef>
+ <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+ <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+ <paramdef>int<parameter> *width_return</parameter></paramdef>
+ <paramdef>int<parameter> *height_return</parameter></paramdef>
+ <paramdef>int<parameter> *gravity_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>user_geom</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-specified geometry or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>def_geom</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's default geometry or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bwidth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the border width.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the x and y offsets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height determined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gravity_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the window gravity.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWMGeometry </function>
+function combines any geometry information (given in the format used by
+<function>XParseGeometry</function>)
+specified by the user and by the calling program with size hints
+(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position,
+size, and gravity
+(<function>NorthWestGravity</function>,
+<function>NorthEastGravity</function>,
+<function>SouthEastGravity</function>,
+or
+<function>SouthWestGravity</function>)
+that describe the window.
+If the base size is not set in the
+<function>XSizeHints</function>
+structure,
+the minimum size is used if set.
+Otherwise, a base size of zero is assumed.
+If no minimum size is set in the hints structure,
+the base size is used.
+A mask (in the form returned by
+<function>XParseGeometry</function>)
+that describes which values came from the user specification
+and whether or not the position coordinates are relative
+to the right and bottom edges is returned.
+Note that these coordinates will have already been accounted for
+in the x_return and y_return values.
+</para>
+<para>
+<!-- .LP -->
+Note that invalid geometry specifications can cause a width or height
+of zero to be returned.
+The caller may pass the address of the hints win_gravity field
+as gravity_return to update the hints directly.
+</para>
+</sect1>
+
+<sect1 id="Manipulating_Regions">
+<title>Manipulating Regions</title>
+<!-- .XS -->
+<!-- (SN Manipulating Regions -->
+<!-- .XE -->
+<para>
+Regions are arbitrary sets of pixel locations.
+Xlib provides functions for manipulating regions.
+The opaque type
+<function>Region</function>
+is defined in
+<!-- .hN X11/Xutil.h . -->
+Xlib provides functions that you can use to manipulate regions.
+This section discusses how to:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+Create, copy, or destroy regions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Move or shrink regions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Compute with regions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Determine if regions are empty or equal
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate a point or rectangle in a region
+ </para>
+ </listitem>
+</itemizedlist>
+
+<sect2 id="Creating_Copying_or_Destroying_Regions">
+<title>Creating, Copying, or Destroying Regions</title>
+<!-- .XS -->
+<!-- (SN Creating, Copying, or Destroying Regions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To create a new empty region, use
+<function>XCreateRegion</function>.
+</para>
+<para>Region XCreateRegion()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To generate a region from a polygon, use
+<function>XPolygonRegion</function>.
+</para>
+<indexterm significance="preferred"><primary>XPolygonRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Region <function> XPolygonRegion</function></funcdef>
+ <paramdef>XPoint<parameter> points[]</parameter></paramdef>
+ <paramdef>int<parameter> n</parameter></paramdef>
+ <paramdef>int<parameter> fill_rule</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>points</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of points.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>n</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of points in the polygon.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fill_rule</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fill-rule you want to set for the specified GC.
+You can pass
+<function>EvenOddRule</function>
+or
+<function>WindingRule</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPolygonRegion</function>
+function returns a region for the polygon defined by the points array.
+For an explanation of fill_rule,
+see
+<function>XCreateGC</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-mask of a GC to a region, use
+<function>XSetRegion</function>.
+<indexterm significance="preferred"><primary>XSetRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetRegion</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>GC<parameter> gc</parameter></paramdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the GC.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetRegion</function>
+function sets the clip-mask in the GC to the specified region.
+The region is specified relative to the drawable's origin.
+The resulting GC clip origin is implementation-dependent.
+Once it is set in the GC,
+the region can be destroyed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To deallocate the storage associated with a specified region, use
+<function>XDestroyRegion</function>.
+<indexterm significance="preferred"><primary>XDestroyRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDestroyRegion</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Moving_or_Shrinking_Regions">
+<title>Moving or Shrinking Regions</title>
+<!-- .XS -->
+<!-- (SN Moving or Shrinking Regions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To move a region by a specified amount, use
+<function>XOffsetRegion</function>.
+<indexterm significance="preferred"><primary>XOffsetRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XOffsetRegion</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+ <paramdef>intdx,<parameter> dy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+<!-- .ds Dy move -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dx</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dy</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates,
+which define the amount you want to (Dy the specified region.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To reduce a region by a specified amount, use
+<function>XShrinkRegion</function>.
+<indexterm significance="preferred"><primary>XShrinkRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XShrinkRegion</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+ <paramdef>intdx,<parameter> dy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+<!-- .ds Dy shrink -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dx</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dy</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates,
+which define the amount you want to (Dy the specified region.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Positive values shrink the size of the region,
+and negative values expand the region.
+</para>
+</sect2>
+<sect2 id="Computing_with_Regions">
+<title>Computing with Regions</title>
+<!-- .XS -->
+<!-- (SN Computing with Regions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To generate the smallest rectangle enclosing a region, use
+<function>XClipBox</function>.
+<indexterm significance="preferred"><primary>XClipBox</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XClipBox</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rect_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the smallest enclosing rectangle.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XClipBox</function>
+function returns the smallest rectangle enclosing the specified region.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To compute the intersection of two regions, use
+<function>XIntersectRegion</function>.
+<indexterm significance="preferred"><primary>XIntersectRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XIntersectRegion</function></funcdef>
+ <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sra</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>srb</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the two regions with which you want to perform the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dr_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the result of the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To compute the union of two regions, use
+<function>XUnionRegion</function>.
+<indexterm significance="preferred"><primary>XUnionRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUnionRegion</function></funcdef>
+ <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sra</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>srb</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the two regions with which you want to perform the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dr_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the result of the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To create a union of a source region and a rectangle, use
+<function>XUnionRectWithRegion</function>.
+<indexterm significance="preferred"><primary>XUnionRectWithRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUnionRectWithRegion</function></funcdef>
+ <paramdef>XRectangle<parameter> *rectangle</parameter></paramdef>
+ <paramdef>Region<parameter> src_region</parameter></paramdef>
+ <paramdef>Region<parameter> dest_region_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rectangle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the rectangle.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_region</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source region to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_region_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the destination region.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnionRectWithRegion</function>
+function updates the destination region from a union of the specified rectangle
+and the specified source region.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To subtract two regions, use
+<function>XSubtractRegion</function>.
+<indexterm significance="preferred"><primary>XSubtractRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSubtractRegion</function></funcdef>
+ <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sra</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>srb</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the two regions with which you want to perform the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dr_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the result of the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSubtractRegion</function>
+function subtracts srb from sra and stores the results in dr_return.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To calculate the difference between the union and intersection
+of two regions, use
+<function>XXorRegion</function>.
+<indexterm significance="preferred"><primary>XXorRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XXorRegion</function></funcdef>
+ <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sra</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>srb</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the two regions with which you want to perform the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dr_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the result of the computation.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Determining_if_Regions_Are_Empty_or_Equal">
+<title>Determining if Regions Are Empty or Equal</title>
+<!-- .XS -->
+<!-- (SN Determining if Regions Are Empty or Equal -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To determine if the specified region is empty, use
+<function>XEmptyRegion</function>.
+<indexterm significance="preferred"><primary>XEmptyRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XEmptyRegion</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEmptyRegion</function>
+function returns
+<function>True</function>
+if the region is empty.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine if two regions have the same offset, size, and shape, use
+<function>XEqualRegion</function>.
+<indexterm significance="preferred"><primary>XEqualRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XEqualRegion</function></funcdef>
+ <paramdef>Regionr1,<parameter> r2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r1</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the two regions.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEqualRegion</function>
+function returns
+<function>True</function>
+if the two regions have the same offset, size, and shape.
+</para>
+</sect2>
+<sect2 id="Locating_a_Point_or_a_Rectangle_in_a_Region">
+<title>Locating a Point or a Rectangle in a Region</title>
+<!-- .XS -->
+<!-- (SN Locating a Point or a Rectangle in a Region -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To determine if a specified point resides in a specified region, use
+<function>XPointInRegion</function>.
+<indexterm significance="preferred"><primary>XPointInRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> XPointInRegion</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+<!-- .ds Xy , which define the point -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPointInRegion</function>
+function returns
+<function>True</function>
+if the point (x, y) is contained in the region r.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine if a specified rectangle is inside a region, use
+<function>XRectInRegion</function>.
+<indexterm significance="preferred"><primary>XRectInRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XRectInRegion</function></funcdef>
+ <paramdef>Region<parameter> r</parameter></paramdef>
+ <paramdef>intx,<parameter> y</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>r</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region.
+<!-- .ds Xy , which define the coordinates of the upper-left corner of the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which define the rectangle -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height(Wh.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRectInRegion</function>
+function returns
+<function>RectangleIn</function>
+if the rectangle is entirely in the specified region,
+<function>RectangleOut</function>
+if the rectangle is entirely out of the specified region,
+and
+<function>RectanglePart</function>
+if the rectangle is partially in the specified region.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Using_Cut_Buffers">
+<title>Using Cut Buffers</title>
+<!-- .XS -->
+<!-- (SN Using Cut Buffers -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Cut Buffers</primary></indexterm>
+Xlib provides functions to manipulate cut buffers,
+a very simple form of cut-and-paste inter-client communication.
+Selections are a much more powerful and useful mechanism for
+interchanging data between clients (see section 4.5)
+and generally should be used instead of cut buffers.
+</para>
+<para>
+<!-- .LP -->
+Cut buffers are implemented as properties on the first root window
+of the display.
+The buffers can only contain text, in the STRING encoding.
+The text encoding is not changed by Xlib when fetching or storing.
+Eight buffers are provided
+and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store data in cut buffer 0, use
+<function>XStoreBytes</function>.
+<indexterm significance="preferred"><primary>XStoreBytes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XStoreBytes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *bytes</parameter></paramdef>
+ <paramdef>int<parameter> \^nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the bytes, which are not necessarily ASCII or null-terminated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The data can have embedded null characters
+and need not be null-terminated.
+The cut buffer's contents can be retrieved later by
+any client calling
+<function>XFetchBytes</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreBytes</function>
+can generate a
+<function>BadAlloc</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store data in a specified cut buffer, use
+<function>XStoreBuffer</function>.
+<indexterm significance="preferred"><primary>XStoreBuffer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XStoreBuffer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *bytes</parameter></paramdef>
+ <paramdef>int<parameter> \^nbytes</parameter></paramdef>
+ <paramdef>int<parameter> buffer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the bytes, which are not necessarily ASCII or null-terminated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes to be stored.
+<!-- .ds Fn in which you want to store the bytes -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If an invalid buffer is specified, the call has no effect.
+The data can have embedded null characters
+and need not be null-terminated.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreBuffer</function>
+can generate a
+<function>BadAlloc </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return data from cut buffer 0, use
+<function>XFetchBytes</function>.
+<indexterm significance="preferred"><primary>XFetchBytes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XFetchBytes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *nbytes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of bytes in the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchBytes</function>
+function
+returns the number of bytes in the nbytes_return argument,
+if the buffer contains data.
+Otherwise, the function
+returns NULL and sets nbytes to 0.
+The appropriate amount of storage is allocated and the pointer returned.
+The client must free this storage when finished with it by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return data from a specified cut buffer, use
+<function>XFetchBuffer</function>.
+<indexterm significance="preferred"><primary>XFetchBuffer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function> XFetchBuffer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *nbytes_return</parameter></paramdef>
+ <paramdef>int<parameter> buffer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of bytes in the buffer.
+<!-- .ds Fn from which you want the stored data returned -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer (Fn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchBuffer</function>
+function returns zero to the nbytes_return argument
+if there is no data in the buffer or if an invalid
+buffer is specified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rotate the cut buffers, use
+<function>XRotateBuffers</function>.
+<indexterm significance="preferred"><primary>XRotateBuffers</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XRotateBuffers</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> rotate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rotate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how much to rotate the cut buffers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRotateBuffers</function>
+function rotates the cut
+buffers, such that buffer 0 becomes buffer n,
+buffer 1 becomes n + 1 mod 8, and so on.
+This cut buffer numbering is global to the display.
+Note that
+<function>XRotateBuffers</function>
+generates
+<function>BadMatch</function>
+errors if any of the eight buffers have not been created.
+</para>
+</sect1>
+<sect1 id="Determining_the_Appropriate_Visual_Type">
+<title>Determining the Appropriate Visual Type</title>
+<!-- .XS -->
+<!-- (SN Determining the Appropriate Visual Type -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A single display can support multiple screens.
+Each screen can have several different visual types supported
+at different depths.
+You can use the functions described in this section to determine
+which visual to use for your application.
+</para>
+<para>
+<!-- .LP -->
+The functions in this section use the visual information masks and the
+<function>XVisualInfo </function>
+structure,
+which is defined in
+<!-- .hN X11/Xutil.h -->
+and contains:
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+
+/* Visual information mask bits */
+
+
+#define VisualNoMask 0x0
+#define VisualIDMask 0x1
+#define VisualScreenMask 0x2
+#define VisualDepthMask 0x4
+#define VisualClassMask 0x8
+#define VisualRedMaskMask 0x10
+#define VisualGreenMaskMask 0x20
+#define VisualBlueMaskMask 0x40
+#define VisualColormapSizeMask 0x80
+#define VisualBitsPerRGBMask 0x100
+#define VisualAllMask 0x1FF
+
+</literallayout>
+
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* Values */
+
+typedef struct {
+ Visual *visual;
+ VisualID visualid;
+ int screen;
+ unsigned int depth;
+ int class;
+ unsigned long red_mask;
+ unsigned long green_mask;
+ unsigned long blue_mask;
+ int colormap_size;
+ int bits_per_rgb;
+} XVisualInfo;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To obtain a list of visual information structures that match a specified
+template, use
+<function>XGetVisualInfo</function>.
+<indexterm significance="preferred"><primary>XGetVisualInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XVisualInfo *<function> XGetVisualInfo</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>long<parameter> vinfo_mask</parameter></paramdef>
+ <paramdef>XVisualInfo<parameter> *vinfo_template</parameter></paramdef>
+ <paramdef>int<parameter> *nitems_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vinfo_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual mask value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vinfo_template</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual attributes that are to be used in matching the visual
+structures.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of matching visual structures.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetVisualInfo</function>
+function returns a list of visual structures that have attributes
+equal to the attributes specified by vinfo_template.
+If no visual structures match the template using the specified vinfo_mask,
+<function>XGetVisualInfo</function>
+returns a NULL.
+To free the data returned by this function, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the visual information that matches the specified depth and
+class of the screen, use
+<function>XMatchVisualInfo</function>.
+<indexterm significance="preferred"><primary>XMatchVisualInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function> XMatchVisualInfo</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen</parameter></paramdef>
+ <paramdef>int<parameter> depth</parameter></paramdef>
+ <paramdef>int<parameter> class</parameter></paramdef>
+ <paramdef>XVisualInfo<parameter> *vinfo_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the depth of the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>vinfo_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched visual information.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMatchVisualInfo</function>
+function returns the visual information for a visual that matches the specified
+depth and class for a screen.
+Because multiple visuals that match the specified depth and class can exist,
+the exact visual chosen is undefined.
+If a visual is found,
+<function>XMatchVisualInfo</function>
+returns nonzero and the information on the visual to vinfo_return.
+Otherwise, when a visual is not found,
+<function>XMatchVisualInfo</function>
+returns zero.
+</para>
+</sect1>
+<sect1 id="Manipulating_Images">
+<title>Manipulating Images</title>
+<!-- .XS -->
+<!-- (SN Manipulating Images -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides several functions that perform basic operations on images.
+All operations on images are defined using an
+<function>XImage </function>
+structure,
+as defined in
+<!-- .hN X11/Xlib.h . -->
+Because the number of different types of image formats can be very large,
+this hides details of image storage properly from applications.
+</para>
+<para>
+<!-- .LP -->
+This section describes the functions for generic operations on images.
+Manufacturers can provide very fast implementations of these for the
+formats frequently encountered on their hardware.
+These functions are neither sufficient nor desirable to use for general image
+processing.
+Rather, they are here to provide minimal functions on screen format
+images.
+The basic operations for getting and putting images are
+<function>XGetImage</function>
+and
+<function>XPutImage</function>.
+</para>
+<para>
+<!-- .LP -->
+Note that no functions have been defined, as yet, to read and write images
+to and from disk files.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XImage </function>
+structure describes an image as it exists in the client's memory.
+The user can request that some of the members such as height, width,
+and xoffset be changed when the image is sent to the server.
+Note that bytes_per_line in concert with offset can be used to
+extract a subset of the image.
+Other members (for example, byte order, bitmap_unit, and so forth)
+are characteristics of both the image and the server.
+If these members
+differ between the image and the server,
+<function>XPutImage </function>
+makes the appropriate conversions.
+The first byte of the first line of
+plane n must be located at the address (data + (n * height * bytes_per_line)).
+For a description of the
+<function>XImage </function>
+structure,
+see section 8.7.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate an
+<function>XImage </function>
+structure and initialize it with image format values from a display, use
+<function>XCreateImage</function>.
+<indexterm significance="preferred"><primary>XCreateImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XImage *<function> XCreateImage</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Visual<parameter> *visual</parameter></paramdef>
+ <paramdef>unsignedint<parameter> depth</parameter></paramdef>
+ <paramdef>int<parameter> format</parameter></paramdef>
+ <paramdef>int<parameter> offset</parameter></paramdef>
+ <paramdef>char<parameter> *data</parameter></paramdef>
+ <paramdef>unsignedint<parameter> width</parameter></paramdef>
+ <paramdef>unsignedint<parameter> height</parameter></paramdef>
+ <paramdef>int<parameter> bitmap_pad</parameter></paramdef>
+ <paramdef>int<parameter> bytes_per_line</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>Visual</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the depth of the image.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the format for the image.
+You can pass
+<function>XYBitmap</function>,
+<function>XYPixmap</function>,
+or
+<function>ZPixmap</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of pixels to ignore at the beginning of the scanline.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width of the image, in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height of the image, in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bitmap_pad</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the quantum of a scanline (8, 16, or 32).
+In other words, the start of one scanline is separated in client memory from
+the start of the next scanline by an integer multiple of this many bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes_per_line</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes in the client image between
+the start of one scanline and the start of the next.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateImage</function>
+function allocates the memory needed for an
+<function>XImage</function>
+structure for the
+specified display but does not allocate space for the image itself.
+Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
+values from the display and returns a pointer to the
+<function>XImage </function>
+structure.
+The red, green, and blue mask values are defined for Z format images only
+and are derived from the
+<function>Visual </function>
+structure passed in.
+Other values also are passed in.
+The offset permits the rapid displaying of the image without requiring each
+scanline to be shifted into position.
+If you pass a zero value in bytes_per_line,
+Xlib assumes that the scanlines are contiguous
+in memory and calculates the value of bytes_per_line itself.
+</para>
+<para>
+<!-- .LP -->
+Note that when the image is created using
+<function>XCreateImage</function>,
+<function>XGetImage</function>,
+or
+<function>XSubImage</function>,
+the destroy procedure that the
+<function>XDestroyImage</function>
+function calls frees both the image structure
+and the data pointed to by the image structure.
+</para>
+<para>
+<!-- .LP -->
+The basic functions used to get a pixel, set a pixel, create a subimage,
+and add a constant value to an image are defined in the image object.
+The functions in this section are really macro invocations of the functions
+in the image object and are defined in
+<!-- .hN X11/Xutil.h . -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pixel value in an image, use
+<function>XGetPixel</function>.
+<indexterm significance="preferred"><primary>XGetPixel</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function> XGetPixel</function></funcdef>
+ <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+ <paramdef>int<parameter> x</parameter></paramdef>
+ <paramdef>int<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ximage</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPixel</function>
+function returns the specified pixel from the named image.
+The pixel value is returned in normalized format (that is,
+the least significant byte of the long is the least significant byte
+of the pixel).
+The image must contain the x and y coordinates.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a pixel value in an image, use
+<function>XPutPixel</function>.
+<indexterm significance="preferred"><primary>XPutPixel</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPutPixel</function></funcdef>
+ <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+ <paramdef>int<parameter> x</parameter></paramdef>
+ <paramdef>int<parameter> y</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ximage</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixel</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new pixel value.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPutPixel</function>
+function overwrites the pixel in the named image with the specified pixel value.
+The input pixel value must be in normalized format
+(that is, the least significant byte of the long is the least significant
+byte of the pixel).
+The image must contain the x and y coordinates.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a subimage, use
+<function>XSubImage</function>.
+<indexterm significance="preferred"><primary>XSubImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XImage *<function> XSubImage</function></funcdef>
+ <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+ <paramdef>int<parameter> x</parameter></paramdef>
+ <paramdef>int<parameter> y</parameter></paramdef>
+ <paramdef>unsignedint<parameter> subimage_width</parameter></paramdef>
+ <paramdef>unsignedint<parameter> subimage_height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ximage</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>subimage_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width of the new subimage, in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>subimage_height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height of the new subimage, in pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSubImage</function>
+function creates a new image that is a subsection of an existing one.
+It allocates the memory necessary for the new
+<function>XImage</function>
+structure
+and returns a pointer to the new image.
+The data is copied from the source image,
+and the image must contain the rectangle defined by x, y, subimage_width,
+and subimage_height.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To increment each pixel in an image by a constant value, use
+<function>XAddPixel</function>.
+<indexterm significance="preferred"><primary>XAddPixel</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAddPixel</function></funcdef>
+ <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+ <paramdef>long<parameter> value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ximage</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the constant value that is to be added.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddPixel</function>
+function adds a constant value to every pixel in an image.
+It is useful when you have a base pixel value from allocating
+color resources and need to manipulate the image to that form.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To deallocate the memory allocated in a previous call to
+<function>XCreateImage</function>,
+use
+<function>XDestroyImage</function>.
+<indexterm significance="preferred"><primary>XDestroyImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDestroyImage</function></funcdef>
+ <paramdef>XImage<parameter> *\^ximage</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ximage</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the image.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroyImage</function>
+function deallocates the memory associated with the
+<function>XImage</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+Note that when the image is created using
+<function>XCreateImage</function>,
+<function>XGetImage</function>,
+or
+<function>XSubImage</function>,
+the destroy procedure that this macro calls
+frees both the image structure and the data pointed to by the image structure.
+</para>
+</sect1>
+<sect1 id="Manipulating_Bitmaps">
+<title>Manipulating Bitmaps</title>
+<!-- .XS -->
+<!-- (SN Manipulating Bitmaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to read a bitmap from a file,
+save a bitmap to a file, or create a bitmap.
+This section describes those functions that transfer bitmaps to and
+from the client's file system, thus allowing their reuse in a later
+connection (for example, from an entirely different client or to a
+different display or server).
+</para>
+<para>
+<!-- .LP -->
+The X version 11 bitmap file format is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+#define <emphasis remap='I'>name</emphasis>_width <emphasis remap='I'>width</emphasis>
+#define <emphasis remap='I'>name</emphasis>_height <emphasis remap='I'>height</emphasis>
+#define <emphasis remap='I'>name</emphasis>_x_hot <emphasis remap='I'>x</emphasis>
+#define <emphasis remap='I'>name</emphasis>_y_hot <emphasis remap='I'>y</emphasis>
+static unsigned char <emphasis remap='I'>name</emphasis>_bits[] = { 0x<emphasis remap='I'>NN</emphasis>,... }
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The lines for the variables ending with _x_hot and _y_hot suffixes are optional
+because they are present only if a hotspot has been defined for this bitmap.
+The lines for the other variables are required.
+The word ``unsigned'' is optional;
+that is, the type of the _bits array can be ``char'' or ``unsigned char''.
+The _bits array must be large enough to contain the size bitmap.
+The bitmap unit is 8.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a bitmap from a file and store it in a pixmap, use
+<function>XReadBitmapFile</function>.
+<indexterm significance="preferred"><primary>XReadBitmapFile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XReadBitmapFile</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+ <paramdef>Pixmap<parameter> *bitmap_return</parameter></paramdef>
+ <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Dr \ that indicates the screen -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable(Dr.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height values of the read in bitmap file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bitmap_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the bitmap that is created.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_hot_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_hot_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the hotspot coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XReadBitmapFile</function>
+function reads in a file containing a bitmap.
+The file is parsed in the encoding of the current locale.
+The ability to read other than the standard format
+is implementation-dependent.
+If the file cannot be opened,
+<function>XReadBitmapFile </function>
+returns
+<function>BitmapOpenFailed</function>.
+If the file can be opened but does not contain valid bitmap data,
+it returns
+<function>BitmapFileInvalid</function>.
+If insufficient working storage is allocated,
+it returns
+<function>BitmapNoMemory</function>.
+If the file is readable and valid,
+it returns
+<function>BitmapSuccess</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XReadBitmapFile </function>
+returns the bitmap's height and width, as read
+from the file, to width_return and height_return.
+It then creates a pixmap of the appropriate size,
+reads the bitmap data from the file into the pixmap,
+and assigns the pixmap to the caller's variable bitmap.
+The caller must free the bitmap using
+<function>XFreePixmap </function>
+when finished.
+If <emphasis remap='I'>name</emphasis>_x_hot and <emphasis remap='I'>name</emphasis>_y_hot exist,
+<function>XReadBitmapFile </function>
+returns them to x_hot_return and y_hot_return;
+otherwise, it returns \-1,\-1.
+</para>
+<para>
+<!-- .LP -->
+<function>XReadBitmapFile</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadDrawable</function>,
+and
+<function>BadGC</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a bitmap from a file and return it as data, use
+<function>XReadBitmapFileData</function>.
+<indexterm significance="preferred"><primary>XReadBitmapFileData</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XReadBitmapFileData</function></funcdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+ <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> *data_return</parameter></paramdef>
+ <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the width and height values of the read in bitmap file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the bitmap data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_hot_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_hot_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the hotspot coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XReadBitmapFileData</function>
+function reads in a file containing a bitmap, in the same manner as
+<function>XReadBitmapFile</function>,
+but returns the data directly rather than creating a pixmap in the server.
+The bitmap data is returned in data_return; the client must free this
+storage when finished with it by calling
+<function>XFree</function>.
+The status and other return values are the same as for
+<function>XReadBitmapFile</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To write out a bitmap from a pixmap to a file, use
+<function>XWriteBitmapFile</function>.
+<indexterm significance="preferred"><primary>XWriteBitmapFile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XWriteBitmapFile</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+ <paramdef>Pixmap<parameter> bitmap</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>intx_hot,<parameter> y_hot</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bitmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the bitmap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x_hot</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y_hot</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)
+in the file.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWriteBitmapFile</function>
+function writes a bitmap out to a file in the X Version 11 format.
+The name used in the output file is derived from the file name
+by deleting the directory prefix.
+The file is written in the encoding of the current locale.
+If the file cannot be opened for writing,
+it returns
+<function>BitmapOpenFailed</function>.
+If insufficient memory is allocated,
+<function>XWriteBitmapFile</function>
+returns
+<function>BitmapNoMemory</function>;
+otherwise, on no error,
+it returns
+<function>BitmapSuccess</function>.
+If x_hot and y_hot are not \-1, \-1,
+<function>XWriteBitmapFile</function>
+writes them out as the hotspot coordinates for the bitmap.
+</para>
+<para>
+<!-- .LP -->
+<function>XWriteBitmapFile</function>
+can generate
+<function>BadDrawable</function>
+and
+<function>BadMatch</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a pixmap and then store bitmap-format data into it, use
+<function>XCreatePixmapFromBitmapData</function>.
+<indexterm significance="preferred"><primary>XCreatePixmapFromBitmapData</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Pixmap <function> XCreatePixmapFromBitmapData</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>char<parameter> *data</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+ <paramdef>unsignedlongfg,<parameter> bg</parameter></paramdef>
+ <paramdef>unsignedint<parameter> depth</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Dr \ that indicates the screen -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable(Dr.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data in bitmap format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fg</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the foreground and background pixel values to use.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the depth of the pixmap.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreatePixmapFromBitmapData</function>
+function creates a pixmap of the given depth and then does a bitmap-format
+<function>XPutImage</function>
+of the data into it.
+The depth must be supported by the screen of the specified drawable,
+or a
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreatePixmapFromBitmapData</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadDrawable</function>,
+<function>BadGC</function>,
+and
+<function>BadValue</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To include a bitmap written out by
+<function>XWriteBitmapFile </function>
+<indexterm><primary>XWriteBitmapFile</primary></indexterm>
+in a program directly, as opposed to reading it in every time at run time, use
+<function>XCreateBitmapFromData</function>.
+<indexterm significance="preferred"><primary>XCreateBitmapFromData</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Pixmap <function> XCreateBitmapFromData</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Drawable<parameter> d</parameter></paramdef>
+ <paramdef>char<parameter> *data</parameter></paramdef>
+ <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Dr \ that indicates the screen -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable(Dr.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the location of the bitmap data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateBitmapFromData</function>
+function allows you to include in your C program (using
+<function>#include</function>)
+a bitmap file that was written out by
+<function>XWriteBitmapFile</function>
+(X version 11 format only) without reading in the bitmap file.
+The following example creates a gray bitmap:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+#include "gray.bitmap"
+<!-- .sp 6p -->
+Pixmap bitmap;
+bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If insufficient working storage was allocated,
+<function>XCreateBitmapFromData</function>
+returns
+<function>None</function>.
+It is your responsibility to free the
+bitmap using
+<function>XFreePixmap</function>
+when finished.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateBitmapFromData</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadGC</function>
+errors.
+</para>
+</sect1>
+<sect1 id="Using_the_Context_Manager">
+<title>Using the Context Manager</title>
+<!-- .XS -->
+<!-- (SN Using the Context Manager -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The context manager provides a way of associating data with an X resource ID
+(mostly typically a window) in your program.
+Note that this is local to your program;
+the data is not stored in the server on a property list.
+Any amount of data in any number of pieces can be associated with a
+resource ID,
+and each piece of data has a type associated with it.
+The context manager requires knowledge of the resource ID
+and type to store or retrieve data.
+</para>
+<para>
+<!-- .LP -->
+Essentially, the context manager can be viewed as a two-dimensional,
+sparse array: one dimension is subscripted by the X resource ID
+and the other by a context type field.
+Each entry in the array contains a pointer to the data.
+Xlib provides context management functions with which you can
+save data values, get data values, delete entries, and create a unique
+context type.
+The symbols used are in
+<!-- .hN X11/Xutil.h . -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To save a data value that corresponds to a resource ID and context type, use
+<function>XSaveContext</function>.
+<indexterm significance="preferred"><primary>XSaveContext</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XSaveContext</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> rid</parameter></paramdef>
+ <paramdef>XContext<parameter> context</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rid</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource ID with which the data is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the context type to which the data belongs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data to be associated with the window and type.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If an entry with the specified resource ID and type already exists,
+<function>XSaveContext</function>
+overrides it with the specified context.
+The
+<function>XSaveContext</function>
+function returns a nonzero error code if an error has occurred
+and zero otherwise.
+Possible errors are
+<function>XCNOMEM</function>
+(out of memory).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the data associated with a resource ID and type, use
+<function>XFindContext</function>.
+<indexterm significance="preferred"><primary>XFindContext</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XFindContext</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> rid</parameter></paramdef>
+ <paramdef>XContext<parameter> context</parameter></paramdef>
+ <paramdef>XPointer<parameter> *data_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rid</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource ID with which the data is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the context type to which the data belongs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Because it is a return value,
+the data is a pointer.
+The
+<function>XFindContext</function>
+function returns a nonzero error code if an error has occurred
+and zero otherwise.
+Possible errors are
+<function>XCNOENT</function>
+(context-not-found).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry for a given resource ID and type, use
+<function>XDeleteContext</function>.
+<indexterm significance="preferred"><primary>XDeleteContext</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function> XDeleteContext</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XID<parameter> rid</parameter></paramdef>
+ <paramdef>XContext<parameter> context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rid</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource ID with which the data is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the context type to which the data belongs.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteContext</function>
+function deletes the entry for the given resource ID
+and type from the data structure.
+This function returns the same error codes that
+<function>XFindContext</function>
+returns if called with the same arguments.
+<function>XDeleteContext</function>
+does not free the data whose address was saved.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a unique context type that may be used in subsequent calls to
+<function>XSaveContext </function>
+and
+<function>XFindContext</function>,
+use
+<function>XUniqueContext</function>.
+</para>
+<para>XContext XuniqueContext()</para>
+
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/Makefile.am b/libX11/specs/libX11/Makefile.am index c76b4e943..76fa0f688 100644 --- a/libX11/specs/libX11/Makefile.am +++ b/libX11/specs/libX11/Makefile.am @@ -21,36 +21,34 @@ # DEALINGS IN THE SOFTWARE.
#
-# Based on xc/doc/specs/X11/Makefile from X11R6.9
+if ENABLE_SPECS
-doc_sources = libX11.ms
+specdir = $(docdir)/$(subdir)
+doc_sources = libX11.xml
+dist_spec_DATA = $(doc_sources) \
+ AppA.xml \
+ AppB.xml \
+ AppC.xml \
+ AppD.xml \
+ CH01.xml \
+ CH02.xml \
+ CH03.xml \
+ CH04.xml \
+ CH05.xml \
+ CH06.xml \
+ CH07.xml \
+ CH08.xml \
+ CH09.xml \
+ CH10.xml \
+ CH11.xml \
+ CH12.xml \
+ CH13.xml \
+ CH14.xml \
+ CH15.xml \
+ CH16.xml \
+ credits.xml \
+ glossary.xml
-doc_includes = \
- abstract.t \
- credits.t \
- CH01 \
- CH02 \
- CH03 \
- CH04 \
- CH05 \
- CH06 \
- CH07 \
- CH08 \
- CH09 \
- CH10 \
- CH11 \
- CH12 \
- CH13 \
- CH14 \
- CH15 \
- CH16 \
- AppA \
- AppB \
- AppC \
- AppD \
- glossary \
- postproc
+include $(top_srcdir)/specs/xmlrules.in
-include $(top_srcdir)/specs/troffrules.in
-
-EXTRA_DIST += $(doc_includes)
+endif ENABLE_SPECS
diff --git a/libX11/specs/libX11/abstract.t b/libX11/specs/libX11/abstract.t deleted file mode 100644 index 153fbc7a2..000000000 --- a/libX11/specs/libX11/abstract.t +++ /dev/null @@ -1,105 +0,0 @@ -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.ps 11 -.nr PS 11 -\& -.sp 5 -.ce 6 -\s+2\fBXlib \- C Language X Interface\fP\s-2 - -\s+1\fBX Window System Standard\fP\s-1 - -\s+1\fBX Version 11, Release 7\fP\s-1 - -\s+1\fB\*(xV\fP\s-1 -.sp 6 -.ce 4 -\s-1James Gettys -.sp 6p -Cambridge Research Laboratory -Digital Equipment Corporation -.sp 2 -.ce 4 -Robert W. Scheifler -.sp 6p -Laboratory for Computer Science -Massachusetts Institute of Technology -.sp 3 -.ce 1 -\fIwith contributions from\fP -.sp 3 -.ce 11 -Chuck Adams, Tektronix, Inc. -.sp 1 -Vania Joloboff, Open Software Foundation -.sp 1 -Hideki Hiura, Sun Microsystems, Inc. -.sp 1 -Bill McMahon, Hewlett-Packard Company -.sp 1 -Ron Newman, Massachusetts Institute of Technology -.sp 1 -Al Tabayoyon, Tektronix, Inc. -.sp 1 -Glenn Widener, Tektronix, Inc. -.sp 1 -Shigeru Yamada, Fujitsu OSSI -.bp -\& -.ps 9 -.nr PS 9 -.sp 8 -.LP -The X Window System is a trademark of The Open Group. -.LP -TekHVC is a trademark of Tektronix, Inc. -.sp 2 -.LP -Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 -The Open Group -.LP -Permission is hereby granted, free of charge, to any person obtaining -a copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: -.LP -The above copyright notice and this permission notice shall be included -in all copies or substantial portions of the Software. -.LP -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. -.LP -Except as contained in this notice, the name of The Open Group shall -not be used in advertising or otherwise to promote the sale, use or -other dealings in this Software without prior written authorization -from The Open Group. -.sp 3 -.LP -Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -Digital Equipment Corporation -.LP -Portions Copyright \(co 1990, 1991 by -Tektronix, Inc. -.LP -Permission to use, copy, modify and distribute this documentation for -any purpose and without fee is hereby granted, provided that the above -copyright notice appears in all copies and that both that copyright notice and -this permission notice appear in all copies, and that the names of -Digital and Tektronix not be used in in advertising or publicity -pertaining to this documentation without specific, written prior permission. -Digital and Tektronix makes no representations about the suitability -of this documentation for any purpose. -It is provided ``as is'' without express or implied warranty. -.ps 11 -.nr PS 11 -.bp diff --git a/libX11/specs/libX11/credits.t b/libX11/specs/libX11/credits.xml index 5d9909d7c..17713d3cb 100644 --- a/libX11/specs/libX11/credits.t +++ b/libX11/specs/libX11/credits.xml @@ -1,216 +1,232 @@ -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.XS ii -Table of Contents -.XE -.XS iii -Acknowledgments -.XE -\& -.sp 1 -.ce 3 -\s+1\fBAcknowledgments\fP\s-1 -.sp 2 -.na -.LP -The design and implementation of the first 10 versions of X -were primarily the work of three individuals: Robert Scheifler of the -MIT Laboratory for Computer Science and Jim Gettys of Digital -Equipment Corporation and Ron Newman of MIT, both at MIT -Project Athena. -X version 11, however, is the result of the efforts of -dozens of individuals at almost as many locations and organizations. -At the risk of offending some of the players by exclusion, -we would like to acknowledge some of the people who deserve special credit -and recognition for their work on Xlib. -Our apologies to anyone inadvertently overlooked. -.SH -Release 1 -.LP -Our thanks does to Ron Newman (MIT Project Athena), -who contributed substantially to the -design and implementation of the Version 11 Xlib interface. -.LP -Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept -it all together for us during the early releases. -He handled literally thousands of requests from people everywhere -and saved the sanity of at least one of us. -His calm good cheer was a foundation on which we could build. -.LP -Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned'' -to Project Athena at exactly the right moment to provide very capable -and much-needed assistance during the alpha and beta releases. -He was responsible for the successful integration of sources -from multiple sites; -we would not have had a release without him. -.LP -Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX -Documentation Group. -With good humor and cheer, -they took a rough draft and made it an infinitely better and more useful -document. -The work they have done will help many everywhere. -We also would like to thank Hal Murray (Digital SRC) and -Peter George (Digital VMS) who contributed much -by proofreading the early drafts of this document. -.LP -Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, -Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the -library utilities implementation; -to Hania Gajewska (Digital UEG-WSL) who, -along with Ellis Cohen (CMU and Siemens), -was instrumental in the semantic design of the window manager properties; -and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol -and provided the sample generic color frame buffer device-dependent code. -.LP -The alpha and beta test participants deserve special recognition and thanks -as well. -It is significant -that the bug reports (and many fixes) during alpha and beta test came almost -exclusively from just a few of the alpha testers, mostly hardware vendors -working on product implementations of X. -The continued public -contribution of vendors and universities is certainly to the benefit -of the entire X community. -.LP -Our special thanks must go to Sam Fuller, Vice-President of Corporate -Research at Digital, who has remained committed to the widest public -availability of X and who made it possible to greatly supplement MIT's -resources with the Digital staff in order to make version 11 a reality. -Many of the people mentioned here are part of the Western -Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group -and work for Smokey Wallace, who has been vital to the project's success. -Others not mentioned here worked on the toolkit and are acknowledged -in the X Toolkit documentation. -.LP -Of course, -we must particularly thank Paul Asente, formerly of Stanford University -and now of Digital UEG-WSL, who wrote W, the predecessor to X, -and Brian Reid, formerly of Stanford University and now of Digital WRL, -who had much to do with W's design. -.LP -Finally, our thanks goes to MIT, Digital Equipment Corporation, -and IBM for providing the environment where it could happen. -.SH -Release 4 -.LP -Our thanks go to Jim Fulton (MIT X Consortium) for designing and -specifying the new Xlib functions for Inter-Client Communication -Conventions (ICCCM) support. -.LP -We also thank Al Mento of Digital for his continued effort in -maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium) -for their much-appreciated efforts in reviewing the changes. -.SH -Release 5 -.LP -The principal authors of the Input Method facilities are -Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard). -The principal author of the rest of the internationalization facilities -is Glenn Widener (Tektronix). Our thanks to them for keeping their -sense of humor through a long and sometimes difficult design process. -Although the words and much of the design are due to them, many others -have contributed substantially to the design and implementation. -Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition -for their contributions. Other contributors were: -Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP), -Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital), -Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu), -Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM), -Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu Kaiya (Fujitsu), -Yuji Kamata (IBM), -Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC), -Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON), -Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT), -Nelson Ng (Sun), -Takashi Nishimura (NTT America), Makato Nishino (IBM), -Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T), -Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital), -Shoji Sugiyama (IBM), and Eiji Tosa (IBM). -.LP -We are deeply indebted to Tatsuya Kato (NTT), -Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT), -and Li Yuhong (OMRON) for producing one of the first complete -sample implementation of the internationalization facilities, and -Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun), -Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox), -Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), -Makoto Wakamatsu (Sony Corporation) for producing the another complete -sample implementation of the internationalization facilities. -.LP -The principal authors (design and implementation) of the Xcms color -management facilities are Al Tabayoyon (Tektronix) -and Chuck Adams (Tektronix). -Joann Taylor (Tektronix), Bob Toole (Tektronix), -and Keith Packard (MIT X Consortium) also -contributed significantly to the design. Others who contributed are: -Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI), -Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun), -Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM), -Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&T), -and Richard Verberg (IBM). -.LP -We also once again thank Al Mento of Digital for his work in formatting -and reformatting text for this manual, and for producing man pages. -Thanks also to Clive Feather (IXI) for proof-reading and finding a -number of small errors. -.SH -Release 6 -.LP -Stephen Gildea (X Consortium) authored the threads support. -Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially -by testing the facilities and reporting bugs in a timely fashion. -.LP -The principal authors of the internationalization facilities, including -Input and Output Methods, are Hideki Hiura (SunSoft) and -Shigeru Yamada (Fujitsu OSSI). -Although the words and much of the design are due to them, many others -have contributed substantially to the design and implementation. -They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), -Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), -Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP), -Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu), -Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), -Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and -Jinsoo Yoon (KAIST). -.LP -The principal producers of the sample implementation of the -internationalization facilities are: -Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu), -Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), -Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), -Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu), -Franky Ling (Digital), Hiroyuki Miyamoto (Digital), -Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu), -Makoto Wakamatsu (Sony), Masaki Wakao (IBM), -Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba). -.LP -The coordinators of the integration, testing, and release of this -implementation of the internationalization facilities are -Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony). -.LP -Others who have contributed to the architectural design or -testing of the sample implementation of the -internationalization facilities are: -Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital), -Hiroyuki Machida (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), -Yoshiyuki Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), -Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony), -Jinsoo Yoon (KAIST) and Akiyasu Zen (HP). -.sp 2 -.LP -.Ds 0 -.TA 1.5i 3i -.ta 1.5i 3i -.R -Jim Gettys -Cambridge Research Laboratory -Digital Equipment Corporation - -Robert W. Scheifler -Laboratory for Computer Science -Massachusetts Institute of Technology -.DE -.bp 1 +<preface id="acknowledgments">
+<title>Acknowledgments</title>
+<para>
+The design and implementation of the first 10 versions of X
+were primarily the work of three individuals: Robert Scheifler of the
+MIT Laboratory for Computer Science and Jim Gettys of Digital
+Equipment Corporation and Ron Newman of MIT, both at MIT
+Project Athena.
+X version 11, however, is the result of the efforts of
+dozens of individuals at almost as many locations and organizations.
+At the risk of offending some of the players by exclusion,
+we would like to acknowledge some of the people who deserve special credit
+and recognition for their work on Xlib.
+Our apologies to anyone inadvertently overlooked.
+</para>
+<sect1 id="release1">
+<title>
+Release 1
+</title>
+<para>
+Our thanks does to Ron Newman (MIT Project Athena),
+who contributed substantially to the
+design and implementation of the Version 11 Xlib interface.
+</para>
+<para>
+Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept
+it all together for us during the early releases.
+He handled literally thousands of requests from people everywhere
+and saved the sanity of at least one of us.
+His calm good cheer was a foundation on which we could build.
+</para>
+<para>
+Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned''
+to Project Athena at exactly the right moment to provide very capable
+and much-needed assistance during the alpha and beta releases.
+He was responsible for the successful integration of sources
+from multiple sites;
+we would not have had a release without him.
+</para>
+<para>
+Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX
+Documentation Group.
+With good humor and cheer,
+they took a rough draft and made it an infinitely better and more useful
+document.
+The work they have done will help many everywhere.
+We also would like to thank Hal Murray (Digital SRC) and
+Peter George (Digital VMS) who contributed much
+by proofreading the early drafts of this document.
+</para>
+<para>
+Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson,
+Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the
+library utilities implementation;
+to Hania Gajewska (Digital UEG-WSL) who,
+along with Ellis Cohen (CMU and Siemens),
+was instrumental in the semantic design of the window manager properties;
+and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol
+and provided the sample generic color frame buffer device-dependent code.
+</para>
+<para>
+The alpha and beta test participants deserve special recognition and thanks
+as well.
+It is significant
+that the bug reports (and many fixes) during alpha and beta test came almost
+exclusively from just a few of the alpha testers, mostly hardware vendors
+working on product implementations of X.
+The continued public
+contribution of vendors and universities is certainly to the benefit
+of the entire X community.
+</para>
+<para>
+Our special thanks must go to Sam Fuller, Vice-President of Corporate
+Research at Digital, who has remained committed to the widest public
+availability of X and who made it possible to greatly supplement MIT's
+resources with the Digital staff in order to make version 11 a reality.
+Many of the people mentioned here are part of the Western
+Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group
+and work for Smokey Wallace, who has been vital to the project's success.
+Others not mentioned here worked on the toolkit and are acknowledged
+in the X Toolkit documentation.
+</para>
+<para>
+Of course,
+we must particularly thank Paul Asente, formerly of Stanford University
+and now of Digital UEG-WSL, who wrote W, the predecessor to X,
+and Brian Reid, formerly of Stanford University and now of Digital WRL,
+who had much to do with W's design.
+</para>
+<para>
+Finally, our thanks goes to MIT, Digital Equipment Corporation,
+and IBM for providing the environment where it could happen.
+</para>
+</sect1>
+<sect1 id="release4">
+<title>
+Release 4
+</title>
+<para>
+Our thanks go to Jim Fulton (MIT X Consortium) for designing and
+specifying the new Xlib functions for Inter-Client Communication
+Conventions (<acronym>ICCCM</acronym>) support.
+</para>
+<para>
+We also thank Al Mento of Digital for his continued effort in
+maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium)
+for their much-appreciated efforts in reviewing the changes.
+</para>
+</sect1>
+<sect1 id="release5">
+<title>
+Release 5
+</title>
+<para>
+The principal authors of the Input Method facilities are
+Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard).
+The principal author of the rest of the internationalization facilities
+is Glenn Widener (Tektronix). Our thanks to them for keeping their
+sense of humor through a long and sometimes difficult design process.
+Although the words and much of the design are due to them, many others
+have contributed substantially to the design and implementation.
+Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition
+for their contributions. Other contributors were:
+Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP),
+Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital),
+Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu),
+Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM),
+Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu Kaiya (Fujitsu),
+Yuji Kamata (IBM),
+Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC),
+Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON),
+Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT),
+Nelson Ng (Sun),
+Takashi Nishimura (NTT America), Makato Nishino (IBM),
+Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T),
+Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital),
+Shoji Sugiyama (IBM), and Eiji Tosa (IBM).
+</para>
+<para>
+We are deeply indebted to Tatsuya Kato (NTT),
+Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT),
+and Li Yuhong (OMRON) for producing one of the first complete
+sample implementation of the internationalization facilities, and
+Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun),
+Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox),
+Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba),
+Makoto Wakamatsu (Sony Corporation) for producing the another complete
+sample implementation of the internationalization facilities.
+</para>
+<para>
+The principal authors (design and implementation) of the Xcms color
+management facilities are Al Tabayoyon (Tektronix)
+and Chuck Adams (Tektronix).
+Joann Taylor (Tektronix), Bob Toole (Tektronix),
+and Keith Packard (MIT X Consortium) also
+contributed significantly to the design. Others who contributed are:
+Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI),
+Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun),
+Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM),
+Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&T),
+and Richard Verberg (IBM).
+</para>
+<para>
+We also once again thank Al Mento of Digital for his work in formatting
+and reformatting text for this manual, and for producing man pages.
+Thanks also to Clive Feather (IXI) for proof-reading and finding a
+number of small errors.
+</para>
+</sect1>
+<sect1 id="release6">
+<title>
+Release 6
+</title>
+<para>
+Stephen Gildea (X Consortium) authored the threads support.
+Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially
+by testing the facilities and reporting bugs in a timely fashion.
+</para>
+<para>
+The principal authors of the internationalization facilities, including
+Input and Output Methods, are Hideki Hiura (SunSoft) and
+Shigeru Yamada (Fujitsu OSSI).
+Although the words and much of the design are due to them, many others
+have contributed substantially to the design and implementation.
+They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM),
+Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft),
+Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP),
+Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu),
+Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony),
+Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and
+Jinsoo Yoon (KAIST).
+</para>
+<para>
+The principal producers of the sample implementation of the
+internationalization facilities are:
+Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu),
+Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM),
+Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft),
+Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu),
+Franky Ling (Digital), Hiroyuki Miyamoto (Digital),
+Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu),
+Makoto Wakamatsu (Sony), Masaki Wakao (IBM),
+Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).
+</para>
+<para>
+The coordinators of the integration, testing, and release of this
+implementation of the internationalization facilities are
+Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).
+</para>
+<para>
+Others who have contributed to the architectural design or
+testing of the sample implementation of the
+internationalization facilities are:
+Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital),
+Hiroyuki Machida (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM),
+Yoshiyuki Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu),
+Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony),
+Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).
+</para>
+<para>
+<literallayout>
+Jim Gettys
+Cambridge Research Laboratory
+Digital Equipment Corporation
+
+Robert W. Scheifler
+Laboratory for Computer Science
+Massachusetts Institute of Technology
+</literallayout>
+</para>
+</sect1>
+</preface>
diff --git a/libX11/specs/libX11/glossary b/libX11/specs/libX11/glossary deleted file mode 100644 index a130928a6..000000000 --- a/libX11/specs/libX11/glossary +++ /dev/null @@ -1,1484 +0,0 @@ -\& -.sp 1 -.ce 1 -\s+1\fBGlossary\fP\s-1 -.sp 2 -.na -.LP -.XS -Glossary -.XE -.KS -\fBAccess control list\fP -.IN "Access control list" "" "@DEF@" -.IP -X maintains a list of hosts from which client programs can be run. -By default, -only programs on the local host and hosts specified in an initial list read -by the server can use the display. -This access control list can be changed by clients on the local host. -Some server implementations can also implement other authorization mechanisms -in addition to or in place of this mechanism. -The action of this mechanism can be conditional based on the authorization -protocol name and data received by the server at connection setup. -.KE -.LP -.KS -\fBActive grab\fP -.IN "Active grab" "" "@DEF@" -.IP -A grab is active when the pointer or keyboard is actually owned by the -single grabbing client. -.KE -.LP -.KS -\fBAncestors\fP -.IN "Ancestors" "" "@DEF@" -.IP -If W is an inferior of A, then A is an ancestor of W. -.KE -.LP -.KS -\fBAtom\fP -.IN "Atom" "" "@DEF@" -.IP -An atom is a unique ID corresponding to a string name. -Atoms are used to identify properties, types, and selections. -.KE -.LP -.KS -\fBBackground\fP -.IN "Background" "" "@DEF@" -.IP -An -.PN InputOutput -window can have a background, which is defined as a pixmap. -When regions of the window have their contents lost -or invalidated, -the server automatically tiles those regions with the background. -.KE -.LP -.KS -\fBBacking store\fP -.IN "Backing store" "" "@DEF@" -.IP -When a server maintains the contents of a window, -the pixels saved off-screen are known as a backing store. -.KE -.LP -.KS -\fBBase font name\fP -.IN "Base font name" "" "@DEF@" -.IP -A font name used to select a family of fonts whose members may be encoded -in various charsets. -The -.PN CharSetRegistry -and -.PN CharSetEncoding -fields of an XLFD name identify the charset of the font. -A base font name may be a full XLFD name, with all fourteen '-' delimiters, -or an abbreviated XLFD name containing only the first 12 fields of an XLFD name, -up to but not including -.PN CharSetRegistry , -with or without the thirteenth '-', or a non-XLFD name. -Any XLFD fields may contain wild cards. -.IP -When creating an -.PN XFontSet , -Xlib accepts from the client a list of one or more base font names -which select one or more font families. -They are combined with charset names obtained from the encoding of the locale -to load the fonts required to render text. -.KE -.LP -.KS -\fBBit gravity\fP -.IN "Bit" "gravity" "@DEF@" -.IP -When a window is resized, -the contents of the window are not necessarily discarded. -It is possible to request that the server relocate the previous contents -to some region of the window (though no guarantees are made). -This attraction of window contents for some location of -a window is known as bit gravity. -.KE -.LP -.KS -\fBBit plane\fP -.IN "Bit" "plane" "@DEF@" -.IP -When a pixmap or window is thought of as a stack of bitmaps, -each bitmap is called a bit plane or plane. -.KE -.LP -.KS -\fBBitmap\fP -.IN "Bitmap" "" "@DEF@" -.IP -A bitmap is a pixmap of depth one. -.KE -.LP -.KS -\fBBorder\fP -.IN "Border" "" "@DEF@" -.IP -An -.PN InputOutput -window can have a border of equal thickness on all four sides of the window. -The contents of the border are defined by a pixmap, -and the server automatically maintains the contents of the border. -Exposure events are never generated for border regions. -.KE -.LP -.KS -\fBButton grabbing\fP -.IN "Button" "grabbing" "@DEF@" -.IP -Buttons on the pointer can be passively grabbed by a client. -When the button is pressed, -the pointer is then actively grabbed by the client. -.KE -.LP -.KS -\fBByte order\fP -.IN "Byte" "order" "@DEF@" -.IP -For image (pixmap/bitmap) data, -the server defines the byte order, -and clients with different native byte ordering must swap bytes as -necessary. -For all other parts of the protocol, -the client defines the byte order, -and the server swaps bytes as necessary. -.KE -.LP -.KS -\fBCharacter\fP -.IN "Character" "" "@DEF@" -.IP -A member of a set of elements used for the organization, -control, or representation of text (ISO2022, as adapted by XPG3). -Note that in ISO2022 terms, a character is not bound to a coded value -until it is identified as part of a coded character set. -.KE -.LP -.KS -\fBCharacter glyph\fP -.IN "Character glyph" "" "@DEF@" -.IP -The abstract graphical symbol for a character. -Character glyphs may or may not map one-to-one to font glyphs, -and may be context-dependent, varying with the adjacent characters. -Multiple characters may map to a single character glyph. -.KE -.LP -.KS -\fBCharacter set\fP -.IN "Character set" "" "@DEF@" -.IP -A collection of characters. -.KE -.LP -.KS -\fBCharset\fP -.IN "Charset" "" "@DEF@" -.IP -An encoding with a uniform, state-independent mapping from characters -to codepoints. -A coded character set. -.IP -For display in X, -there can be a direct mapping from a charset to one font, -if the width of all characters in the charset is either one or two bytes. -A text string encoded in an encoding such as Shift-JIS cannot be passed -directly to the X server, because the text imaging requests accept only -single-width charsets (either 8 or 16 bits). -Charsets which meet these restrictions can serve as ``font charsets''. -Font charsets strictly speaking map font indices to font glyphs, -not characters to character glyphs. -.IP -Note that a single font charset is sometimes used as the encoding of a locale, -for example, ISO8859-1. -.KE -.LP -.KS -\fBChildren\fP -.IN "Children" "" "@DEF@" -.IP -The children of a window are its first-level subwindows. -.KE -.LP -.KS -\fBClass\fP -.IN "Class" "" "@DEF@" -.IP -Windows can be of different classes or types. -See the entries for -.PN InputOnly -and -.PN InputOutput -windows for further information about valid window types. -.KE -.LP -.KS -\fBClient\fP -.IN "Client" "" "@DEF@" -.IP -An application program connects to the window system server by some -interprocess communication (IPC) path, such as a TCP connection or a -shared memory buffer. -This program is referred to as a client of the window system server. -More precisely, -the client is the IPC path itself. -A program with multiple paths open to the server is viewed as -multiple clients by the protocol. -Resource lifetimes are controlled by -connection lifetimes, not by program lifetimes. -.KE -.LP -.KS -\fBClipping region\fP -.IN "Clipping region" "" "@DEF@" -.IP -In a graphics context, -a bitmap or list of rectangles can be specified -to restrict output to a particular region of the window. -The image defined by the bitmap or rectangles is called a clipping region. -.KE -.LP -.KS -\fBCoded character\fP -.IN "Coded character" "" "@DEF@" -.IP -A character bound to a codepoint. -.KE -.LP -.KS -\fBCoded character set\fP -.IN "Coded character set" "" "@DEF@" -.IP -A set of unambiguous rules that establishes a character set -and the one-to-one relationship between each character of the set -and its bit representation. -(ISO2022, as adapted by XPG3) -A definition of a one-to-one mapping of a set of characters to a set of -codepoints. -.KE -.LP -.KS -\fBCodepoint\fP -.IN "Codepoint" "" "@DEF@" -.IP -The coded representation of a single character in a coded character set. -.KE -.LP -.KS -\fBColormap\fP -.IN "Colormap" "" "@DEF@" -.IP -A colormap consists of a set of entries defining color values. -The colormap associated with a window is used to display the contents of -the window; each pixel value indexes the colormap to produce an RGB value -that drives the guns of a monitor. -Depending on hardware limitations, -one or more colormaps can be installed at one time so -that windows associated with those maps display with true colors. -.KE -.LP -.KS -\fBConnection\fP -.IN "Connection" "" "@DEF@" -.IP -The IPC path between the server and client program is known as a connection. -A client program typically (but not necessarily) has one -connection to the server over which requests and events are sent. -.KE -.LP -.KS -\fBContainment\fP -.IN "Containment" "" "@DEF@" -.IP -A window contains the pointer if the window is viewable and the -hotspot of the cursor is within a visible region of the window or a -visible region of one of its inferiors. -The border of the window is included as part of the window for containment. -The pointer is in a window if the window contains the pointer -but no inferior contains the pointer. -.KE -.LP -.KS -\fBCoordinate system\fP -.IN "Coordinate system" "" "@DEF@" -.IP -The coordinate system has X horizontal and Y vertical, -with the origin [0, 0] at the upper left. -Coordinates are integral and coincide with pixel centers. -Each window and pixmap has its own coordinate system. -For a window, -the origin is inside the border at the inside upper-left corner. -.KE -.LP -.KS -\fBCursor\fP -.IN "Cursor" "" "@DEF@" -.IP -A cursor is the visible shape of the pointer on a screen. -It consists of a hotspot, a source bitmap, a shape bitmap, -and a pair of colors. -The cursor defined for a window controls the visible -appearance when the pointer is in that window. -.KE -.LP -.KS -\fBDepth\fP -.IN "Depth" "" "@DEF@" -.IP -The depth of a window or pixmap is the number of bits per pixel it has. -The depth of a graphics context is the depth of the drawables it can be -used in conjunction with graphics output. -.KE -.LP -.KS -\fBDevice\fP -.IN "Device" "" "@DEF@" -.IP -Keyboards, mice, tablets, track-balls, button boxes, and so on are all -collectively known as input devices. -Pointers can have one or more buttons -(the most common number is three). -The core protocol only deals with two devices: the keyboard -and the pointer. -.KE -.LP -.KS -\fBDirectColor\fP -.IN "DirectColor" "" "@DEF@" -.IP -.PN DirectColor -is a class of colormap in which a pixel value is decomposed into three -separate subfields for indexing. -The first subfield indexes an array to produce red intensity values. -The second subfield indexes a second array to produce blue intensity values. -The third subfield indexes a third array to produce green intensity values. -The RGB (red, green, and blue) values in the colormap entry can be -changed dynamically. -.KE -.LP -.KS -\fBDisplay\fP -.IN "Display" "" "@DEF@" -.IP -A server, together with its screens and input devices, is called a display. -The Xlib -.PN Display -.IN "Display" "structure" -structure contains all information about the particular display and its screens -as well as the state that Xlib needs to communicate with the display over a -particular connection. -.KE -.LP -.KS -\fBDrawable\fP -.IN "Drawable" "" "@DEF@" -.IP -Both windows and pixmaps can be used as sources and destinations -in graphics operations. -These windows and pixmaps are collectively known as drawables. -However, an -.PN InputOnly -window cannot be used as a source or destination in a -graphics operation. -.KE -.LP -.KS -\fBEncoding\fP -.IN "Encoding" "" "@DEF@" -.IP -A set of unambiguous rules that establishes a character set -and a relationship between the characters and their representations. -The character set does not have to be fixed to a finite pre-defined set of -characters. -The representations do not have to be of uniform length. -Examples are an ISO2022 graphic set, a state-independent -or state-dependent combination of graphic sets, possibly including control -sets, and the X Compound Text encoding. -.IP -In X, encodings are identified by a string -which appears as: the -.PN CharSetRegistry -and -.PN CharSetEncoding -components of an XLFD -name; the name of a charset of the locale for which a font could not be -found; or an atom which identifies the encoding of a text property or -which names an encoding for a text selection target type. -Encoding names should be composed of characters from the X Portable -Character Set. -.KE -.LP -.KS -\fBEscapement\fP -.IN "Escapement" "" "@DEF@" -.IP -The escapement of a string is the distance in pixels in the -primary draw direction from the drawing origin to the origin of the next -character (that is, the one following the given string) to be drawn. -.KE -.LP -.KS -\fBEvent\fP -.IN "Event" "" "@DEF@" -.IP -Clients are informed of information asynchronously by means of events. -These events can be either asynchronously generated from devices or -generated as side effects of client requests. -Events are grouped into types. -The server never sends an event to a client unless the -client has specifically asked to be informed of that type of event. -However, clients can force events to be sent to other clients. -Events are typically reported relative to a window. -.KE -.LP -.KS -\fBEvent mask\fP -.IN "Event" "mask" "@DEF@" -.IP -Events are requested relative to a window. -The set of event types a client requests relative to a window is described -by using an event mask. -.KE -.LP -.KS -\fBEvent propagation\fP -.IN "Event" "propagation" "@DEF@" -.IP -Device-related events propagate from the source window to ancestor -windows until some client has expressed interest in handling that type -of event or until the event is discarded explicitly. -.KE -.LP -.KS -\fBEvent source\fP -.IN "Event" "source" "@DEF@" -.IP -The deepest viewable window that the pointer is in is called -the source of a device-related event. -.KE -.LP -.KS -\fBEvent synchronization\fP -.IN "Event" "synchronization" "@DEF@" -.IP -There are certain race conditions possible when demultiplexing device -events to clients (in particular, deciding where pointer and keyboard -events should be sent when in the middle of window management -operations). -The event synchronization mechanism allows synchronous processing of -device events. -.KE -.LP -.KS -\fBExposure event\fP -.IN "Event" "Exposure" "@DEF@" -.IP -Servers do not guarantee to preserve the contents of windows when -windows are obscured or reconfigured. -Exposure events are sent to clients to inform them when contents of regions -of windows have been lost. -.KE -.LP -.KS -\fBExtension\fP -.IN "Extension" "" "@DEF@" -.IP -Named extensions to the core protocol can be defined to extend the system. -Extensions to output requests, resources, and event types are all possible -and expected. -.KE -.LP -.KS -\fBFont\fP -.IN "Font" "" "@DEF@" -.IP -A font is an array of glyphs (typically characters). -The protocol does no translation or interpretation of character sets. -The client simply indicates values used to index the glyph array. -A font contains additional metric information to determine interglyph -and interline spacing. -.KE -.LP -.KS -\fBFont glyph\fP -.IN "Font glyph" "" "@DEF@" -.IP -The abstract graphical symbol for an index into a font. -.KE -.LP -.KS -\fBFrozen events\fP -.IN "Frozen events" "" "@DEF@" -.IP -Clients can freeze event processing during keyboard and pointer grabs. -.KE -.LP -.KS -\fBGC\fP -.IN "GC" "" "@DEF@" -.IP -GC is an abbreviation for graphics context. -See \fBGraphics context\fP. -.KE -.LP -.KS -\fBGlyph\fP -.IN "Glyph" "" "@DEF@" -.IP -An identified abstract graphical symbol independent of any actual image. -(ISO/IEC/DIS 9541-1) -An abstract visual representation of a graphic character, -not bound to a codepoint. -.KE -.LP -.KS -\fBGlyph image\fP -.IN "Glyph image" "" "@DEF@" -.IP -An image of a glyph, as obtained from a glyph representation displayed -on a presentation surface. -(ISO/IEC/DIS 9541-1) -.KE -.LP -.KS -\fBGrab\fP -.IN "Grab" "" "@DEF@" -.IP -Keyboard keys, the keyboard, pointer buttons, the pointer, -and the server can be grabbed for exclusive use by a client. -In general, -these facilities are not intended to be used by normal applications -but are intended for various input and window managers to implement various -styles of user interfaces. -.KE -.LP -.KS -\fBGraphics context\fP -.IN "Graphics context" "" "@DEF@" -.IP -Various information for graphics output is stored in a graphics -context (GC), such as foreground pixel, background -pixel, line width, clipping region, and so on. -A graphics context can only -be used with drawables that have the same root and the same depth as -the graphics context. -.KE -.LP -.KS -\fBGravity\fP -.IN "Gravity" "" "@DEF@" -.IP -The contents of windows and windows themselves have a gravity, -which determines how the contents move when a window is resized. -See \fBBit gravity\fP and \fBWindow gravity\fP. -.KE -.LP -.KS -\fBGrayScale\fP -.IN "GrayScale" "" "@DEF@" -.IP -.PN GrayScale -can be viewed as a degenerate case of -.PN PseudoColor , -in which the red, green, and blue values in any given colormap entry -are equal and thus, produce shades of gray. -The gray values can be changed dynamically. -.KE -.LP -.KS -\fBHost Portable Character Encoding\fP -.IN "Host Portable Character Encoding" "" "@DEF@" -.IP -The encoding of the X Portable Character Set on the host. -The encoding itself is not defined by this standard, -but the encoding must be the same in all locales supported by Xlib on the host. -If a string is said to be in the Host Portable Character Encoding, -then it only contains characters from the X Portable Character Set, -in the host encoding. -.KE -.LP -.KS -\fBHotspot\fP -.IN "Hotspot" "" "@DEF@" -.IP -A cursor has an associated hotspot, which defines the point in the -cursor corresponding to the coordinates reported for the pointer. -.KE -.LP -.KS -\fBIdentifier\fP -.IN "Identifier" "" "@DEF@" -.IP -An identifier is a unique value associated with a resource -that clients use to name that resource. -The identifier can be used over any connection to name the resource. -.KE -.LP -.KS -\fBInferiors\fP -.IN "Inferiors" "" "@DEF@" -.IP -The inferiors of a window are all of the subwindows nested below it: -the children, the children's children, and so on. -.KE -.LP -.KS -\fBInput focus\fP -.IN "Input" "focus" "@DEF@" -.IP -The input focus is usually a window defining the scope for processing -of keyboard input. -If a generated keyboard event usually would be reported to this window -or one of its inferiors, -the event is reported as usual. -Otherwise, the event is reported with respect to the focus window. -The input focus also can be set such that all keyboard events are discarded -and such that the focus window is dynamically taken to be the root window -of whatever screen the pointer is on at each keyboard event. -.KE -.LP -.KS -\fBInput manager\fP -.IN "Input" "manager" "@DEF@" -.IP -Control over keyboard input is typically provided by an input manager -client, which usually is part of a window manager. -.KE -.LP -.KS -\fBInputOnly window\fP -.IN "Window" "InputOnly" "@DEF@" -.IP -An -.PN InputOnly -window is a window that cannot be used for graphics requests. -.PN InputOnly -windows are invisible and are used to control such things as cursors, -input event generation, and grabbing. -.PN InputOnly -windows cannot have -.PN InputOutput -windows as inferiors. -.KE -.LP -.KS -\fBInputOutput window\fP -.IN "Window" "InputOutput" "@DEF@" -.IP -An -.PN InputOutput -window is the normal kind of window that is used for both input and output. -.PN InputOutput -windows can have both -.PN InputOutput -and -.PN InputOnly -windows as inferiors. -.KE -.LP -.KS -\fBInternationalization\fP -.IN "Internationalization" "" "@DEF@" -.IP -The process of making software adaptable to the requirements -of different native languages, local customs, and character string encodings. -Making a computer program adaptable to different locales -without program source modifications or recompilation. -.KE -.LP -.KS -\fBISO2022\fP -.IN "ISO2022" "" "@DEF@" -.IP -ISO standard for code extension techniques for 7-bit and 8-bit coded -character sets. -.KE -.LP -.KS -\fBKey grabbing\fP -.IN "Key" "grabbing" "@DEF@" -.IP -Keys on the keyboard can be passively grabbed by a client. -When the key is pressed, -the keyboard is then actively grabbed by the client. -.KE -.LP -.KS -\fBKeyboard grabbing\fP -.IN "Keyboard" "grabbing" "@DEF@" -.IP -A client can actively grab control of the keyboard, and key events -will be sent to that client rather than the client the events would -normally have been sent to. -.KE -.LP -.KS -\fBKeysym\fP -.IN "Keysym" "" "@DEF@" -.IP -An encoding of a symbol on a keycap on a keyboard. -.KE -.LP -.KS -\fBLatin-1\fP -.IN "Latin-1" "" "@DEF@" -.IP -The coded character set defined by the ISO8859-1 standard. -.KE -.LP -.KS -\fBLatin Portable Character Encoding\fP -.IN "Latin Portable Character Encoding" "" "@DEF@" -.IP -The encoding of the X Portable Character Set using the Latin-1 codepoints -plus ASCII control characters. -If a string is said to be in the Latin Portable Character Encoding, -then it only contains characters from the X Portable Character Set, -not all of Latin-1. -.KE -.LP -.KS -\fBLocale\fP -.IN "Locale" "" "@DEF@" -.IP -The international environment of a computer program defining the ``localized'' -behavior of that program at run-time. -This information can be established from one or more sets of localization data. -ANSI C defines locale-specific processing by C system library calls. -See ANSI C and the X/Open Portability Guide specifications for more details. -In this specification, on implementations that conform to the ANSI C library, -the ``current locale'' is the current setting of the LC_CTYPE -.PN setlocale -category. -Associated with each locale is a text encoding. When text is processed -in the context of a locale, the text must be in the encoding of the locale. -The current locale affects Xlib in its: -.RS -.IP \(bu 5 -Encoding and processing of input method text -.IP \(bu 5 -Encoding of resource files and values -.IP \(bu 5 -Encoding and imaging of text strings -.IP \(bu 5 -Encoding and decoding for inter-client text communication -.RE -.KE -.LP -.KS -\fBLocale name\fP -.IN "Locale name" "" "@DEF@" -.IP -The identifier used to select the desired locale for the host C library -and X library functions. -On ANSI C library compliant systems, -the locale argument to the -.PN setlocale -function. -.KE -.LP -.KS -\fBLocalization\fP -.IN "Localization" "" "@DEF@" -.IP -The process of establishing information within a computer system specific -to the operation of particular native languages, local customs -and coded character sets. -(XPG3) -.KE -.LP -.KS -\fBMapped\fP -.IN "Mapped window" "" "@DEF@" -.IP -A window is said to be mapped if a map call has been performed on it. -Unmapped windows and their inferiors are never viewable or visible. -.KE -.LP -.KS -\fBModifier keys\fP -.IN "Modifier keys" "" "@DEF@" -.IP -Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock, -ShiftLock, and similar keys are called modifier keys. -.KE -.LP -.KS -\fBMonochrome\fP -.IN "Monochrome" "" "@DEF@" -.IP -Monochrome is a special case of -.PN StaticGray -in which there are only two colormap entries. -.KE -.LP -.KS -\fBMultibyte\fP -.IN "Multibyte" "" "@DEF@" -.IP -A character whose codepoint is stored in more than one byte; -any encoding which can contain multibyte characters; -text in a multibyte encoding. -The ``char *'' null-terminated string datatype in ANSI C. -Note that references in this document to multibyte strings -imply only that the strings \fImay\fP contain multibyte characters. -.KE -.LP -.KS -\fBObscure\fP -.IN "Obscure" "" "@DEF@" -.IP -A window is obscured if some other window obscures it. -A window can be partially obscured and so still have visible regions. -Window A obscures window B if both are viewable -.PN InputOutput -windows, if A is higher in the global stacking order, -and if the rectangle defined by the outside -edges of A intersects the rectangle defined by the outside edges of B. -Note the distinction between obscures and occludes. -Also note that window borders are included in the calculation. -.KE -.LP -.KS -\fBOcclude\fP -.IN "Occlude" "" "@DEF@" -.IP -A window is occluded if some other window occludes it. -Window A occludes window B if both are mapped, -if A is higher in the global stacking order, -and if the rectangle defined by the outside edges of A intersects the rectangle defined -by the outside edges of B. -Note the distinction between occludes and obscures. -Also note that window borders are included in the calculation -and that -.PN InputOnly -windows never obscure other windows but can occlude other windows. -.KE -.LP -.KS -\fBPadding\fP -.IN "Padding" "" "@DEF@" -.IP -Some padding bytes are inserted in the data stream to maintain -alignment of the protocol requests on natural boundaries. -This increases ease of portability to some machine architectures. -.KE -.LP -.KS -\fBParent window\fP -.IN "Window" "parent" "@DEF@" -.IP -If C is a child of P, then P is the parent of C. -.KE -.LP -.KS -\fBPassive grab\fP -.IN "Passive grab" "" "@DEF@" -.IP -Grabbing a key or button is a passive grab. -The grab activates when the key or button is actually pressed. -.KE -.LP -.KS -\fBPixel value\fP -.IN "Pixel value" "" "@DEF@" -.IP -A pixel is an N-bit value, -where N is the number of bit planes used in a particular window or pixmap -(that is, is the depth of the window or pixmap). -A pixel in a window indexes a colormap to derive an actual color to be -displayed. -.KE -.LP -.KS -\fBPixmap\fP -.IN "Pixmap" "" "@DEF@" -.EQ -delim %% -.EN -.IP -A pixmap is a three-dimensional array of bits. -A pixmap is normally thought of as a two-dimensional array of pixels, -where each pixel can be a value from 0 to %2 sup N %\-1, -and where N is the depth (z axis) of the pixmap. -A pixmap can also be thought of as a stack of N bitmaps. -A pixmap can only be used on the screen that it was created in. -.KE -.LP -.KS -\fBPlane\fP -.IN "Plane" "" "@DEF@" -.IP -When a pixmap or window is thought of as a stack of bitmaps, each -bitmap is called a plane or bit plane. -.KE -.LP -.KS -\fBPlane mask\fP -.IN "Plane" "mask" "@DEF@" -.IP -Graphics operations can be restricted to only affect a subset of bit -planes of a destination. -A plane mask is a bit mask describing which planes are to be modified. -The plane mask is stored in a graphics context. -.KE -.LP -.KS -\fBPointer\fP -.IN "Pointer" "" "@DEF@" -.IP -The pointer is the pointing device currently attached to the cursor -and tracked on the screens. -.KE -.LP -.KS -\fBPointer grabbing\fP -.IN "Pointer" "grabbing" "@DEF@" -.IP -A client can actively grab control of the pointer. -Then button and motion events will be sent to that client -rather than the client the events would normally have been sent to. -.KE -.LP -.KS -\fBPointing device\fP -.IN "Pointing device" "" "@DEF@" -.IP -A pointing device is typically a mouse, tablet, or some other -device with effective dimensional motion. -The core protocol defines only one visible cursor, -which tracks whatever pointing device is attached as the pointer. -.KE -.LP -.KS -\fBPOSIX\fP -.IN "POSIX" "" "@DEF@" -.IP -Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1). -.KE -.LP -.KS -\fBPOSIX Portable Filename Character Set\fP -.IN "POSIX Portable Filename Character Set" "" "@DEF@" -.IP -The set of 65 characters which can be used in naming files on a POSIX-compliant -host that are correctly processed in all locales. -The set is: -.IP -.Ds 0 -a..z A..Z 0..9 ._- -.De -.KE -.LP -.KS -\fBProperty\fP -.IN "Property" "" "@DEF@" -.IP -Windows can have associated properties that consist of a name, a type, -a data format, and some data. -The protocol places no interpretation on properties. -They are intended as a general-purpose naming mechanism for clients. -For example, clients might use properties to share information such as resize -hints, program names, and icon formats with a window manager. -.KE -.LP -.KS -\fBProperty list\fP -.IN "Property list" "" "@DEF@" -.IP -The property list of a window is the list of properties that have -been defined for the window. -.KE -.LP -.KS -\fBPseudoColor\fP -.IN "PseudoColor" "" "@DEF@" -.IP -.PN PseudoColor -is a class of colormap in which a pixel value indexes the colormap entry to -produce an independent RGB value; -that is, the colormap is viewed as an array of triples (RGB values). -The RGB values can be changed dynamically. -.KE -.LP -.KS -\fBRectangle\fP -.IN "Rectangle" "" "@DEF@" -.IP -A rectangle specified by [x,y,w,h] has an infinitely thin -outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h]. -When a rectangle is filled, -the lower-right edges are not drawn. -For example, -if w=h=0, -nothing would be drawn. -For w=h=1, -a single pixel would be drawn. -.KE -.LP -.KS -\fBRedirecting control\fP -.IN "Redirecting control" "" "@DEF@" -.IP -Window managers (or client programs) may enforce window layout -policy in various ways. -When a client attempts to change the size or position of a window, -the operation may be redirected to a specified client -rather than the operation actually being performed. -.KE -.LP -.KS -\fBReply\fP -.IN "Reply" "" "@DEF@" -.IP -Information requested by a client program using the X protocol -is sent back to the client with a reply. -Both events and replies are multiplexed on the same connection. -Most requests do not generate replies, -but some requests generate multiple replies. -.KE -.LP -.KS -\fBRequest\fP -.IN "Request" "" "@DEF@" -.IP -A command to the server is called a request. -It is a single block of data sent over a connection. -.KE -.LP -.KS -\fBResource\fP -.IN "Resource" "" "@DEF@" -.IP -Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are -known as resources. -They all have unique identifiers associated with them for naming purposes. -The lifetime of a resource usually is bounded by the lifetime of the -connection over which the resource was created. -.KE -.LP -.KS -\fBRGB values\fP -.IN "RGB values" "" "@DEF@" -.IP -RGB values are the red, green, and blue intensity values that are used -to define a color. -These values are always represented as 16-bit, unsigned numbers, with 0 -the minimum intensity and 65535 the maximum intensity. -The X server scales these values to match the display hardware. -.KE -.LP -.KS -\fBRoot\fP -.IN "Root" "" "@DEF@" -.IP -The root of a pixmap or graphics context is the same as the root -of whatever drawable was used when the pixmap or GC was created. -The root of a window is the root window under which the window was created. -.KE -.LP -.KS -\fBRoot window\fP -.IN "Window" "root" "@DEF@" -.IP -Each screen has a root window covering it. -The root window cannot be reconfigured or unmapped, -but otherwise it acts as a full-fledged window. -A root window has no parent. -.KE -.LP -.KS -\fBSave set\fP -.IN "Save set" "" "@DEF@" -.IP -The save set of a client is a list of other clients' windows that, -if they are inferiors of one of the client's windows at connection -close, should not be destroyed and that should be remapped -if currently unmapped. -Save sets are typically used by window managers to avoid -lost windows if the manager should terminate abnormally. -.KE -.LP -.KS -\fBScanline\fP -.IN "Scanline" "" "@DEF@" -.IP -A scanline is a list of pixel or bit values viewed as a horizontal -row (all values having the same y coordinate) of an image, with the -values ordered by increasing the x coordinate. -.KE -.LP -.KS -\fBScanline order\fP -.IN "Scanline" "order" "@DEF@" -.IP -An image represented in scanline order contains scanlines ordered by -increasing the y coordinate. -.KE -.LP -.KS -\fBScreen\fP -.IN "Screen" "" "@DEF@" -.IP -A server can provide several independent screens, -which typically have physically independent monitors. -This would be the expected configuration when there is only a single keyboard -and pointer shared among the screens. -A -.PN Screen -.IN "Screen" "structure" -structure contains the information about that screen -and is linked to the -.PN Display -.IN "Display" "structure" -structure. -.KE -.LP -.KS -\fBSelection\fP -.IN "Selection" "" "@DEF@" -.IP -A selection can be thought of as an indirect property with dynamic -type. -That is, rather than having the property stored in the X server, -it is maintained by some client (the owner). -A selection is global and is thought of as belonging to the user -and being maintained by clients, -rather than being private to a particular window subhierarchy -or a particular set of clients. -When a client asks for the contents of -a selection, it specifies a selection target type, -which can be used to control the transmitted representation of the contents. -For example, if the selection is ``the last thing the user clicked on,'' -and that is currently an image, then the target type might specify -whether the contents of the image should be sent in XY format or -Z format. -.IP -The target type can also be used to control the class of -contents transmitted; for example, -asking for the ``looks'' (fonts, line -spacing, indentation, and so forth) of a paragraph selection, rather than the -text of the paragraph. -The target type can also be used for other -purposes. -The protocol does not constrain the semantics. -.KE -.LP -.KS -\fBServer\fP -.IN "Server" "" "@DEF@" -.IP -The server, which is also referred to as the X server, -provides the basic windowing mechanism. -It handles IPC connections from clients, -multiplexes graphics requests onto the screens, -and demultiplexes input back to the appropriate clients. -.KE -.LP -.KS -\fBServer grabbing\fP -.IN "Server" "grabbing" "@DEF@" -.IP -The server can be grabbed by a single client for exclusive use. -This prevents processing of any requests from other client connections until -the grab is completed. -This is typically only a transient state for such things as rubber-banding, -pop-up menus, or executing requests indivisibly. -.KE -.LP -.KS -\fBShift sequence\fP -.IN "Shift sequence" "" "@DEF@" -.IP -ISO2022 defines control characters and escape sequences -which temporarily (single shift) or permanently (locking shift) cause a -different character set to be in effect (``invoking'' a character set). -.KE -.LP -.KS -\fBSibling\fP -.IN "Sibling" "" "@DEF@" -.IP -Children of the same parent window are known as sibling windows. -.KE -.LP -.KS -\fBStacking order\fP -.IN "Stacking order" "" "@DEF@" -.IP -Sibling windows, similar to sheets of paper on a desk, -can stack on top of each other. -Windows above both obscure and occlude lower windows. -The relationship between sibling windows is known as the stacking order. -.KE -.LP -.KS -\fBState-dependent encoding\fP -.IN "State-dependent encoding" "" "@DEF@" -.IP -An encoding in which an invocation of a charset can apply to multiple -characters in sequence. -A state-dependent encoding begins in an ``initial state'' -and enters other ``shift states'' when specific ``shift sequences'' -are encountered in the byte sequence. -In ISO2022 terms, -this means use of locking shifts, not single shifts. -.KE -.LP -.KS -\fBState-independent encoding\fP -.IN "State-independent encoding" "" "@DEF@" -.IP -Any encoding in which the invocations of the charsets are fixed, -or span only a single character. -In ISO2022 terms, -this means use of at most single shifts, not locking shifts. -.KE -.LP -.KS -\fBStaticColor\fP -.IN "StaticColor" "" "@DEF@" -.IP -.PN StaticColor -can be viewed as a degenerate case of -.PN PseudoColor -in which the RGB values are predefined and read-only. -.KE -.LP -.KS -\fBStaticGray\fP -.IN "StaticGray" "" "@DEF@" -.IP -.PN StaticGray -can be viewed as a degenerate case of -.PN GrayScale -in which the gray values are predefined and read-only. -The values are typically linear or near-linear increasing ramps. -.KE -.LP -.KS -\fBStatus\fP -.IN "Status" "" "@DEF@" -.IP -Many Xlib functions return a success status. -If the function does not succeed, -however, its arguments are not disturbed. -.KE -.LP -.KS -\fBStipple\fP -.IN "Stipple" "" "@DEF@" -.IP -A stipple pattern is a bitmap that is used to tile a region to serve -as an additional clip mask for a fill operation with the foreground -color. -.KE -.KS -.LP -.KS -\fBSTRING encoding\fP -.IN "STRING encoding" "" "@DEF@" -.IP -Latin-1, plus tab and newline. -.KE -.LP -\fBString Equivalence\fP -.IN "String Equivalence" "" "@DEF@" -.IP -Two ISO Latin-1 STRING8 values are considered equal if they are the same -length and if corresponding bytes are either equal or are equivalent as -follows: decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are -pairwise equivalent to decimal values 97 to 122 inclusive -(characters ``a'' to ``z''), decimal values 192 to 214 inclusive -(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal -values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''), -and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'') -are pairwise equivalent to decimal values 246 to 254 inclusive -(characters ``o oblique'' to ``thorn''). -.KE -.LP -.KS -\fBTile\fP -.IN "Tile" "" "@DEF@" -.IP -A pixmap can be replicated in two dimensions to tile a region. -The pixmap itself is also known as a tile. -.KE -.LP -.KS -\fBTimestamp\fP -.IN "Timestamp" "" "@DEF@" -.IP -A timestamp is a time value expressed in milliseconds. -It is typically the time since the last server reset. -Timestamp values wrap around (after about 49.7 days). -The server, given its current time is represented by timestamp T, -always interprets timestamps from clients by treating half -of the timestamp space as being earlier in time than T -and half of the timestamp space as being later in time than T. -One timestamp value, represented by the constant -.PN CurrentTime , -is never generated by the server. -This value is reserved for use in requests to represent the current server time. -.KE -.LP -.KS -\fBTrueColor\fP -.IN "TrueColor" "" "@DEF@" -.IP -.PN TrueColor -can be viewed as a degenerate case of -.PN DirectColor -in which the subfields in the pixel value directly encode the corresponding RGB -values. -That is, the colormap has predefined read-only RGB values. -The values are typically linear or near-linear increasing ramps. -.KE -.LP -.KS -\fBType\fP -.IN "Type" "" "@DEF@" -.IP -A type is an arbitrary atom used to identify the interpretation of property -data. -Types are completely uninterpreted by the server. -They are solely for the benefit of clients. -X predefines type atoms for many frequently used types, -and clients also can define new types. -.KE -.LP -.KS -\fBViewable\fP -.IN "Viewable" "" "@DEF@" -.IP -A window is viewable if it and all of its ancestors are mapped. -This does not imply that any portion of the window is actually visible. -Graphics requests can be performed on a window when it is not -viewable, but output will not be retained unless the server is maintaining -backing store. -.KE -.LP -.KS -\fBVisible\fP -.IN "Visible" "" "@DEF@" -.IP -A region of a window is visible if someone looking at the screen can -actually see it; that is, the window is viewable and the region is not occluded -by any other window. -.KE -.LP -.KS -\fBWhitespace\fP -.IN "Whitespace" "" "@DEF@" -.IP -Any spacing character. -On implementations that conform to the ANSI C library, -whitespace is any character for which -.PN isspace -returns true. -.KE -.LP -.KS -\fBWindow gravity\fP -.IN "Window" "gravity" "@DEF@" -.IP -When windows are resized, -subwindows may be repositioned automatically relative to some position in the -window. -This attraction of a subwindow to some part of its parent is known -as window gravity. -.KE -.LP -.KS -\fBWindow manager\fP -.IN "Window" "manager" "@DEF@" -.IP -Manipulation of windows on the screen and much of the user interface -(policy) is typically provided by a window manager client. -.KE -.LP -.KS -\fBX Portable Character Set\fP -.IN "X Portable Character Set" "" "@DEF@" -.IP -A basic set of 97 characters which are assumed to exist in all -locales supported by Xlib. This set contains the following characters: -.IP -.Ds 0 -.EQ -delim DD -.EN -a..z A..Z 0..9 -!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ -<space>, <tab>, and <newline> -.EQ -delim %% -.EN -.De -.IP -This is the left/lower half (also called the G0 set) -of the graphic character set of ISO8859-1 plus <space>, <tab>, and <newline>. -It is also the set of graphic characters in 7-bit ASCII plus the same -three control characters. -The actual encoding of these characters on the host is system dependent; -see the Host Portable Character Encoding. -.KE -.LP -.KS -\fBXLFD\fP -.IN "XLFD" "" "@DEF@" -.IP -The X Logical Font Description Conventions that define a standard syntax -for structured font names. -.KE -.LP -.KS -\fBXY format\fP -.IN "XY format" "" "@DEF@" -.IP -The data for a pixmap is said to be in XY format if it is organized as -a set of bitmaps representing individual bit planes with the planes -appearing from most-significant to least-significant bit order. -.KE -.LP -.KS -\fBZ format\fP -.IN "Z format" "" "@DEF@" -.IP -The data for a pixmap is said to be in Z format if it is organized as -a set of pixel values in scanline order. -.KE -.LP -\fBReferences\fP -.LP -ANSI Programming Language - C: ANSI X3.159-1989, December 14, 1989. -.LP -Draft Proposed Multibyte Extension of ANSI C, Draft 1.1, November 30, -1989, SC22/C WG/SWG IPSJ/ITSCJ Japan. -.LP -ISO2022: Information processing - ISO 7-bit and 8-bit coded character -sets - Code extension techniques. -.LP -ISO8859-1: Information processing - 8-bit single-byte coded graphic -character sets - Part 1: Latin alphabet No. 1. -.LP -POSIX: Information Technology - Portable Operating System Interface (POSIX) - -Part 1: System Application Program Interface (API) [C Language], -ISO/IEC 9945-1. -.LP -Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information -Interchange - Part 1: Architecture. -.LP -X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company, -Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8. -(See especially Volume 3: XSI Supplementary Definitions.) -.bp diff --git a/libX11/specs/libX11/glossary.xml b/libX11/specs/libX11/glossary.xml new file mode 100644 index 000000000..eda236875 --- /dev/null +++ b/libX11/specs/libX11/glossary.xml @@ -0,0 +1,1901 @@ +<glossary id='glossary'>
+<title>Glossary</title>
+<glossentry>
+ <glossterm>Access control list</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Access control list</primary></indexterm>
+ <para>
+X maintains a list of hosts from which client programs can be run.
+By default,
+only programs on the local host and hosts specified in an initial list read
+by the server can use the display.
+This access control list can be changed by clients on the local host.
+Some server implementations can also implement other authorization mechanisms
+in addition to or in place of this mechanism.
+The action of this mechanism can be conditional based on the authorization
+protocol name and data received by the server at connection setup.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Active grab</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>
+ <para>
+A grab is active when the pointer or keyboard is actually owned by the
+single grabbing client.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Ancestors</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Ancestors</primary></indexterm>
+ <para>
+If W is an inferior of A, then A is an ancestor of W.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Atom</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Atom</primary></indexterm>
+ <para>
+An atom is a unique ID corresponding to a string name.
+Atoms are used to identify properties, types, and selections.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Background</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Background</primary></indexterm>
+ <para>
+An
+<function>InputOutput</function>
+window can have a background, which is defined as a pixmap.
+When regions of the window have their contents lost
+or invalidated,
+the server automatically tiles those regions with the background.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Backing store</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Backing store</primary></indexterm>
+ <para>
+When a server maintains the contents of a window,
+the pixels saved off-screen are known as a backing store.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Base font name</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Base font name</primary></indexterm>
+ <para>
+A font name used to select a family of fonts whose members may be encoded
+in various charsets.
+The
+<function>CharSetRegistry</function>
+and
+<function>CharSetEncoding</function>
+fields of an <acronym>XLFD</acronym> name identify the charset of the font.
+A base font name may be a full <acronym>XLFD</acronym> name, with all fourteen '-' delimiters,
+or an abbreviated <acronym>XLFD</acronym> name containing only the first 12 fields of an <acronym>XLFD</acronym> name,
+up to but not including
+<function>CharSetRegistry</function>,
+with or without the thirteenth '-', or a non-<acronym>XLFD</acronym> name.
+Any <acronym>XLFD</acronym> fields may contain wild cards.
+</para>
+ <para>
+When creating an
+<function>XFontSet</function>,
+Xlib accepts from the client a list of one or more base font names
+which select one or more font families.
+They are combined with charset names obtained from the encoding of the locale
+to load the fonts required to render text.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Bit gravity</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Bit</primary><secondary>gravity</secondary></indexterm>
+ <para>
+When a window is resized,
+the contents of the window are not necessarily discarded.
+It is possible to request that the server relocate the previous contents
+to some region of the window (though no guarantees are made).
+This attraction of window contents for some location of
+a window is known as bit gravity.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Bit plane</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Bit</primary><secondary>plane</secondary></indexterm>
+ <para>
+When a pixmap or window is thought of as a stack of bitmaps,
+each bitmap is called a bit plane or plane.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Bitmap</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Bitmap</primary></indexterm>
+ <para>
+A bitmap is a pixmap of depth one.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Border</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Border</primary></indexterm>
+ <para>
+An
+<function>InputOutput</function>
+window can have a border of equal thickness on all four sides of the window.
+The contents of the border are defined by a pixmap,
+and the server automatically maintains the contents of the border.
+Exposure events are never generated for border regions.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Button grabbing</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Button</primary><secondary>grabbing</secondary></indexterm>
+ <para>
+Buttons on the pointer can be passively grabbed by a client.
+When the button is pressed,
+the pointer is then actively grabbed by the client.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Byte order</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Byte</primary><secondary>order</secondary></indexterm>
+ <para>
+For image (pixmap/bitmap) data,
+the server defines the byte order,
+and clients with different native byte ordering must swap bytes as
+necessary.
+For all other parts of the protocol,
+the client defines the byte order,
+and the server swaps bytes as necessary.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Character</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Character</primary></indexterm>
+ <para>
+A member of a set of elements used for the organization,
+control, or representation of text (ISO2022, as adapted by XPG3).
+Note that in ISO2022 terms, a character is not bound to a coded value
+until it is identified as part of a coded character set.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Character glyph</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Character glyph</primary></indexterm>
+ <para>
+The abstract graphical symbol for a character.
+Character glyphs may or may not map one-to-one to font glyphs,
+and may be context-dependent, varying with the adjacent characters.
+Multiple characters may map to a single character glyph.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Character set</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Character set</primary></indexterm>
+ <para>
+A collection of characters.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Charset</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Charset</primary></indexterm>
+ <para>
+An encoding with a uniform, state-independent mapping from characters
+to codepoints.
+A coded character set.
+</para>
+ <para>
+For display in X,
+there can be a direct mapping from a charset to one font,
+if the width of all characters in the charset is either one or two bytes.
+A text string encoded in an encoding such as Shift-JIS cannot be passed
+directly to the X server, because the text imaging requests accept only
+single-width charsets (either 8 or 16 bits).
+Charsets which meet these restrictions can serve as ``font charsets''.
+Font charsets strictly speaking map font indices to font glyphs,
+not characters to character glyphs.
+</para>
+ <para>
+Note that a single font charset is sometimes used as the encoding of a locale,
+for example, ISO8859-1.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Children</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Children</primary></indexterm>
+ <para>
+The children of a window are its first-level subwindows.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Class</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Class</primary></indexterm>
+ <para>
+Windows can be of different classes or types.
+See the entries for
+<function>InputOnly</function>
+and
+<function>InputOutput</function>
+windows for further information about valid window types.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Client</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Client</primary></indexterm>
+ <para>
+An application program connects to the window system server by some
+interprocess communication (<acronym>IPC</acronym>) path, such as a <acronym>TCP</acronym> connection or a
+shared memory buffer.
+This program is referred to as a client of the window system server.
+More precisely,
+the client is the <acronym>IPC</acronym> path itself.
+A program with multiple paths open to the server is viewed as
+multiple clients by the protocol.
+Resource lifetimes are controlled by
+connection lifetimes, not by program lifetimes.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Clipping region</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Clipping region</primary></indexterm>
+ <para>
+In a graphics context,
+a bitmap or list of rectangles can be specified
+to restrict output to a particular region of the window.
+The image defined by the bitmap or rectangles is called a clipping region.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Coded character</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Coded character</primary></indexterm>
+ <para>
+A character bound to a codepoint.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Coded character set</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Coded character set</primary></indexterm>
+ <para>
+A set of unambiguous rules that establishes a character set
+and the one-to-one relationship between each character of the set
+and its bit representation.
+(ISO2022, as adapted by XPG3)
+A definition of a one-to-one mapping of a set of characters to a set of
+codepoints.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Codepoint</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Codepoint</primary></indexterm>
+ <para>
+The coded representation of a single character in a coded character set.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Colormap</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Colormap</primary></indexterm>
+ <para>
+A colormap consists of a set of entries defining color values.
+The colormap associated with a window is used to display the contents of
+the window; each pixel value indexes the colormap to produce an <acronym>RGB</acronym> value
+that drives the guns of a monitor.
+Depending on hardware limitations,
+one or more colormaps can be installed at one time so
+that windows associated with those maps display with true colors.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Connection</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Connection</primary></indexterm>
+ <para>
+The <acronym>IPC</acronym> path between the server and client program is known as a connection.
+A client program typically (but not necessarily) has one
+connection to the server over which requests and events are sent.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Containment</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Containment</primary></indexterm>
+ <para>
+A window contains the pointer if the window is viewable and the
+hotspot of the cursor is within a visible region of the window or a
+visible region of one of its inferiors.
+The border of the window is included as part of the window for containment.
+The pointer is in a window if the window contains the pointer
+but no inferior contains the pointer.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Coordinate system</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Coordinate system</primary></indexterm>
+ <para>
+The coordinate system has X horizontal and Y vertical,
+with the origin [0, 0] at the upper left.
+Coordinates are integral and coincide with pixel centers.
+Each window and pixmap has its own coordinate system.
+For a window,
+the origin is inside the border at the inside upper-left corner.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Cursor</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Cursor</primary></indexterm>
+ <para>
+A cursor is the visible shape of the pointer on a screen.
+It consists of a hotspot, a source bitmap, a shape bitmap,
+and a pair of colors.
+The cursor defined for a window controls the visible
+appearance when the pointer is in that window.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Depth</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Depth</primary></indexterm>
+ <para>
+The depth of a window or pixmap is the number of bits per pixel it has.
+The depth of a graphics context is the depth of the drawables it can be
+used in conjunction with graphics output.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Device</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Device</primary></indexterm>
+ <para>
+Keyboards, mice, tablets, track-balls, button boxes, and so on are all
+collectively known as input devices.
+Pointers can have one or more buttons
+(the most common number is three).
+The core protocol only deals with two devices: the keyboard
+and the pointer.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>DirectColor</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>DirectColor</primary></indexterm>
+ <para>
+<function>DirectColor</function>
+is a class of colormap in which a pixel value is decomposed into three
+separate subfields for indexing.
+The first subfield indexes an array to produce red intensity values.
+The second subfield indexes a second array to produce blue intensity values.
+The third subfield indexes a third array to produce green intensity values.
+The <acronym>RGB</acronym> (red, green, and blue) values in the colormap entry can be
+changed dynamically.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Display</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Display</primary></indexterm>
+ <para>
+A server, together with its screens and input devices, is called a display.
+The Xlib
+<function>Display</function>
+<indexterm><primary>Display</primary><secondary>structure</secondary></indexterm>
+structure contains all information about the particular display and its screens
+as well as the state that Xlib needs to communicate with the display over a
+particular connection.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Drawable</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Drawable</primary></indexterm>
+ <para>
+Both windows and pixmaps can be used as sources and destinations
+in graphics operations.
+These windows and pixmaps are collectively known as drawables.
+However, an
+<function>InputOnly </function>
+window cannot be used as a source or destination in a
+graphics operation.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Encoding</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Encoding</primary></indexterm>
+ <para>
+A set of unambiguous rules that establishes a character set
+and a relationship between the characters and their representations.
+The character set does not have to be fixed to a finite pre-defined set of
+characters.
+The representations do not have to be of uniform length.
+Examples are an ISO2022 graphic set, a state-independent
+or state-dependent combination of graphic sets, possibly including control
+sets, and the X Compound Text encoding.
+</para>
+ <para>
+In X, encodings are identified by a string
+which appears as: the
+<function>CharSetRegistry</function>
+and
+<function>CharSetEncoding</function>
+components of an <acronym>XLFD</acronym>
+name; the name of a charset of the locale for which a font could not be
+found; or an atom which identifies the encoding of a text property or
+which names an encoding for a text selection target type.
+Encoding names should be composed of characters from the X Portable
+Character Set.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Escapement</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Escapement</primary></indexterm>
+ <para>
+The escapement of a string is the distance in pixels in the
+primary draw direction from the drawing origin to the origin of the next
+character (that is, the one following the given string) to be drawn.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Event</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Event</primary></indexterm>
+ <para>
+Clients are informed of information asynchronously by means of events.
+These events can be either asynchronously generated from devices or
+generated as side effects of client requests.
+Events are grouped into types.
+The server never sends an event to a client unless the
+client has specifically asked to be informed of that type of event.
+However, clients can force events to be sent to other clients.
+Events are typically reported relative to a window.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Event mask</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Event</primary><secondary>mask</secondary></indexterm>
+ <para>
+Events are requested relative to a window.
+The set of event types a client requests relative to a window is described
+by using an event mask.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Event propagation</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Event</primary><secondary>propagation</secondary></indexterm>
+ <para>
+Device-related events propagate from the source window to ancestor
+windows until some client has expressed interest in handling that type
+of event or until the event is discarded explicitly.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Event source</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Event</primary><secondary>source</secondary></indexterm>
+ <para>
+The deepest viewable window that the pointer is in is called
+the source of a device-related event.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Event synchronization</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Event</primary><secondary>synchronization</secondary></indexterm>
+ <para>
+There are certain race conditions possible when demultiplexing device
+events to clients (in particular, deciding where pointer and keyboard
+events should be sent when in the middle of window management
+operations).
+The event synchronization mechanism allows synchronous processing of
+device events.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Exposure event</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Event</primary><secondary>Exposure</secondary></indexterm>
+ <para>
+Servers do not guarantee to preserve the contents of windows when
+windows are obscured or reconfigured.
+Exposure events are sent to clients to inform them when contents of regions
+of windows have been lost.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Extension</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Extension</primary></indexterm>
+ <para>
+Named extensions to the core protocol can be defined to extend the system.
+Extensions to output requests, resources, and event types are all possible
+and expected.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Font</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Font</primary></indexterm>
+ <para>
+A font is an array of glyphs (typically characters).
+The protocol does no translation or interpretation of character sets.
+The client simply indicates values used to index the glyph array.
+A font contains additional metric information to determine interglyph
+and interline spacing.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Font glyph</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Font glyph</primary></indexterm>
+ <para>
+The abstract graphical symbol for an index into a font.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Frozen events</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Frozen events</primary></indexterm>
+ <para>
+Clients can freeze event processing during keyboard and pointer grabs.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>GC</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>GC</primary></indexterm>
+ <para>
+GC is an abbreviation for graphics context.
+See <function>Graphics context</function>.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Glyph</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Glyph</primary></indexterm>
+ <para>
+An identified abstract graphical symbol independent of any actual image.
+(ISO/IEC/DIS 9541-1)
+An abstract visual representation of a graphic character,
+not bound to a codepoint.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Glyph image</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Glyph image</primary></indexterm>
+ <para>
+An image of a glyph, as obtained from a glyph representation displayed
+on a presentation surface.
+(ISO/IEC/DIS 9541-1)
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Grab</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Grab</primary></indexterm>
+ <para>
+Keyboard keys, the keyboard, pointer buttons, the pointer,
+and the server can be grabbed for exclusive use by a client.
+In general,
+these facilities are not intended to be used by normal applications
+but are intended for various input and window managers to implement various
+styles of user interfaces.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Graphics context</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Graphics context</primary></indexterm>
+ <para>
+Various information for graphics output is stored in a graphics
+context (GC), such as foreground pixel, background
+pixel, line width, clipping region, and so on.
+A graphics context can only
+be used with drawables that have the same root and the same depth as
+the graphics context.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Gravity</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Gravity</primary></indexterm>
+ <para>
+The contents of windows and windows themselves have a gravity,
+which determines how the contents move when a window is resized.
+See <function>Bit gravity</function> and <function>Window gravity</function>.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>GrayScale</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>GrayScale</primary></indexterm>
+ <para>
+<function>GrayScale </function>
+can be viewed as a degenerate case of
+<function>PseudoColor</function>,
+in which the red, green, and blue values in any given colormap entry
+are equal and thus, produce shades of gray.
+The gray values can be changed dynamically.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Host Portable Character Encoding</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Host Portable Character Encoding</primary></indexterm>
+ <para>
+The encoding of the X Portable Character Set on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Hotspot</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Hotspot</primary></indexterm>
+ <para>
+A cursor has an associated hotspot, which defines the point in the
+cursor corresponding to the coordinates reported for the pointer.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Identifier</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Identifier</primary></indexterm>
+ <para>
+An identifier is a unique value associated with a resource
+that clients use to name that resource.
+The identifier can be used over any connection to name the resource.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Inferiors</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Inferiors</primary></indexterm>
+ <para>
+The inferiors of a window are all of the subwindows nested below it:
+the children, the children's children, and so on.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Input focus</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Input</primary><secondary>focus</secondary></indexterm>
+ <para>
+The input focus is usually a window defining the scope for processing
+of keyboard input.
+If a generated keyboard event usually would be reported to this window
+or one of its inferiors,
+the event is reported as usual.
+Otherwise, the event is reported with respect to the focus window.
+The input focus also can be set such that all keyboard events are discarded
+and such that the focus window is dynamically taken to be the root window
+of whatever screen the pointer is on at each keyboard event.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Input manager</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Input</primary><secondary>manager</secondary></indexterm>
+ <para>
+Control over keyboard input is typically provided by an input manager
+client, which usually is part of a window manager.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>InputOnly window</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Window</primary><secondary>InputOnly</secondary></indexterm>
+ <para>
+An
+<function>InputOnly</function>
+window is a window that cannot be used for graphics requests.
+<function>InputOnly </function>
+windows are invisible and are used to control such things as cursors,
+input event generation, and grabbing.
+<function>InputOnly </function>
+windows cannot have
+<function>InputOutput </function>
+windows as inferiors.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>InputOutput window</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Window</primary><secondary>InputOutput</secondary></indexterm>
+ <para>
+An
+<function>InputOutput</function>
+window is the normal kind of window that is used for both input and output.
+<function>InputOutput </function>
+windows can have both
+<function>InputOutput </function>
+and
+<function>InputOnly </function>
+windows as inferiors.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Internationalization</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Internationalization</primary></indexterm>
+ <para>
+The process of making software adaptable to the requirements
+of different native languages, local customs, and character string encodings.
+Making a computer program adaptable to different locales
+without program source modifications or recompilation.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>ISO2022</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>ISO2022</primary></indexterm>
+ <para>
+ISO standard for code extension techniques for 7-bit and 8-bit coded
+character sets.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Key grabbing</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Key</primary><secondary>grabbing</secondary></indexterm>
+ <para>
+Keys on the keyboard can be passively grabbed by a client.
+When the key is pressed,
+the keyboard is then actively grabbed by the client.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Keyboard grabbing</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>
+ <para>
+A client can actively grab control of the keyboard, and key events
+will be sent to that client rather than the client the events would
+normally have been sent to.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Keysym</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Keysym</primary></indexterm>
+ <para>
+An encoding of a symbol on a keycap on a keyboard.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Latin-1</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Latin-1</primary></indexterm>
+ <para>
+The coded character set defined by the ISO8859-1 standard.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Latin Portable Character Encoding</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Latin Portable Character Encoding</primary></indexterm>
+ <para>
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Locale</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Locale</primary></indexterm>
+ <para>
+The international environment of a computer program defining the ``localized''
+behavior of that program at run-time.
+This information can be established from one or more sets of localization data.
+ANSI C defines locale-specific processing by C system library calls.
+See ANSI C and the X/Open Portability Guide specifications for more details.
+In this specification, on implementations that conform to the ANSI C library,
+the ``current locale'' is the current setting of the LC_CTYPE
+<function>setlocale</function>
+category.
+Associated with each locale is a text encoding. When text is processed
+in the context of a locale, the text must be in the encoding of the locale.
+The current locale affects Xlib in its:
+<!-- .RS -->
+</para>
+ <para>
+Encoding and processing of input method text
+</para>
+ <para>
+Encoding of resource files and values
+</para>
+ <para>
+Encoding and imaging of text strings
+</para>
+ <para>
+Encoding and decoding for inter-client text communication
+<!-- .RE -->
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Locale name</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Locale name</primary></indexterm>
+ <para>
+The identifier used to select the desired locale for the host C library
+and X library functions.
+On ANSI C library compliant systems,
+the locale argument to the
+<function>setlocale</function>
+function.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Localization</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Localization</primary></indexterm>
+ <para>
+The process of establishing information within a computer system specific
+to the operation of particular native languages, local customs
+and coded character sets.
+(XPG3)
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Mapped</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Mapped window</primary></indexterm>
+ <para>
+A window is said to be mapped if a map call has been performed on it.
+Unmapped windows and their inferiors are never viewable or visible.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Modifier keys</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Modifier keys</primary></indexterm>
+ <para>
+Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
+ShiftLock, and similar keys are called modifier keys.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Monochrome</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Monochrome</primary></indexterm>
+ <para>
+Monochrome is a special case of
+<function>StaticGray</function>
+in which there are only two colormap entries.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Multibyte</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Multibyte</primary></indexterm>
+ <para>
+A character whose codepoint is stored in more than one byte;
+any encoding which can contain multibyte characters;
+text in a multibyte encoding.
+The ``char *'' null-terminated string datatype in ANSI C.
+Note that references in this document to multibyte strings
+imply only that the strings <emphasis remap='I'>may</emphasis> contain multibyte characters.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Obscure</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Obscure</primary></indexterm>
+ <para>
+A window is obscured if some other window obscures it.
+A window can be partially obscured and so still have visible regions.
+Window A obscures window B if both are viewable
+<function>InputOutput </function>
+windows, if A is higher in the global stacking order,
+and if the rectangle defined by the outside
+edges of A intersects the rectangle defined by the outside edges of B.
+Note the distinction between obscures and occludes.
+Also note that window borders are included in the calculation.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Occlude</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Occlude</primary></indexterm>
+ <para>
+A window is occluded if some other window occludes it.
+Window A occludes window B if both are mapped,
+if A is higher in the global stacking order,
+and if the rectangle defined by the outside edges of A intersects the rectangle defined
+by the outside edges of B.
+Note the distinction between occludes and obscures.
+Also note that window borders are included in the calculation
+and that
+<function>InputOnly</function>
+windows never obscure other windows but can occlude other windows.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Padding</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Padding</primary></indexterm>
+ <para>
+Some padding bytes are inserted in the data stream to maintain
+alignment of the protocol requests on natural boundaries.
+This increases ease of portability to some machine architectures.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Parent window</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Window</primary><secondary>parent</secondary></indexterm>
+ <para>
+If C is a child of P, then P is the parent of C.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Passive grab</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Passive grab</primary></indexterm>
+ <para>
+Grabbing a key or button is a passive grab.
+The grab activates when the key or button is actually pressed.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Pixel value</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Pixel value</primary></indexterm>
+ <para>
+A pixel is an N-bit value,
+where N is the number of bit planes used in a particular window or pixmap
+(that is, is the depth of the window or pixmap).
+A pixel in a window indexes a colormap to derive an actual color to be
+displayed.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Pixmap</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Pixmap</primary></indexterm>
+<!-- .EQ -->
+<!-- .EN -->
+ <para>
+A pixmap is a three-dimensional array of bits.
+A pixmap is normally thought of as a two-dimensional array of pixels,
+where each pixel can be a value from 0 to %2 sup N %\-1,
+and where N is the depth (z axis) of the pixmap.
+A pixmap can also be thought of as a stack of N bitmaps.
+A pixmap can only be used on the screen that it was created in.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Plane</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Plane</primary></indexterm>
+ <para>
+When a pixmap or window is thought of as a stack of bitmaps, each
+bitmap is called a plane or bit plane.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Plane mask</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Plane</primary><secondary>mask</secondary></indexterm>
+ <para>
+Graphics operations can be restricted to only affect a subset of bit
+planes of a destination.
+A plane mask is a bit mask describing which planes are to be modified.
+The plane mask is stored in a graphics context.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Pointer</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Pointer</primary></indexterm>
+ <para>
+The pointer is the pointing device currently attached to the cursor
+and tracked on the screens.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Pointer grabbing</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+ <para>
+A client can actively grab control of the pointer.
+Then button and motion events will be sent to that client
+rather than the client the events would normally have been sent to.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Pointing device</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Pointing device</primary></indexterm>
+ <para>
+A pointing device is typically a mouse, tablet, or some other
+device with effective dimensional motion.
+The core protocol defines only one visible cursor,
+which tracks whatever pointing device is attached as the pointer.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm><acronym>POSIX</acronym></glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary><acronym>POSIX</acronym></primary></indexterm>
+ <para>
+Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm><acronym>POSIX</acronym> Portable Filename Character Set</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary><acronym>POSIX</acronym> Portable Filename Character Set</primary></indexterm>
+ <para>
+The set of 65 characters which can be used in naming files on a <acronym>POSIX</acronym>-compliant
+host that are correctly processed in all locales.
+The set is:
+</para>
+ <para>
+<!-- .Ds 0 -->
+a..z A..Z 0..9 ._-
+<!-- .De -->
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Property</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Property</primary></indexterm>
+ <para>
+Windows can have associated properties that consist of a name, a type,
+a data format, and some data.
+The protocol places no interpretation on properties.
+They are intended as a general-purpose naming mechanism for clients.
+For example, clients might use properties to share information such as resize
+hints, program names, and icon formats with a window manager.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Property list</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Property list</primary></indexterm>
+ <para>
+The property list of a window is the list of properties that have
+been defined for the window.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>PseudoColor</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>PseudoColor</primary></indexterm>
+ <para>
+<function>PseudoColor</function>
+is a class of colormap in which a pixel value indexes the colormap entry to
+produce an independent <acronym>RGB</acronym> value;
+that is, the colormap is viewed as an array of triples (<acronym>RGB</acronym> values).
+The <acronym>RGB</acronym> values can be changed dynamically.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Rectangle</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Rectangle</primary></indexterm>
+ <para>
+A rectangle specified by [x,y,w,h] has an infinitely thin
+outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h].
+When a rectangle is filled,
+the lower-right edges are not drawn.
+For example,
+if w=h=0,
+nothing would be drawn.
+For w=h=1,
+a single pixel would be drawn.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Redirecting control</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Redirecting control</primary></indexterm>
+ <para>
+Window managers (or client programs) may enforce window layout
+policy in various ways.
+When a client attempts to change the size or position of a window,
+the operation may be redirected to a specified client
+rather than the operation actually being performed.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Reply</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Reply</primary></indexterm>
+ <para>
+Information requested by a client program using the X protocol
+is sent back to the client with a reply.
+Both events and replies are multiplexed on the same connection.
+Most requests do not generate replies,
+but some requests generate multiple replies.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Request</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Request</primary></indexterm>
+ <para>
+A command to the server is called a request.
+It is a single block of data sent over a connection.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Resource</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Resource</primary></indexterm>
+ <para>
+Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are
+known as resources.
+They all have unique identifiers associated with them for naming purposes.
+The lifetime of a resource usually is bounded by the lifetime of the
+connection over which the resource was created.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm><acronym>RGB</acronym> values</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary><acronym>RGB</acronym> values</primary></indexterm>
+ <para>
+<acronym>RGB</acronym> values are the red, green, and blue intensity values that are used
+to define a color.
+These values are always represented as 16-bit, unsigned numbers, with 0
+the minimum intensity and 65535 the maximum intensity.
+The X server scales these values to match the display hardware.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Root</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Root</primary></indexterm>
+ <para>
+The root of a pixmap or graphics context is the same as the root
+of whatever drawable was used when the pixmap or GC was created.
+The root of a window is the root window under which the window was created.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Root window</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Window</primary><secondary>root</secondary></indexterm>
+ <para>
+Each screen has a root window covering it.
+The root window cannot be reconfigured or unmapped,
+but otherwise it acts as a full-fledged window.
+A root window has no parent.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Save set</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Save set</primary></indexterm>
+ <para>
+The save set of a client is a list of other clients' windows that,
+if they are inferiors of one of the client's windows at connection
+close, should not be destroyed and that should be remapped
+if currently unmapped.
+Save sets are typically used by window managers to avoid
+lost windows if the manager should terminate abnormally.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Scanline</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Scanline</primary></indexterm>
+ <para>
+A scanline is a list of pixel or bit values viewed as a horizontal
+row (all values having the same y coordinate) of an image, with the
+values ordered by increasing the x coordinate.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Scanline order</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Scanline</primary><secondary>order</secondary></indexterm>
+ <para>
+An image represented in scanline order contains scanlines ordered by
+increasing the y coordinate.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Screen</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Screen</primary></indexterm>
+ <para>
+A server can provide several independent screens,
+which typically have physically independent monitors.
+This would be the expected configuration when there is only a single keyboard
+and pointer shared among the screens.
+A
+<function>Screen </function>
+<indexterm><primary>Screen</primary><secondary>structure</secondary></indexterm>
+structure contains the information about that screen
+and is linked to the
+<function>Display</function>
+<indexterm><primary>Display</primary><secondary>structure</secondary></indexterm>
+structure.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Selection</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Selection</primary></indexterm>
+ <para>
+A selection can be thought of as an indirect property with dynamic
+type.
+That is, rather than having the property stored in the X server,
+it is maintained by some client (the owner).
+A selection is global and is thought of as belonging to the user
+and being maintained by clients,
+rather than being private to a particular window subhierarchy
+or a particular set of clients.
+When a client asks for the contents of
+a selection, it specifies a selection target type,
+which can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on,''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or
+Z format.
+</para>
+ <para>
+The target type can also be used to control the class of
+contents transmitted; for example,
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, rather than the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Server</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Server</primary></indexterm>
+ <para>
+The server, which is also referred to as the X server,
+provides the basic windowing mechanism.
+It handles <acronym>IPC</acronym> connections from clients,
+multiplexes graphics requests onto the screens,
+and demultiplexes input back to the appropriate clients.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Server grabbing</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Server</primary><secondary>grabbing</secondary></indexterm>
+ <para>
+The server can be grabbed by a single client for exclusive use.
+This prevents processing of any requests from other client connections until
+the grab is completed.
+This is typically only a transient state for such things as rubber-banding,
+pop-up menus, or executing requests indivisibly.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Shift sequence</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Shift sequence</primary></indexterm>
+ <para>
+ISO2022 defines control characters and escape sequences
+which temporarily (single shift) or permanently (locking shift) cause a
+different character set to be in effect (``invoking'' a character set).
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Sibling</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Sibling</primary></indexterm>
+ <para>
+Children of the same parent window are known as sibling windows.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Stacking order</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Stacking order</primary></indexterm>
+ <para>
+Sibling windows, similar to sheets of paper on a desk,
+can stack on top of each other.
+Windows above both obscure and occlude lower windows.
+The relationship between sibling windows is known as the stacking order.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>State-dependent encoding</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>State-dependent encoding</primary></indexterm>
+ <para>
+An encoding in which an invocation of a charset can apply to multiple
+characters in sequence.
+A state-dependent encoding begins in an ``initial state''
+and enters other ``shift states'' when specific ``shift sequences''
+are encountered in the byte sequence.
+In ISO2022 terms,
+this means use of locking shifts, not single shifts.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>State-independent encoding</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>State-independent encoding</primary></indexterm>
+ <para>
+Any encoding in which the invocations of the charsets are fixed,
+or span only a single character.
+In ISO2022 terms,
+this means use of at most single shifts, not locking shifts.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>StaticColor</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>StaticColor</primary></indexterm>
+ <para>
+<function>StaticColor </function>
+can be viewed as a degenerate case of
+<function>PseudoColor</function>
+in which the <acronym>RGB</acronym> values are predefined and read-only.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>StaticGray</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>StaticGray</primary></indexterm>
+ <para>
+<function>StaticGray </function>
+can be viewed as a degenerate case of
+<function>GrayScale</function>
+in which the gray values are predefined and read-only.
+The values are typically linear or near-linear increasing ramps.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Status</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Status</primary></indexterm>
+ <para>
+Many Xlib functions return a success status.
+If the function does not succeed,
+however, its arguments are not disturbed.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Stipple</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Stipple</primary></indexterm>
+ <para>
+A stipple pattern is a bitmap that is used to tile a region to serve
+as an additional clip mask for a fill operation with the foreground
+color.
+ </para>
+ </glossdef>
+</glossentry>
+<!-- .KE -->
+<glossentry>
+ <glossterm>STRING encoding</glossterm>
+ <glossdef>
+ <para>
+Latin-1, plus tab and newline.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>String Equivalence</glossterm>
+ <glossdef>
+ <para>
+<indexterm significance="preferred"><primary>String Equivalence</primary></indexterm>
+Two ISO Latin-1 STRING8 values are considered equal if they are the same
+length and if corresponding bytes are either equal or are equivalent as
+follows: decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are
+pairwise equivalent to decimal values 97 to 122 inclusive
+(characters ``a'' to ``z''), decimal values 192 to 214 inclusive
+(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal
+values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''),
+and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'')
+are pairwise equivalent to decimal values 246 to 254 inclusive
+(characters ``o oblique'' to ``thorn'').
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Tile</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Tile</primary></indexterm>
+ <para>
+A pixmap can be replicated in two dimensions to tile a region.
+The pixmap itself is also known as a tile.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Timestamp</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Timestamp</primary></indexterm>
+ <para>
+A timestamp is a time value expressed in milliseconds.
+It is typically the time since the last server reset.
+Timestamp values wrap around (after about 49.7 days).
+The server, given its current time is represented by timestamp T,
+always interprets timestamps from clients by treating half
+of the timestamp space as being earlier in time than T
+and half of the timestamp space as being later in time than T.
+One timestamp value, represented by the constant
+<function>CurrentTime</function>,
+is never generated by the server.
+This value is reserved for use in requests to represent the current server time.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>TrueColor</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>TrueColor</primary></indexterm>
+ <para>
+<function>TrueColor</function>
+can be viewed as a degenerate case of
+<function>DirectColor</function>
+in which the subfields in the pixel value directly encode the corresponding <acronym>RGB</acronym>
+values.
+That is, the colormap has predefined read-only <acronym>RGB</acronym> values.
+The values are typically linear or near-linear increasing ramps.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Type</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Type</primary></indexterm>
+ <para>
+A type is an arbitrary atom used to identify the interpretation of property
+data.
+Types are completely uninterpreted by the server.
+They are solely for the benefit of clients.
+X predefines type atoms for many frequently used types,
+and clients also can define new types.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Viewable</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Viewable</primary></indexterm>
+ <para>
+A window is viewable if it and all of its ancestors are mapped.
+This does not imply that any portion of the window is actually visible.
+Graphics requests can be performed on a window when it is not
+viewable, but output will not be retained unless the server is maintaining
+backing store.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Visible</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Visible</primary></indexterm>
+ <para>
+A region of a window is visible if someone looking at the screen can
+actually see it; that is, the window is viewable and the region is not occluded
+by any other window.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Whitespace</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Whitespace</primary></indexterm>
+ <para>
+Any spacing character.
+On implementations that conform to the ANSI C library,
+whitespace is any character for which
+<function>isspace</function>
+returns true.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Window gravity</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Window</primary><secondary>gravity</secondary></indexterm>
+ <para>
+When windows are resized,
+subwindows may be repositioned automatically relative to some position in the
+window.
+This attraction of a subwindow to some part of its parent is known
+as window gravity.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Window manager</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Window</primary><secondary>manager</secondary></indexterm>
+ <para>
+Manipulation of windows on the screen and much of the user interface
+(policy) is typically provided by a window manager client.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>X Portable Character Set</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>X Portable Character Set</primary></indexterm>
+ <para>
+A basic set of 97 characters which are assumed to exist in all
+locales supported by Xlib. This set contains the following characters:
+ </para>
+ <para>
+<!-- .Ds 0 -->
+<!-- .EQ -->
+<!-- .EN -->
+ </para>
+ <para>
+a..z A..Z 0..9
+!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
+<space>, <tab>, and <newline>
+<!-- .EQ -->
+<!-- .EN -->
+<!-- .De -->
+ </para>
+ <para>
+This is the left/lower half (also called the G0 set)
+of the graphic character set of ISO8859-1 plus <space>, <tab>, and <newline>.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent;
+see the Host Portable Character Encoding.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm><acronym>XLFD</acronym></glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary><acronym>XLFD</acronym></primary></indexterm>
+ <para>
+The X Logical Font Description Conventions that define a standard syntax
+for structured font names.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>XY format</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>XY format</primary></indexterm>
+ <para>
+The data for a pixmap is said to be in XY format if it is organized as
+a set of bitmaps representing individual bit planes with the planes
+appearing from most-significant to least-significant bit order.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Z format</glossterm>
+ <glossdef>
+<indexterm significance="preferred"><primary>Z format</primary></indexterm>
+ <para>
+The data for a pixmap is said to be in Z format if it is organized as
+a set of pixel values in scanline order.
+<!-- .KE -->
+ </para>
+ </glossdef>
+</glossentry>
+
+<bibliography>
+<title>References</title>
+<biblioentry>
+<title>Draft Proposed Multibyte Extension of ANSI C, Draft 1.1</title>
+<date>November 30, 1989 SC22/C WG/SWG IPSJ/ITSCJ Japan</date>
+</biblioentry>
+
+<biblioentry>
+<title>
+ISO2022: Information processing - ISO 7-bit and 8-bit coded character
+sets - Code extension techniques.
+</title>
+</biblioentry>
+
+<biblioentry>
+<title>
+ISO8859-1: Information processing - 8-bit single-byte coded graphic
+character sets - Part 1: Latin alphabet No. 1.
+</title>
+</biblioentry>
+
+<biblioentry>
+<title>
+<acronym>POSIX</acronym>: Information Technology - Portable Operating System Interface (<acronym>POSIX</acronym>) -
+Part 1: System Application Program Interface (API) [C Language],
+ISO/IEC 9945-1.
+</title>
+</biblioentry>
+
+<biblioentry>
+<title>
+Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information
+Interchange - Part 1: Architecture.
+</title>
+</biblioentry>
+
+<biblioentry>
+<title>
+X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company,
+Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8.
+(See especially Volume 3: XSI Supplementary Definitions.)
+</title>
+</biblioentry>
+</bibliography>
+
+</glossary>
diff --git a/libX11/specs/libX11/indexmacros.t b/libX11/specs/libX11/indexmacros.t deleted file mode 100644 index ec5d4fa6d..000000000 --- a/libX11/specs/libX11/indexmacros.t +++ /dev/null @@ -1,3 +0,0 @@ -.eh '\fBXlib \- C Library\fP''\fB\*(xV\fP'
-.oh '\fBXlib \- C Library\fP''\fB\*(xV\fP'
-.so index.pageno
diff --git a/libX11/specs/libX11/libX11.ms b/libX11/specs/libX11/libX11.ms deleted file mode 100644 index b44425623..000000000 --- a/libX11/specs/libX11/libX11.ms +++ /dev/null @@ -1,24 +0,0 @@ -.so abstract.t -.so credits.t -.so CH01 -.so CH02 -.so CH03 -.so CH04 -.so CH05 -.so CH06 -.so CH07 -.so CH08 -.so CH09 -.so CH10 -.so CH11 -.so CH12 -.so CH13 -.so CH14 -.so CH15 -.so CH16 -.so AppA -.so AppB -.so AppC -.so AppD -.so glossary -.so postproc diff --git a/libX11/specs/libX11/libX11.xml b/libX11/specs/libX11/libX11.xml new file mode 100644 index 000000000..40a1d95ec --- /dev/null +++ b/libX11/specs/libX11/libX11.xml @@ -0,0 +1,147 @@ +<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<book id="libX11">
+
+<bookinfo>
+ <title>Xlib - C Language X Interface</title>
+ <subtitle>X Window System Standard</subtitle>
+ <releaseinfo>X Version 11, Release 7</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>James</firstname><surname>Gettys</surname>
+ <affiliation>
+ <orgname>Digital Equipment Corporation</orgname>
+ <orgdiv>Cambridge Research Laboratory</orgdiv>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Robert</firstname><othername role='mi'>W.</othername> <surname>Scheifler</surname>
+ <affiliation>
+ <orgname>Massachusetts Institute of Technology</orgname>
+ <orgdiv>Laboratory for Computer Science</orgdiv>
+ </affiliation>
+ </author>
+ <othercredit>
+ <firstname>Chuck</firstname><surname>Adams</surname>
+ <affiliation><orgname>Tektronix, Inc.</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Vania</firstname><surname>Joloboff</surname>
+ <affiliation><orgname>Open Software Foundation</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Hideki</firstname><surname>Hiura</surname>
+ <affiliation><orgname>Sun Microsystems, Inc.</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Bill</firstname><surname>McMahon</surname>
+ <affiliation><orgname>Hewlett-Packard Company</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Ron</firstname><surname>Newman</surname>
+ <affiliation><orgname>Massachusetts Institute of Technology</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Al</firstname><surname>Tabayoyon</surname>
+ <affiliation><orgname>Tektronix, Inc.</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Glenn</firstname><surname>Widener</surname>
+ <affiliation><orgname>Tektronix, Inc.</orgname></affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Shigeru</firstname><surname>Yamada</surname>
+ <affiliation><orgname>Fujitsu OSSI</orgname></affiliation>
+ </othercredit>
+ </authorgroup>
+ <copyright><year>1985</year><year>1986</year><year>1987</year>
+ <year>1988</year><year>1989</year><year>1991</year><year>1994</year>
+ <year>1996</year><year>2002</year><holder>The Open Group</holder>
+ </copyright>
+ <copyright><year>1985</year><year>1986</year><year>1987</year>
+ <year>1988</year><year>1989</year><year>1991</year>
+ <holder>Digital Equipment Corporation</holder>
+ </copyright>
+
+ <affiliation><orgname>formerly MIT X Consortium</orgname></affiliation>
+ <productnumber>X Version 11, Release 7</productnumber>
+
+<legalnotice>
+
+<para>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files
+(the “Software”), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following
+conditions:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+</para>
+
+<para>
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of The Open Group shall not
+be used in advertising or otherwise to promote the sale, use or other dealings
+in this Software without prior written authorization from The Open Group.
+</para>
+
+<para>
+Permission to use, copy, modify and distribute this documentation for any
+purpose and without fee is hereby granted, provided that the above copyright
+notice appears in all copies and that both that copyright notice and this
+permission notice appear in supporting documentation, and that the names of
+Digital and Tetronix not be used in in advertising or publicity pertaining
+to distribution of the software without specific, written prior permission.
+Digital and Tetronix make no representations about the suitability of the
+software described herein for any purpose.
+It is provided "as is" without express or implied warranty.
+</para>
+
+
+<para>TekHVC is a trademark of Tektronix, Inc.</para>
+
+</legalnotice>
+</bookinfo>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="credits.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH01.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH02.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH03.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH04.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH05.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH06.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH07.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH08.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH09.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH10.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH11.xml"/>
+<!-- -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH12.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH13.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH14.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH15.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH16.xml"/>
+<!-- runs out of mem at here -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AppA.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AppB.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AppC.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AppD.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml"/>
+<index />
+</book>
+
diff --git a/libX11/specs/libX11/postproc b/libX11/specs/libX11/postproc deleted file mode 100644 index 0f45a5a00..000000000 --- a/libX11/specs/libX11/postproc +++ /dev/null @@ -1,17 +0,0 @@ -.\" -.\" print Table of Contents -.if e \& \" Force blank page to begin TOC on an odd (right-hand) page. -.EH '''' -.OH '''' -.bp -\& \" Want old footings if blank page was forced. -.EF '''' -.OF '''' -.XS -Index -.XE -.EQ -delim $$ -.EN -.tm .pn \n% -.PX diff --git a/libX11/specs/xmlrules.in b/libX11/specs/xmlrules.in new file mode 100644 index 000000000..50865b5b8 --- /dev/null +++ b/libX11/specs/xmlrules.in @@ -0,0 +1,59 @@ +#
+# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+#
+
+if HAVE_XMLTO
+spec_DATA = $(doc_sources:.xml=.html)
+
+if HAVE_FOP
+spec_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf)
+endif
+
+if HAVE_XMLTO_TEXT
+spec_DATA += $(doc_sources:.xml=.txt)
+endif
+
+if HAVE_STYLESHEETS
+XMLTO_FLAGS = -m $(XSL_STYLESHEET)
+
+spec_DATA += xorg.css
+xorg.css: $(STYLESHEET_SRCDIR)/xorg.css
+ $(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@
+endif
+
+CLEANFILES = $(spec_DATA)
+
+SUFFIXES = .xml .ps .pdf .txt .html
+
+.xml.txt:
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<
+
+.xml.html:
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $<
+
+.xml.pdf:
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $<
+
+.xml.ps:
+ $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $<
+
+endif HAVE_XMLTO
diff --git a/libX11/src/Makefile.am b/libX11/src/Makefile.am index 3864bfaaa..455650c58 100644 --- a/libX11/src/Makefile.am +++ b/libX11/src/Makefile.am @@ -341,7 +341,7 @@ libX11_la_SOURCES+=UIThrStubs.c endif
x11datadir = @X11_DATADIR@
-x11data_DATA = XKeysymDB XErrorDB
+x11data_DATA = XErrorDB
EXTRA_DIST = \
$(x11data_DATA) \
@@ -414,10 +414,10 @@ endif MAKE_LINT_LIB # Building ks_tables.h requires the makekeys utility
#
-KEYSYMDEF=@KEYSYMDEF@
+KEYSYMDEFS=@KEYSYMDEFS@
-ks_tables.h: $(KEYSYMDEF) $(top_builddir)/src/util/makekeys$(EXEEXT)
- $(top_builddir)/src/util/makekeys < $(KEYSYMDEF) > ks_tables_h
+ks_tables.h: $(KEYSYMDEFS) $(top_builddir)/src/util/makekeys$(EXEEXT)
+ $(top_builddir)/src/util/makekeys $(KEYSYMDEFS) > ks_tables_h
mv ks_tables_h $@
$(top_builddir)/src/util/makekeys$(EXEEXT): force
diff --git a/libX11/src/StrKeysym.c b/libX11/src/StrKeysym.c index fb507458f..8fb384505 100644 --- a/libX11/src/StrKeysym.c +++ b/libX11/src/StrKeysym.c @@ -1,156 +1,171 @@ -/* - -Copyright 1985, 1987, 1990, 1998 The Open Group - -Permission to use, copy, modify, distribute, and sell this software and its -documentation for any purpose is hereby granted without fee, provided that -the above copyright notice appear in all copies and that both that -copyright notice and this permission notice appear in supporting -documentation. - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN -AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -Except as contained in this notice, the name of The Open Group shall not be -used in advertising or otherwise to promote the sale, use or other dealings -in this Software without prior written authorization from The Open Group. - -*/ - -#ifdef HAVE_CONFIG_H -#include <config.h> -#endif -#include "Xlibint.h" -#include <X11/Xresource.h> -#include <X11/keysymdef.h> -#include "Xresinternal.h" - -#define NEEDKTABLE -#include "ks_tables.h" -#include "Key.h" - -#ifndef KEYSYMDB -#ifndef XKEYSYMDB -#define KEYSYMDB "/usr/lib/X11/XKeysymDB" -#else -#define KEYSYMDB XKEYSYMDB -#endif -#endif - -static Bool initialized; -static XrmDatabase keysymdb; -static XrmQuark Qkeysym[2]; - -XrmDatabase -_XInitKeysymDB(void) -{ - if (!initialized) - { - const char *dbname; - - XrmInitialize(); - /* use and name of this env var is not part of the standard */ - /* implementation-dependent feature */ - dbname = getenv("XKEYSYMDB"); - if (!dbname) - dbname = KEYSYMDB; - keysymdb = XrmGetFileDatabase(dbname); - if (keysymdb) - Qkeysym[0] = XrmStringToQuark("Keysym"); - initialized = True; - } - return keysymdb; -} - -KeySym -XStringToKeysym(_Xconst char *s) -{ - register int i, n; - int h; - register Signature sig = 0; - register const char *p = s; - register int c; - register int idx; - const unsigned char *entry; - unsigned char sig1, sig2; - KeySym val; - - while ((c = *p++)) - sig = (sig << 1) + c; - i = sig % KTABLESIZE; - h = i + 1; - sig1 = (sig >> 8) & 0xff; - sig2 = sig & 0xff; - n = KMAXHASH; - while ((idx = hashString[i])) - { - entry = &_XkeyTable[idx]; - if ((entry[0] == sig1) && (entry[1] == sig2) && - !strcmp(s, (char *)entry + 6)) - { - val = (entry[2] << 24) | (entry[3] << 16) | - (entry[4] << 8) | entry[5]; - if (!val) - val = XK_VoidSymbol; - return val; - } - if (!--n) - break; - i += h; - if (i >= KTABLESIZE) - i -= KTABLESIZE; - } - - if (!initialized) - (void)_XInitKeysymDB(); - if (keysymdb) - { - XrmValue result; - XrmRepresentation from_type; - char c; - XrmQuark names[2]; - - names[0] = _XrmInternalStringToQuark(s, p - s - 1, sig, False); - names[1] = NULLQUARK; - (void)XrmQGetResource(keysymdb, names, Qkeysym, &from_type, &result); - if (result.addr && (result.size > 1)) - { - val = 0; - for (i = 0; i < result.size - 1; i++) - { - c = ((char *)result.addr)[i]; - if ('0' <= c && c <= '9') val = (val<<4)+c-'0'; - else if ('a' <= c && c <= 'f') val = (val<<4)+c-'a'+10; - else if ('A' <= c && c <= 'F') val = (val<<4)+c-'A'+10; - else return NoSymbol; - } - return val; - } - } - - if (*s == 'U') { - val = 0; - for (p = &s[1]; *p; p++) { - c = *p; - if ('0' <= c && c <= '9') val = (val<<4)+c-'0'; - else if ('a' <= c && c <= 'f') val = (val<<4)+c-'a'+10; - else if ('A' <= c && c <= 'F') val = (val<<4)+c-'A'+10; - else return NoSymbol; - if (val > 0x10ffff) - return NoSymbol; - } - if (val < 0x20 || (val > 0x7e && val < 0xa0)) - return NoSymbol; - if (val < 0x100) - return val; - return val | 0x01000000; - } - return NoSymbol; -} +/*
+
+Copyright 1985, 1987, 1990, 1998 The Open Group
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of The Open Group shall not be
+used in advertising or otherwise to promote the sale, use or other dealings
+in this Software without prior written authorization from The Open Group.
+
+*/
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+#include "Xlibint.h"
+#include <X11/Xresource.h>
+#include <X11/keysymdef.h>
+#include "Xresinternal.h"
+
+#define NEEDKTABLE
+#include "ks_tables.h"
+#include "Key.h"
+
+#ifndef KEYSYMDB
+#ifndef XKEYSYMDB
+#define KEYSYMDB "/usr/lib/X11/XKeysymDB"
+#else
+#define KEYSYMDB XKEYSYMDB
+#endif
+#endif
+
+static Bool initialized;
+static XrmDatabase keysymdb;
+static XrmQuark Qkeysym[2];
+
+XrmDatabase
+_XInitKeysymDB(void)
+{
+ if (!initialized)
+ {
+ const char *dbname;
+
+ XrmInitialize();
+ /* use and name of this env var is not part of the standard */
+ /* implementation-dependent feature */
+ dbname = getenv("XKEYSYMDB");
+ if (!dbname)
+ dbname = KEYSYMDB;
+ keysymdb = XrmGetFileDatabase(dbname);
+ if (keysymdb)
+ Qkeysym[0] = XrmStringToQuark("Keysym");
+ initialized = True;
+ }
+ return keysymdb;
+}
+
+KeySym
+XStringToKeysym(_Xconst char *s)
+{
+ register int i, n;
+ int h;
+ register Signature sig = 0;
+ register const char *p = s;
+ register int c;
+ register int idx;
+ const unsigned char *entry;
+ unsigned char sig1, sig2;
+ KeySym val;
+
+ while ((c = *p++))
+ sig = (sig << 1) + c;
+ i = sig % KTABLESIZE;
+ h = i + 1;
+ sig1 = (sig >> 8) & 0xff;
+ sig2 = sig & 0xff;
+ n = KMAXHASH;
+ while ((idx = hashString[i]))
+ {
+ entry = &_XkeyTable[idx];
+ if ((entry[0] == sig1) && (entry[1] == sig2) &&
+ !strcmp(s, (char *)entry + 6))
+ {
+ val = (entry[2] << 24) | (entry[3] << 16) |
+ (entry[4] << 8) | entry[5];
+ if (!val)
+ val = XK_VoidSymbol;
+ return val;
+ }
+ if (!--n)
+ break;
+ i += h;
+ if (i >= KTABLESIZE)
+ i -= KTABLESIZE;
+ }
+
+ if (!initialized)
+ (void)_XInitKeysymDB();
+ if (keysymdb)
+ {
+ XrmValue result;
+ XrmRepresentation from_type;
+ char c;
+ XrmQuark names[2];
+
+ names[0] = _XrmInternalStringToQuark(s, p - s - 1, sig, False);
+ names[1] = NULLQUARK;
+ (void)XrmQGetResource(keysymdb, names, Qkeysym, &from_type, &result);
+ if (result.addr && (result.size > 1))
+ {
+ val = 0;
+ for (i = 0; i < result.size - 1; i++)
+ {
+ c = ((char *)result.addr)[i];
+ if ('0' <= c && c <= '9') val = (val<<4)+c-'0';
+ else if ('a' <= c && c <= 'f') val = (val<<4)+c-'a'+10;
+ else if ('A' <= c && c <= 'F') val = (val<<4)+c-'A'+10;
+ else return NoSymbol;
+ }
+ return val;
+ }
+ }
+
+ if (*s == 'U') {
+ val = 0;
+ for (p = &s[1]; *p; p++) {
+ c = *p;
+ if ('0' <= c && c <= '9') val = (val<<4)+c-'0';
+ else if ('a' <= c && c <= 'f') val = (val<<4)+c-'a'+10;
+ else if ('A' <= c && c <= 'F') val = (val<<4)+c-'A'+10;
+ else return NoSymbol;
+ if (val > 0x10ffff)
+ return NoSymbol;
+ }
+ if (val < 0x20 || (val > 0x7e && val < 0xa0))
+ return NoSymbol;
+ if (val < 0x100)
+ return val;
+ return val | 0x01000000;
+ }
+
+ /* Stupid inconsistency between the headers and XKeysymDB: the former has
+ * no separating underscore, while some XF86* syms in the latter did.
+ * As a last ditch effort, try without. */
+ if (strncmp(s, "XF86_", 5) == 0) {
+ KeySym ret;
+ char *tmp = strdup(s);
+ if (!tmp)
+ return NoSymbol;
+ memmove(&tmp[4], &tmp[5], strlen(s) - 5 + 1);
+ ret = XStringToKeysym(tmp);
+ free(tmp);
+ return ret;
+ }
+
+ return NoSymbol;
+}
diff --git a/libX11/src/XKeysymDB b/libX11/src/XKeysymDB deleted file mode 100644 index 45d892971..000000000 --- a/libX11/src/XKeysymDB +++ /dev/null @@ -1,380 +0,0 @@ -! Copyright 1993 Massachusetts Institute of Technology -! -! Permission to use, copy, modify, distribute, and sell this software and -! its documentation for any purpose is hereby granted without fee, provided -! that the above copyright notice appear in all copies and that both that -! copyright notice and this permission notice appear in supporting -! documentation, and that the name of M.I.T. not be used in advertising or -! publicity pertaining to distribution of the software without specific, -! written prior permission. M.I.T. makes no representations about the -! suitability of this software for any purpose. It is provided "as is" -! without express or implied warranty. -! - -hpmute_acute :100000A8 -hpmute_grave :100000A9 -hpmute_asciicircum :100000AA -hpmute_diaeresis :100000AB -hpmute_asciitilde :100000AC -hplira :100000AF -hpguilder :100000BE -hpYdiaeresis :100000EE -hpIO :100000EE -hplongminus :100000F6 -hpblock :100000FC -apLineDel :1000FF00 -apCharDel :1000FF01 -apCopy :1000FF02 -apCut :1000FF03 -apPaste :1000FF04 -apMove :1000FF05 -apGrow :1000FF06 -apCmd :1000FF07 -apShell :1000FF08 -apLeftBar :1000FF09 -apRightBar :1000FF0A -apLeftBox :1000FF0B -apRightBox :1000FF0C -apUpBox :1000FF0D -apDownBox :1000FF0E -apPop :1000FF0F -apRead :1000FF10 -apEdit :1000FF11 -apSave :1000FF12 -apExit :1000FF13 -apRepeat :1000FF14 -hpModelock1 :1000FF48 -hpModelock2 :1000FF49 -hpReset :1000FF6C -hpSystem :1000FF6D -hpUser :1000FF6E -hpClearLine :1000FF6F -hpInsertLine :1000FF70 -hpDeleteLine :1000FF71 -hpInsertChar :1000FF72 -hpDeleteChar :1000FF73 -hpBackTab :1000FF74 -hpKP_BackTab :1000FF75 -apKP_parenleft :1000FFA8 -apKP_parenright :1000FFA9 - -I2ND_FUNC_L :10004001 -I2ND_FUNC_R :10004002 -IREMOVE :10004003 -IREPEAT :10004004 -IA1 :10004101 -IA2 :10004102 -IA3 :10004103 -IA4 :10004104 -IA5 :10004105 -IA6 :10004106 -IA7 :10004107 -IA8 :10004108 -IA9 :10004109 -IA10 :1000410A -IA11 :1000410B -IA12 :1000410C -IA13 :1000410D -IA14 :1000410E -IA15 :1000410F -IB1 :10004201 -IB2 :10004202 -IB3 :10004203 -IB4 :10004204 -IB5 :10004205 -IB6 :10004206 -IB7 :10004207 -IB8 :10004208 -IB9 :10004209 -IB10 :1000420A -IB11 :1000420B -IB12 :1000420C -IB13 :1000420D -IB14 :1000420E -IB15 :1000420F -IB16 :10004210 - -DRemove :1000FF00 -Dring_accent :1000FEB0 -Dcircumflex_accent :1000FE5E -Dcedilla_accent :1000FE2C -Dacute_accent :1000FE27 -Dgrave_accent :1000FE60 -Dtilde :1000FE7E -Ddiaeresis :1000FE22 - -osfCopy :1004FF02 -osfCut :1004FF03 -osfPaste :1004FF04 -osfBackTab :1004FF07 -osfBackSpace :1004FF08 -osfClear :1004FF0B -osfEscape :1004FF1B -osfAddMode :1004FF31 -osfPrimaryPaste :1004FF32 -osfQuickPaste :1004FF33 -osfPageLeft :1004FF40 -osfPageUp :1004FF41 -osfPageDown :1004FF42 -osfPageRight :1004FF43 -osfActivate :1004FF44 -osfMenuBar :1004FF45 -osfLeft :1004FF51 -osfUp :1004FF52 -osfRight :1004FF53 -osfDown :1004FF54 -osfPrior :1004FF55 -osfNext :1004FF56 -osfEndLine :1004FF57 -osfBeginLine :1004FF58 -osfEndData :1004FF59 -osfBeginData :1004FF5A -osfPrevMenu :1004FF5B -osfNextMenu :1004FF5C -osfPrevField :1004FF5D -osfNextField :1004FF5E -osfSelect :1004FF60 -osfInsert :1004FF63 -osfUndo :1004FF65 -osfMenu :1004FF67 -osfCancel :1004FF69 -osfHelp :1004FF6A -osfSelectAll :1004FF71 -osfDeselectAll :1004FF72 -osfReselect :1004FF73 -osfExtend :1004FF74 -osfRestore :1004FF78 -osfSwitchDirection :1004FF7E -osfPriorMinor :1004FFF5 -osfNextMinor :1004FFF6 -osfRightLine :1004FFF7 -osfLeftLine :1004FFF8 -osfDelete :1004FFFF - -SunFA_Grave :1005FF00 -SunFA_Circum :1005FF01 -SunFA_Tilde :1005FF02 -SunFA_Acute :1005FF03 -SunFA_Diaeresis :1005FF04 -SunFA_Cedilla :1005FF05 -SunF36 :1005FF10 -SunF37 :1005FF11 -SunSys_Req :1005FF60 -SunProps :1005FF70 -SunFront :1005FF71 -SunCopy :1005FF72 -SunOpen :1005FF73 -SunPaste :1005FF74 -SunCut :1005FF75 -SunPowerSwitch :1005FF76 -SunAudioLowerVolume :1005FF77 -SunAudioMute :1005FF78 -SunAudioRaiseVolume :1005FF79 -SunVideoDegauss :1005FF7A -SunVideoLowerBrightness :1005FF7B -SunVideoRaiseBrightness :1005FF7C -SunPowerSwitchShift :1005FF7D - -SunCompose :FF20 -SunPageUp :FF55 -SunPageDown :FF56 -SunPrint_Screen :FF61 -SunUndo :FF65 -SunAgain :FF66 -SunFind :FF68 -SunStop :FF69 -SunAltGraph :FF7E - -WYSetup :1006FF00 - -ncdSetup :1006FF00 - -XeroxPointerButton1 :10070001 -XeroxPointerButton2 :10070002 -XeroxPointerButton3 :10070003 -XeroxPointerButton4 :10070004 -XeroxPointerButton5 :10070005 - -! The definitions here should match <X11/XF86keysym.h> -XF86ModeLock :1008FF01 -XF86MonBrightnessUp :1008FF02 -XF86MonBrightnessDown :1008FF03 -XF86KbdLightOnOff :1008FF04 -XF86KbdBrightnessUp :1008FF05 -XF86KbdBrightnessDown :1008FF06 -XF86Standby :1008FF10 -XF86AudioLowerVolume :1008FF11 -XF86AudioMute :1008FF12 -XF86AudioRaiseVolume :1008FF13 -XF86AudioPlay :1008FF14 -XF86AudioStop :1008FF15 -XF86AudioPrev :1008FF16 -XF86AudioNext :1008FF17 -XF86HomePage :1008FF18 -XF86Mail :1008FF19 -XF86Start :1008FF1A -XF86Search :1008FF1B -XF86AudioRecord :1008FF1C -XF86Calculator :1008FF1D -XF86Memo :1008FF1E -XF86ToDoList :1008FF1F -XF86Calendar :1008FF20 -XF86PowerDown :1008FF21 -XF86ContrastAdjust :1008FF22 -XF86RockerUp :1008FF23 -XF86RockerDown :1008FF24 -XF86RockerEnter :1008FF25 -XF86Back :1008FF26 -XF86Forward :1008FF27 -XF86Stop :1008FF28 -XF86Refresh :1008FF29 -XF86PowerOff :1008FF2A -XF86WakeUp :1008FF2B -XF86Eject :1008FF2C -XF86ScreenSaver :1008FF2D -XF86WWW :1008FF2E -XF86Sleep :1008FF2F -XF86Favorites :1008FF30 -XF86AudioPause :1008FF31 -XF86AudioMedia :1008FF32 -XF86MyComputer :1008FF33 -XF86VendorHome :1008FF34 -XF86LightBulb :1008FF35 -XF86Shop :1008FF36 -XF86History :1008FF37 -XF86OpenURL :1008FF38 -XF86AddFavorite :1008FF39 -XF86HotLinks :1008FF3A -XF86BrightnessAdjust :1008FF3B -XF86Finance :1008FF3C -XF86Community :1008FF3D -XF86AudioRewind :1008FF3E -XF86BackForward :1008FF3F -XF86Launch0 :1008FF40 -XF86Launch1 :1008FF41 -XF86Launch2 :1008FF42 -XF86Launch3 :1008FF43 -XF86Launch4 :1008FF44 -XF86Launch5 :1008FF45 -XF86Launch6 :1008FF46 -XF86Launch7 :1008FF47 -XF86Launch8 :1008FF48 -XF86Launch9 :1008FF49 -XF86LaunchA :1008FF4A -XF86LaunchB :1008FF4B -XF86LaunchC :1008FF4C -XF86LaunchD :1008FF4D -XF86LaunchE :1008FF4E -XF86LaunchF :1008FF4F -XF86ApplicationLeft :1008FF50 -XF86ApplicationRight :1008FF51 -XF86Book :1008FF52 -XF86CD :1008FF53 -XF86Calculater :1008FF54 -XF86Clear :1008FF55 -XF86Close :1008FF56 -XF86Copy :1008FF57 -XF86Cut :1008FF58 -XF86Display :1008FF59 -XF86DOS :1008FF5A -XF86Documents :1008FF5B -XF86Excel :1008FF5C -XF86Explorer :1008FF5D -XF86Game :1008FF5E -XF86Go :1008FF5F -XF86iTouch :1008FF60 -XF86LogOff :1008FF61 -XF86Market :1008FF62 -XF86Meeting :1008FF63 -XF86MenuKB :1008FF65 -XF86MenuPB :1008FF66 -XF86MySites :1008FF67 -XF86New :1008FF68 -XF86News :1008FF69 -XF86OfficeHome :1008FF6A -XF86Open :1008FF6B -XF86Option :1008FF6C -XF86Paste :1008FF6D -XF86Phone :1008FF6E -XF86Q :1008FF70 -XF86Reply :1008FF72 -XF86Reload :1008FF73 -XF86RotateWindows :1008FF74 -XF86RotationPB :1008FF75 -XF86RotationKB :1008FF76 -XF86Save :1008FF77 -XF86ScrollUp :1008FF78 -XF86ScrollDown :1008FF79 -XF86ScrollClick :1008FF7A -XF86Send :1008FF7B -XF86Spell :1008FF7C -XF86SplitScreen :1008FF7D -XF86Support :1008FF7E -XF86TaskPane :1008FF7F -XF86Terminal :1008FF80 -XF86Tools :1008FF81 -XF86Travel :1008FF82 -XF86UserPB :1008FF84 -XF86User1KB :1008FF85 -XF86User2KB :1008FF86 -XF86Video :1008FF87 -XF86WheelButton :1008FF88 -XF86Word :1008FF89 -XF86Xfer :1008FF8A -XF86ZoomIn :1008FF8B -XF86ZoomOut :1008FF8C -XF86Away :1008FF8D -XF86Messenger :1008FF8E -XF86WebCam :1008FF8F -XF86MailForward :1008FF90 -XF86Pictures :1008FF91 -XF86Music :1008FF92 -XF86Battery :1008FF93 -XF86Bluetooth :1008FF94 -XF86WLAN :1008FF95 -XF86UWB :1008FF96 -XF86AudioForward :1008FF97 -XF86AudioRepeat :1008FF98 -XF86AudioRandomPlay :1008FF99 -XF86Subtitle :1008FF9A -XF86AudioCycleTrack :1008FF9B -XF86CycleAngle :1008FF9C -XF86FrameBack :1008FF9D -XF86FrameForward :1008FF9E -XF86Time :1008FF9F -XF86Select :1008FFA0 -XF86View :1008FFA1 -XF86TopMenu :1008FFA2 -XF86Red :1008FFA3 -XF86Green :1008FFA4 -XF86Yellow :1008FFA5 -XF86Blue :1008FFA6 -XF86Suspend :1008FFA7 -XF86Hibernate :1008FFA8 -XF86TouchpadToggle :1008FFA9 - -! XFree86 special action keys -XF86_Switch_VT_1 :1008FE01 -XF86_Switch_VT_2 :1008FE02 -XF86_Switch_VT_3 :1008FE03 -XF86_Switch_VT_4 :1008FE04 -XF86_Switch_VT_5 :1008FE05 -XF86_Switch_VT_6 :1008FE06 -XF86_Switch_VT_7 :1008FE07 -XF86_Switch_VT_8 :1008FE08 -XF86_Switch_VT_9 :1008FE09 -XF86_Switch_VT_10 :1008FE0A -XF86_Switch_VT_11 :1008FE0B -XF86_Switch_VT_12 :1008FE0C -XF86_Ungrab :1008FE20 -XF86_ClearGrab :1008FE21 -XF86_Next_VMode :1008FE22 -XF86_Prev_VMode :1008FE23 - -usldead_acute :100000A8 -usldead_grave :100000A9 -usldead_diaeresis :100000AB -usldead_asciicircum :100000AA -usldead_asciitilde :100000AC -usldead_cedilla :1000FE2C -usldead_ring :1000FEB0 diff --git a/libX11/src/util/makekeys.c b/libX11/src/util/makekeys.c index 1c27e6b21..85ce75268 100644 --- a/libX11/src/util/makekeys.c +++ b/libX11/src/util/makekeys.c @@ -1,277 +1,316 @@ -/* - -Copyright 1990, 1998 The Open Group - -Permission to use, copy, modify, distribute, and sell this software and its -documentation for any purpose is hereby granted without fee, provided that -the above copyright notice appear in all copies and that both that -copyright notice and this permission notice appear in supporting -documentation. - -The above copyright notice and this permission notice shall be included -in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - -Except as contained in this notice, the name of The Open Group shall -not be used in advertising or otherwise to promote the sale, use or -other dealings in this Software without prior written authorization -from The Open Group. - -*/ - -/* Constructs hash tables for XStringToKeysym and XKeysymToString. */ - -#include <X11/X.h> -#include <X11/Xos.h> -#include <X11/keysymdef.h> -#include <stdio.h> -#include <stdlib.h> - -typedef unsigned long Signature; - -#define KTNUM 4000 - -static struct info { - char *name; - KeySym val; -} info[KTNUM]; - -#define MIN_REHASH 15 -#define MATCHES 10 - -static char tab[KTNUM]; -static unsigned short offsets[KTNUM]; -static unsigned short indexes[KTNUM]; -static KeySym values[KTNUM]; -static char buf[1024]; - -int -main(int argc, char *argv[]) -{ - int ksnum = 0; - int max_rehash; - Signature sig; - register int i, j, k, z; - register char *name; - register char c; - int first; - int best_max_rehash; - int best_z = 0; - int num_found; - KeySym val; - char key[128]; - char alias[128]; - - - while (fgets(buf, sizeof(buf), stdin)) { - i = sscanf(buf, "#define XK_%127s 0x%lx", key, &info[ksnum].val); - if (i != 2) { - i = sscanf(buf, "#define XK_%127s XK_%127s", key, alias); - if (i != 2) - continue; - for (i = ksnum - 1; i >= 0; i--) { - if (strcmp(info[i].name, alias) == 0) { - info[ksnum].val = info[i].val; - break; - } - } - if (i < 0) { /* Didn't find a match */ - fprintf(stderr, - "can't find matching definition %s for keysym %s\n", - alias, key); - continue; - } - } - if (info[ksnum].val == XK_VoidSymbol) - info[ksnum].val = 0; - if (info[ksnum].val > 0x1fffffff) { - fprintf(stderr, - "ignoring illegal keysym (%s), remove it from .h file!\n", - key); - continue; - } - name = strdup(key); - if (!name) { - fprintf(stderr, "makekeys: out of memory!\n"); - exit(1); - } - info[ksnum].name = name; - ksnum++; - if (ksnum == KTNUM) { - fprintf(stderr, "makekeys: too many keysyms!\n"); - exit(1); - } - } - - printf("/* This file is generated from keysymdef.h. */\n"); - printf("/* Do not edit. */\n"); - printf("\n"); - - best_max_rehash = ksnum; - num_found = 0; - for (z = ksnum; z < KTNUM; z++) { - max_rehash = 0; - for (name = tab, i = z; --i >= 0;) - *name++ = 0; - for (i = 0; i < ksnum; i++) { - name = info[i].name; - sig = 0; - while ((c = *name++)) - sig = (sig << 1) + c; - first = j = sig % z; - for (k = 0; tab[j]; k++) { - j += first + 1; - if (j >= z) - j -= z; - if (j == first) - goto next1; - } - tab[j] = 1; - if (k > max_rehash) - max_rehash = k; - } - if (max_rehash < MIN_REHASH) { - if (max_rehash < best_max_rehash) { - best_max_rehash = max_rehash; - best_z = z; - } - num_found++; - if (num_found >= MATCHES) - break; - } -next1: ; - } - - z = best_z; - if (z == 0) { - fprintf(stderr, "makekeys: failed to find small enough hash!\n" - "Try increasing KTNUM in makekeys.c\n"); - exit(1); - } - printf("#ifdef NEEDKTABLE\n"); - printf("const unsigned char _XkeyTable[] = {\n"); - printf("0,\n"); - k = 1; - for (i = 0; i < ksnum; i++) { - name = info[i].name; - sig = 0; - while ((c = *name++)) - sig = (sig << 1) + c; - first = j = sig % z; - while (offsets[j]) { - j += first + 1; - if (j >= z) - j -= z; - } - offsets[j] = k; - indexes[i] = k; - val = info[i].val; - printf("0x%.2lx, 0x%.2lx, 0x%.2lx, 0x%.2lx, 0x%.2lx, 0x%.2lx, ", - (sig >> 8) & 0xff, sig & 0xff, - (val >> 24) & 0xff, (val >> 16) & 0xff, - (val >> 8) & 0xff, val & 0xff); - for (name = info[i].name, k += 7; (c = *name++); k++) - printf("'%c',", c); - printf((i == (ksnum-1)) ? "0\n" : "0,\n"); - } - printf("};\n"); - printf("\n"); - printf("#define KTABLESIZE %d\n", z); - printf("#define KMAXHASH %d\n", best_max_rehash + 1); - printf("\n"); - printf("static const unsigned short hashString[KTABLESIZE] = {\n"); - for (i = 0; i < z;) { - printf("0x%.4x", offsets[i]); - i++; - if (i == z) - break; - printf((i & 7) ? ", " : ",\n"); - } - printf("\n"); - printf("};\n"); - printf("#endif /* NEEDKTABLE */\n"); - - best_max_rehash = ksnum; - num_found = 0; - for (z = ksnum; z < KTNUM; z++) { - max_rehash = 0; - for (name = tab, i = z; --i >= 0;) - *name++ = 0; - for (i = 0; i < ksnum; i++) { - val = info[i].val; - first = j = val % z; - for (k = 0; tab[j]; k++) { - if (values[j] == val) - goto skip1; - j += first + 1; - if (j >= z) - j -= z; - if (j == first) - goto next2; - } - tab[j] = 1; - values[j] = val; - if (k > max_rehash) - max_rehash = k; -skip1: ; - } - if (max_rehash < MIN_REHASH) { - if (max_rehash < best_max_rehash) { - best_max_rehash = max_rehash; - best_z = z; - } - num_found++; - if (num_found >= MATCHES) - break; - } -next2: ; - } - - z = best_z; - if (z == 0) { - fprintf(stderr, "makekeys: failed to find small enough hash!\n" - "Try increasing KTNUM in makekeys.c\n"); - exit(1); - } - for (i = z; --i >= 0;) - offsets[i] = 0; - for (i = 0; i < ksnum; i++) { - val = info[i].val; - first = j = val % z; - while (offsets[j]) { - if (values[j] == val) - goto skip2; - j += first + 1; - if (j >= z) - j -= z; - } - offsets[j] = indexes[i] + 2; - values[j] = val; -skip2: ; - } - printf("\n"); - printf("#ifdef NEEDVTABLE\n"); - printf("#define VTABLESIZE %d\n", z); - printf("#define VMAXHASH %d\n", best_max_rehash + 1); - printf("\n"); - printf("static const unsigned short hashKeysym[VTABLESIZE] = {\n"); - for (i = 0; i < z;) { - printf("0x%.4x", offsets[i]); - i++; - if (i == z) - break; - printf((i & 7) ? ", " : ",\n"); - } - printf("\n"); - printf("};\n"); - printf("#endif /* NEEDVTABLE */\n"); - - exit(0); -} +/*
+
+Copyright 1990, 1998 The Open Group
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of The Open Group shall
+not be used in advertising or otherwise to promote the sale, use or
+other dealings in this Software without prior written authorization
+from The Open Group.
+
+*/
+
+/* Constructs hash tables for XStringToKeysym and XKeysymToString. */
+
+#include <X11/X.h>
+#include <X11/Xos.h>
+#include <X11/keysymdef.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+typedef unsigned long Signature;
+
+#define KTNUM 4000
+
+static struct info {
+ char *name;
+ KeySym val;
+} info[KTNUM];
+
+#define MIN_REHASH 15
+#define MATCHES 10
+
+static char tab[KTNUM];
+static unsigned short offsets[KTNUM];
+static unsigned short indexes[KTNUM];
+static KeySym values[KTNUM];
+static char buf[1024];
+static int ksnum = 0;
+
+static int
+parse_line(const char *buf, char *key, KeySym *val, char *prefix)
+{
+ int i;
+ char alias[128];
+ char *tmp, *tmpa;
+
+ /* See if we can catch a straight XK_foo 0x1234-style definition first;
+ * the trickery around tmp is to account for prefices. */
+ i = sscanf(buf, "#define %127s 0x%lx", key, val);
+ if (i == 2 && (tmp = strstr(key, "XK_"))) {
+ memcpy(prefix, key, tmp - key);
+ prefix[tmp - key] = '\0';
+ tmp += 3;
+ memmove(key, tmp, strlen(tmp) + 1);
+ return 1;
+ }
+
+ /* Now try to catch alias (XK_foo XK_bar) definitions, and resolve them
+ * immediately: if the target is in the form XF86XK_foo, we need to
+ * canonicalise this to XF86foo before we do the lookup. */
+ i = sscanf(buf, "#define %127s %127s", key, alias);
+ if (i == 2 && (tmp = strstr(key, "XK_")) && (tmpa = strstr(alias, "XK_"))) {
+ memcpy(prefix, key, tmp - key);
+ prefix[tmp - key] = '\0';
+ tmp += 3;
+ memmove(key, tmp, strlen(tmp) + 1);
+ memmove(tmpa, tmpa + 3, strlen(tmpa + 3) + 1);
+
+ for (i = ksnum - 1; i >= 0; i--) {
+ if (strcmp(info[i].name, alias) == 0) {
+ *val = info[i].val;
+ return 1;
+ }
+ }
+
+ fprintf(stderr, "can't find matching definition %s for keysym %s%s\n",
+ alias, prefix, key);
+ }
+
+ return 0;
+}
+
+int
+main(int argc, char *argv[])
+{
+ int max_rehash;
+ Signature sig;
+ int i, j, k, l, z;
+ FILE *fptr;
+ char *name;
+ char c;
+ int first;
+ int best_max_rehash;
+ int best_z = 0;
+ int num_found;
+ KeySym val;
+ char key[128], prefix[128];
+
+ for (l = 1; l < argc; l++) {
+ fptr = fopen(argv[l], "r");
+ if (!fptr) {
+ fprintf(stderr, "couldn't open %s\n", argv[l]);
+ continue;
+ }
+
+ while (fgets(buf, sizeof(buf), fptr)) {
+ if (!parse_line(buf, key, &val, prefix))
+ continue;
+
+ if (val == XK_VoidSymbol)
+ val = 0;
+ if (val > 0x1fffffff) {
+ fprintf(stderr, "ignoring illegal keysym (%s, %lx)\n", key,
+ val);
+ continue;
+ }
+
+ name = malloc(strlen(prefix) + strlen(key) + 1);
+ if (!name) {
+ fprintf(stderr, "makekeys: out of memory!\n");
+ exit(1);
+ }
+ sprintf(name, "%s%s", prefix, key);
+ info[ksnum].name = name;
+ info[ksnum].val = val;
+ ksnum++;
+ if (ksnum == KTNUM) {
+ fprintf(stderr, "makekeys: too many keysyms!\n");
+ exit(1);
+ }
+ }
+
+ fclose(fptr);
+ }
+
+ printf("/* This file is generated from keysymdef.h. */\n");
+ printf("/* Do not edit. */\n");
+ printf("\n");
+
+ best_max_rehash = ksnum;
+ num_found = 0;
+ for (z = ksnum; z < KTNUM; z++) {
+ max_rehash = 0;
+ for (name = tab, i = z; --i >= 0;)
+ *name++ = 0;
+ for (i = 0; i < ksnum; i++) {
+ name = info[i].name;
+ sig = 0;
+ while ((c = *name++))
+ sig = (sig << 1) + c;
+ first = j = sig % z;
+ for (k = 0; tab[j]; k++) {
+ j += first + 1;
+ if (j >= z)
+ j -= z;
+ if (j == first)
+ goto next1;
+ }
+ tab[j] = 1;
+ if (k > max_rehash)
+ max_rehash = k;
+ }
+ if (max_rehash < MIN_REHASH) {
+ if (max_rehash < best_max_rehash) {
+ best_max_rehash = max_rehash;
+ best_z = z;
+ }
+ num_found++;
+ if (num_found >= MATCHES)
+ break;
+ }
+next1: ;
+ }
+
+ z = best_z;
+ if (z == 0) {
+ fprintf(stderr, "makekeys: failed to find small enough hash!\n"
+ "Try increasing KTNUM in makekeys.c\n");
+ exit(1);
+ }
+ printf("#ifdef NEEDKTABLE\n");
+ printf("const unsigned char _XkeyTable[] = {\n");
+ printf("0,\n");
+ k = 1;
+ for (i = 0; i < ksnum; i++) {
+ name = info[i].name;
+ sig = 0;
+ while ((c = *name++))
+ sig = (sig << 1) + c;
+ first = j = sig % z;
+ while (offsets[j]) {
+ j += first + 1;
+ if (j >= z)
+ j -= z;
+ }
+ offsets[j] = k;
+ indexes[i] = k;
+ val = info[i].val;
+ printf("0x%.2lx, 0x%.2lx, 0x%.2lx, 0x%.2lx, 0x%.2lx, 0x%.2lx, ",
+ (sig >> 8) & 0xff, sig & 0xff,
+ (val >> 24) & 0xff, (val >> 16) & 0xff,
+ (val >> 8) & 0xff, val & 0xff);
+ for (name = info[i].name, k += 7; (c = *name++); k++)
+ printf("'%c',", c);
+ printf((i == (ksnum-1)) ? "0\n" : "0,\n");
+ }
+ printf("};\n");
+ printf("\n");
+ printf("#define KTABLESIZE %d\n", z);
+ printf("#define KMAXHASH %d\n", best_max_rehash + 1);
+ printf("\n");
+ printf("static const unsigned short hashString[KTABLESIZE] = {\n");
+ for (i = 0; i < z;) {
+ printf("0x%.4x", offsets[i]);
+ i++;
+ if (i == z)
+ break;
+ printf((i & 7) ? ", " : ",\n");
+ }
+ printf("\n");
+ printf("};\n");
+ printf("#endif /* NEEDKTABLE */\n");
+
+ best_max_rehash = ksnum;
+ num_found = 0;
+ for (z = ksnum; z < KTNUM; z++) {
+ max_rehash = 0;
+ for (name = tab, i = z; --i >= 0;)
+ *name++ = 0;
+ for (i = 0; i < ksnum; i++) {
+ val = info[i].val;
+ first = j = val % z;
+ for (k = 0; tab[j]; k++) {
+ if (values[j] == val)
+ goto skip1;
+ j += first + 1;
+ if (j >= z)
+ j -= z;
+ if (j == first)
+ goto next2;
+ }
+ tab[j] = 1;
+ values[j] = val;
+ if (k > max_rehash)
+ max_rehash = k;
+skip1: ;
+ }
+ if (max_rehash < MIN_REHASH) {
+ if (max_rehash < best_max_rehash) {
+ best_max_rehash = max_rehash;
+ best_z = z;
+ }
+ num_found++;
+ if (num_found >= MATCHES)
+ break;
+ }
+next2: ;
+ }
+
+ z = best_z;
+ if (z == 0) {
+ fprintf(stderr, "makekeys: failed to find small enough hash!\n"
+ "Try increasing KTNUM in makekeys.c\n");
+ exit(1);
+ }
+ for (i = z; --i >= 0;)
+ offsets[i] = 0;
+ for (i = 0; i < ksnum; i++) {
+ val = info[i].val;
+ first = j = val % z;
+ while (offsets[j]) {
+ if (values[j] == val)
+ goto skip2;
+ j += first + 1;
+ if (j >= z)
+ j -= z;
+ }
+ offsets[j] = indexes[i] + 2;
+ values[j] = val;
+skip2: ;
+ }
+ printf("\n");
+ printf("#ifdef NEEDVTABLE\n");
+ printf("#define VTABLESIZE %d\n", z);
+ printf("#define VMAXHASH %d\n", best_max_rehash + 1);
+ printf("\n");
+ printf("static const unsigned short hashKeysym[VTABLESIZE] = {\n");
+ for (i = 0; i < z;) {
+ printf("0x%.4x", offsets[i]);
+ i++;
+ if (i == z)
+ break;
+ printf((i & 7) ? ", " : ",\n");
+ }
+ printf("\n");
+ printf("};\n");
+ printf("#endif /* NEEDVTABLE */\n");
+
+ exit(0);
+}
|