summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatt Dew <matt@osource.org>2010-07-08 14:42:32 -0400
committerGaetan Nadon <memsize@videotron.ca>2010-07-08 14:46:33 -0400
commite14273f44c1501ab51db4adcb83b18a1073787d8 (patch)
treea828ab414d1168ccc50d43aec33dc4d81837bd23
parentbea0873caf50e9ed1b89255775d9ab912cbecd45 (diff)
specs: replace troff source with docbook-xml source
Signed-off-by: Gaetan Nadon <memsize@videotron.ca>
-rw-r--r--configure.ac13
-rw-r--r--specs/.gitignore2
-rw-r--r--specs/libX11/AppA604
-rw-r--r--specs/libX11/AppA.xml540
-rw-r--r--specs/libX11/AppB101
-rw-r--r--specs/libX11/AppB.xml49
-rw-r--r--specs/libX11/AppC2230
-rw-r--r--specs/libX11/AppC.xml3352
-rw-r--r--specs/libX11/AppD1183
-rw-r--r--specs/libX11/AppD.xml1900
-rw-r--r--specs/libX11/CH01.xml (renamed from specs/libX11/CH01)884
-rw-r--r--specs/libX11/CH022051
-rw-r--r--specs/libX11/CH02.xml3488
-rw-r--r--specs/libX11/CH033121
-rw-r--r--specs/libX11/CH03.xml4162
-rw-r--r--specs/libX11/CH041595
-rw-r--r--specs/libX11/CH04.xml2647
-rw-r--r--specs/libX11/CH05518
-rw-r--r--specs/libX11/CH05.xml815
-rw-r--r--specs/libX11/CH064773
-rw-r--r--specs/libX11/CH06.xml7439
-rw-r--r--specs/libX11/CH072357
-rw-r--r--specs/libX11/CH07.xml3401
-rw-r--r--specs/libX11/CH083468
-rw-r--r--specs/libX11/CH08.xml5960
-rw-r--r--specs/libX11/CH091290
-rw-r--r--specs/libX11/CH09.xml2012
-rw-r--r--specs/libX11/CH103886
-rw-r--r--specs/libX11/CH10.xml4725
-rw-r--r--specs/libX11/CH111664
-rw-r--r--specs/libX11/CH11.xml2539
-rw-r--r--specs/libX11/CH122680
-rw-r--r--specs/libX11/CH12.xml3928
-rw-r--r--specs/libX11/CH137673
-rw-r--r--specs/libX11/CH13.xml10350
-rw-r--r--specs/libX11/CH143590
-rw-r--r--specs/libX11/CH14.xml5190
-rw-r--r--specs/libX11/CH151628
-rw-r--r--specs/libX11/CH15.xml2485
-rw-r--r--specs/libX11/CH162364
-rw-r--r--specs/libX11/CH16.xml4136
-rw-r--r--specs/libX11/Makefile.am57
-rw-r--r--specs/libX11/abstract.t105
-rw-r--r--specs/libX11/credits.xml (renamed from specs/libX11/credits.t)115
-rw-r--r--specs/libX11/glossary.xml (renamed from specs/libX11/glossary)2183
-rw-r--r--specs/libX11/indexmacros.t3
-rw-r--r--specs/libX11/libX11.ms24
-rw-r--r--specs/libX11/libX11.xml148
-rw-r--r--specs/libX11/postproc17
-rw-r--r--specs/xmlrules.in60
50 files changed, 71247 insertions, 48258 deletions
diff --git a/configure.ac b/configure.ac
index 577f581c..90c9179e 100644
--- a/configure.ac
+++ b/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
diff --git a/specs/.gitignore b/specs/.gitignore
index ac21ee43..eba39221 100644
--- a/specs/.gitignore
+++ b/specs/.gitignore
@@ -3,6 +3,8 @@
*.ps
*.pdf
*.txt
+*.css
+# Delete the following 4 lines when groff is gone
*.html.raw
*.ps.raw
*.txt.raw
diff --git a/specs/libX11/AppA b/specs/libX11/AppA
deleted file mode 100644
index 26a1ba32..00000000
--- a/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/specs/libX11/AppA.xml b/specs/libX11/AppA.xml
new file mode 100644
index 00000000..443f5d46
--- /dev/null
+++ b/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/specs/libX11/AppB b/specs/libX11/AppB
deleted file mode 100644
index 2e57ede8..00000000
--- a/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/specs/libX11/AppB.xml b/specs/libX11/AppB.xml
new file mode 100644
index 00000000..54352295
--- /dev/null
+++ b/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/specs/libX11/AppC b/specs/libX11/AppC
deleted file mode 100644
index 43261ba8..00000000
--- a/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/specs/libX11/AppC.xml b/specs/libX11/AppC.xml
new file mode 100644
index 00000000..52fff317
--- /dev/null
+++ b/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
+&lt;X11/Xlibint.h&gt; .
+<!-- .SH -->
+Basic Protocol Support Routines
+</para>
+<para>
+The basic protocol requests for extensions are
+<function>XQueryExtension</function>
+and
+<function>XListExtensions .</function>
+</para>
+<!-- .IN "XQueryExtension" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XListExtensions" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XFreeExtensionList" "" "@DEF@" -->
+<!-- .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
+&lt;X11/Xlib.h&gt; :
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "XExtCodes" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XInitExtension" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XAddExtension" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XESetCloseDisplay" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XESetCreateGC" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XESetCopyGC" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XESetCreateFont" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XESetFreeFont" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XESetWireToEvent" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "_XSetLastRequestRead" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XESetEventToWire" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XESetWireToError" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XESetError" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XESetErrorString" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XESetPrintErrorValues" "" "@DEF@" -->
+<!-- .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 POSIX-compliant system, fp should be cast to type FILE*.
+<!-- .IN "XESetFlushGC" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XESetBeforeFlush" "" "@DEF@" -->
+<!-- .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
+&lt;X11/Xlib.h&gt;
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "XExtData" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XEHeadOfExtensionList" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XAddToExtensionList" "" "@DEF@" -->
+<!-- .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-&gt;number with the extension number
+before calling this function.
+<!-- .IN "XFindOnExtensionList" "" "@DEF@" -->
+<!-- .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
+&lt;X11/Xlib.h&gt;.
+<!-- .IN "XAllocID" "" "@DEF@" -->
+<!-- .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.
+<!-- .IN "XAllocIDs" "" "@DEF@" -->
+<!-- .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:
+<!-- .IN "FlushGC" "" "@DEF@" -->
+<!-- .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:
+<!-- .IN "_XFlushGCCache" "" "@DEF@" -->
+<!-- .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 &lt;X11/Xlibint.h&gt;
+
+/* 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-&gt;last_req;
+ /* if same as previous request, with same drawable, batch requests */
+ if (
+ (req-&gt;reqType == X_PolyPoint)
+ &amp;&amp; (req-&gt;drawable == d)
+ &amp;&amp; (req-&gt;gc == gc-&gt;gid)
+ &amp;&amp; (req-&gt;coordMode == CoordModeOrigin)
+ &amp;&amp; ((dpy-&gt;bufptr + sizeof (xPoint)) &lt;= dpy-&gt;bufmax)
+ &amp;&amp; (((char *)dpy-&gt;bufptr - (char *)req) &lt; size) ) {
+ point = (xPoint *) dpy-&gt;bufptr;
+ req-&gt;length += sizeof (xPoint) &gt;&gt; 2;
+ dpy-&gt;bufptr += sizeof (xPoint);
+ }
+
+ else {
+ GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
+ req-&gt;drawable = d;
+ req-&gt;gc = gc-&gt;gid;
+ req-&gt;coordMode = CoordModeOrigin;
+ point = (xPoint *) (req + 1);
+ }
+ point-&gt;x = x;
+ point-&gt;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
+&lt;X11/Xlibint.h&gt;
+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-&gt;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
+&lt;X11/Xproto.h&gt;
+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
+&lt;X11/Xproto.h&gt;
+for your extension and need to include it in your stub procedure.
+Each stub procedure also must include
+&lt;X11/Xlibint.h&gt; .
+</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
+&lt;X11/Xlibint.h&gt; ,
+takes advantage of this naming scheme.
+</para>
+<para>
+<!-- .LP -->
+For each X request,
+there is a definition in
+&lt;X11/Xproto.h&gt;
+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
+&lt;X11/Xproto.h&gt;,
+which looks like:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "xDoSomethingReq" "" "@DEF@" -->
+<!-- .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
+&lt;X11/Xproto.h&gt;.
+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 -->
+<!-- .IN "xResourceReq" "" "@DEF@" -->
+<!-- .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
+&lt;X11/Xproto.h&gt;,
+which contains only a reqType and a length (and a pad byte).
+</para>
+<para>
+<!-- .LP -->
+If the protocol request requires a reply,
+then
+&lt;X11/Xproto.h&gt;
+also contains a reply structure typedef:
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "xDoSomethingReply" "" "@DEF@" -->
+<!-- .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.
+&lt;X11/Xproto.h&gt;
+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 "&lt;X11/Xlibint.h&gt;
+
+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.
+<!-- .IN "LockDisplay" "" "@DEF@" -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> LockDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .IN "UnlockDisplay" "" "@DEF@" -->
+<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
+&lt;X11/Xlibint.h&gt;:
+<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
+&lt;X11/Xproto.h&gt;
+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-&gt;arg1 = arg1;
+req-&gt;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-&gt;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-&gt;length += (nbytes+3)&gt;&gt;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.
+<!-- .IN "_XReply" "" "@DEF@" -->
+<!-- .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 *)&amp;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:
+<!-- .IN "_XAllocScratch" "" "@DEF@" -->
+<!-- .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:
+<!-- .IN "_XAllocTemp" "" "@DEF@" -->
+<!-- .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:
+<!-- .IN "_XFreeTemp" "" "@DEF@" -->
+<!-- .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 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 <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
+&lt;stdio.h&gt;
+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/specs/libX11/AppD b/specs/libX11/AppD
deleted file mode 100644
index f96e0617..00000000
--- a/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/specs/libX11/AppD.xml b/specs/libX11/AppD.xml
new file mode 100644
index 00000000..128ad3dd
--- /dev/null
+++ b/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.
+<!-- .IN "XSetStandardProperties" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XSetNormalHints" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XGetNormalHints" "" "@DEF@" -->
+<!-- .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>.
+<!-- .IN "XSetZoomHints" "" "@DEF@" -->
+<!-- .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>.
+<!-- .IN "XGetZoomHints" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XSetSizeHints" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XGetSizeHints" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XGetStandardColormap" "" "@DEF@" -->
+<!-- .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), &amp;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>
+<!-- .IN "XSetStandardColormap" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "Window" "determining location" -->
+<!-- .IN "XGeometry" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .IN "XGetDefault" "" "@DEF@" -->
+<!-- .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 POSIX-conformant system,
+this file is
+<function>"$HOME/.Xdefaults" .</function>
+<!-- .IN "Files" "$HOME/.Xdefaults" -->
+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>
+<!-- .IN "XDrawLines" -->
+or
+<function>XDrawSegments </function>
+<!-- .IN "XDrawSegments" -->
+is much faster.
+</para>
+<para>
+<!-- .LP -->
+The functions discussed here provide all the functionality of the
+X Version 10 functions
+<function>XDraw , </function>
+<!-- .IN "X10 compatibility" "XDraw" -->
+<function>XDrawFilled , </function>
+<!-- .IN "X10 compatibility" "XDrawFilled" -->
+<function>XDrawPatterned , </function>
+<!-- .IN "X10 compatibility" "XDrawPatterned" -->
+<function>XDrawDashed , </function>
+<!-- .IN "X10 compatibility" "XDrawDashed" -->
+and
+<function>XDrawTiled . </function>
+<!-- .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
+<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>
+<!-- .IN "X10 compatibility" "XDraw" -->
+<function>XDrawDashed , </function>
+<!-- .IN "X10 compatibility" "XDrawDashed" -->
+and
+<function>XDrawPatterned , </function>
+<!-- .IN "X10 compatibility" "XDrawPatterned" -->
+use
+<function>XDraw . </function>
+</para>
+
+<para>
+#include &lt;X11/X10.h&gt;
+</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 -->
+<!-- .IN "Vertex" "" "@DEF@" -->
+<!-- .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:
+<!-- .IN "VertexRelative" "" "@DEF@" -->
+<!-- .IN "VertexDontDraw" "" "@DEF@" -->
+<!-- .IN "VertexCurved" "" "@DEF@" -->
+<!-- .IN "VertexStartClosed" "" "@DEF@" -->
+<!-- .IN "VertexEndClosed" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "X10 compatibility" "XDrawTiled" -->
+and
+<function>XDrawFilled , </function>
+<!-- .IN "X10 compatibility" "XDrawFilled" -->
+use
+<function>XDrawFilled .</function>
+</para>
+
+<para>#include &lt;X11/X10.h&gt;</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.
+<!-- .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
+<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>
+<!-- .IN "XCreateAssocTable" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XMakeAssoc" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XLookUpAssoc" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XDeleteAssoc" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XDestroyAssocTable" "" "@DEF@" -->
+<!-- .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/specs/libX11/CH01 b/specs/libX11/CH01.xml
index 765e4b5f..8d8e1d69 100644
--- a/specs/libX11/CH01
+++ b/specs/libX11/CH01.xml
@@ -1,127 +1,56 @@
-.\" 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
+<chapter><title>Introduction to Xlib</title>
-\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
+<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.
-.LP
+</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
@@ -130,27 +59,31 @@ 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"
+</para>
+<para>
+<!-- .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"
+<!-- .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
+</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.
-.IN "Stacking order"
+<!-- .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.
@@ -159,8 +92,10 @@ 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@"
+</para>
+<para>
+<!-- .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,
@@ -168,7 +103,9 @@ 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
+</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.
@@ -177,26 +114,32 @@ 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
+</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
-.PN Expose
+<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.
-.LP
-.IN "Pixmap"
-.IN "Drawable"
-.IN "Tile"
-.IN "Bitmap"
+</para>
+<para>
+<!-- .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
+</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
@@ -204,35 +147,39 @@ 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"
+</para>
+<para>
+<!-- .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 ,
+<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.
-.LP
-.IN "Resource IDs"
-.IN "Resource IDs" "Window"
-.IN "Resource IDs" "Font"
-.IN "Resource IDs" "Pixmap"
-.IN "Resource IDs" "Cursor"
-.IN "Resource IDs" "GContext"
+</para>
+<para>
+<!-- .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 ,
+<function>Window , </function>
+<function>Font , </function>
+<function>Pixmap , </function>
+<function>Colormap ,</function>
+<function>Cursor , </function>
and
-.PN GContext ,
+<function>GContext ,</function>
as defined in the file
-.hN X11/X.h .
+<!-- .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
@@ -242,394 +189,598 @@ 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"
+</para>
+<para>
+<!-- .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
+<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.
-.LP
+</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,
-.PN XNextEvent
+<function>XNextEvent</function>
or
-.PN XWindowEvent ).
+<function>XWindowEvent ).</function>
In addition, some library
functions (for example,
-.PN XRaiseWindow )
+<function>XRaiseWindow )</function>
generate
-.PN Expose
+<function>Expose</function>
and
-.PN ConfigureRequest
+<function>ConfigureRequest</function>
events.
These events also arrive asynchronously, but the client may
-.IN "XSync"
+<!-- .IN "XSync" -->
wish to explicitly wait for them by calling
-.PN XSync
+<function>XSync</function>
after calling a function that can cause the server to generate events.
-.NH 2
-Errors
-.XS
-\*(SN Errors
-.XE
-.LP
+</para>
+</sect1>
+<sect1 id="Errors">
+<title>Errors</title>
+<!-- .XS -->
+<!-- (SN Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
Some functions return
-.PN Status ,
+<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.
-.IN "Status"
+<!-- .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"
+<!-- .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
+</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.
-.LP
+</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).
+(see section 11.8.1). <!-- xref -->
When synchronization is enabled,
errors are reported as they are generated.
-.LP
+</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.
-.NH 2
-Standard Header Files
-.XS
-\*(SN Standard Header Files
-.XE
-.LP
+</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:
-.IP \(bu 5
-.hN X11/Xlib.h
-.IP
+</para>
+<!-- .IP \(bu 5 -->
+<!-- .hN X11/Xlib.h -->
+<!-- .IP -->
+
+<variablelist>
+ <varlistentry>
+ <term>&lt;/X11/Xlib.h&gt;</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
-.PN XlibSpecificationRelease .
-.IN "XlibSpecificationRelease" "" "@DEF@"
+<function>XlibSpecificationRelease .</function>
+<!-- .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
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/X.h&gt;</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
-.hN X11/Xlib.h ,
-so application code should never need to reference this file directly.
-.IP \(bu 5
-.hN X11/Xcms.h
-.IP
+to be used by applications. It is included automatically from
+&gt;X11/Xlib.h&lt; so application code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xcms.h&gt;</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'',
+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.
-.hN X11/Xlib.h
-must be included before including this file.
-.IP \(bu 5
-.hN X11/Xutil.h
-.IP
+&lt;X11/Xlib.h&gt; must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xutil.h&gt;</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.
-.hN X11/Xlib.h
-must be included before including this file.
-.IP \(bu 5
-.hN X11/Xresource.h
-.IP
+which are described in chapters 14 and 16. <!-- xref -->
+&lt;X11/Xlib.h&gt; must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xresource.h&gt;</term>
+ <listitem>
+ <para>
This file declares all functions, types, and symbols for the
resource manager facilities, which are described in chapter 15.
-.hN X11/Xlib.h
+&lt;X11/Xlib.h&gt; <!-- xref -->
must be included before including this file.
-.IP \(bu 5
-.hN X11/Xatom.h
-.IP
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xatom.h&gt;</term>
+ <listitem>
+ <para>
This file declares all predefined atoms,
-which are symbols with the prefix ``XA_''.
-.IP \(bu 5
-.hN X11/cursorfont.h
-.IP
+which are symbols with the prefix "XA_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/cursorfont.h&gt;</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_''.
-.IP \(bu 5
-.hN X11/keysymdef.h
-.IP
+All cursor symbols have the prefix "XC_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/keysymdef.h&gt;</term>
+ <listitem>
+ <para>
This file declares all standard KeySym values,
-which are symbols with the prefix ``XK_''.
+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
+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>&lt;X11/keysym.h&gt;</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
-.hN X11/keysymdef.h .
-.IP \(bu 5
-.hN X11/Xlibint.h
-.IP
+and then includes &lt;X11/keysymdef.h&gt;
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xlibint.h&gt;</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
-.hN X11/Xlib.h .
-.IP \(bu 5
-.hN X11/Xproto.h
-.IP
+&lt;X11/Xlib.h&lt;.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xproto.h&gt;</term>
+ <listitem>
+ <para>
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 ,
+&lt;X11/Xlibint.h&lt;,
so application and extension code should never need to
reference this file directly.
-.IP \(bu 5
-.hN X11/Xprotostr.h
-.IP
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/Xprotostr.h&gt;</term>
+ <listitem>
+ <para>
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 ,
+&lt;X11/Xproto.h&lt;,
so application and extension code should never need to
reference this file directly.
-.IP \(bu 5
-.hN X11/X10.h
-.IP
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&lt;X11/X10.h&gt;</term>
+ <listitem>
+ <para>
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
+ </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:
-.IN "Bool" "" "@DEF@"
-.IN "True" "" "@DEF@"
-.IN "False" "" "@DEF@"
-.IP \(bu 5
+<!-- .IN "Bool" "" "@DEF@" -->
+<!-- .IN "True" "" "@DEF@" -->
+<!-- .IN "False" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
Xlib defines the type
-.PN Bool
+<function>Bool</function>
and the Boolean values
-.PN True
+<function>True</function>
and
-.PN False .
-.IN "None" "" "@DEF@"
-.IP \(bu 5
-.PN None
+<function>False .</function>
+<!-- .IN "None" "" "@DEF@" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>None</function>
is the universal null resource ID or atom.
-.IN "XID" "" "@DEF@"
-.IP \(bu 5
+<!-- .IN "XID" "" "@DEF@" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The type
-.PN XID
+<function>XID</function>
is used for generic resource IDs.
-.IN "XPointer" "" "@DEF@"
-.IP \(bu 5
+<!-- .IN "XPointer" "" "@DEF@" -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The type
-.PN XPointer
+<function>XPointer</function>
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
+ </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.
-.LP
+</para>
+<para>
+<!-- .LP -->
The major naming conventions are:
-.IP \(bu 5
+</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.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
All Xlib functions begin with a capital X.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The beginnings of all function names and symbols are capitalized.
-.IP \(bu 5
+ </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.
-.IP \(bu 5
+ </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.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
All elements of or variables in a data structure are in lowercase.
-Compound words, where needed, are constructed with underscores (\^_\^).
-.IP \(bu 5
+Compound words, where needed, are constructed with underscores (_).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The display argument, where used, is always first in the argument list.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
All resource objects, where used, occur at the beginning of the argument list
immediately after the display argument.
-.IP \(bu 5
+ </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.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Source arguments always precede the destination arguments in the argument list.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The x argument always precedes the y argument in the argument list.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The width argument always precedes the height argument in the argument list.
-.IP \(bu 5
+ </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.
-.IP \(bu 5
+ </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.
-.NH 2
-Programming Considerations
-.XS
-\*(SN Programming Considerations
-.XE
-.LP
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Programming_Considerations">
+<title>Programming Considerations</title>
+<!-- .XS -->
+<!-- (SN Programming Considerations -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
The major programming considerations are:
-.IP \(bu 5
+</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
-.PN int
+<function>int </function>
in the interface.
Values larger than 16 bits are truncated silently.
Sizes (width and height) are declared as unsigned quantities.
-.IP \(bu 5
+ </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.
-.IP \(bu 5
+ </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.
-.IP \(bu 5
+ </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
-and the \fIInter-Client Communication Conventions Manual\fP.
-.NH 2
-Character Sets and Encodings
-.XS
-\*(SN Character Sets and Encodings
-.XE
-.LP
+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:
-.IP \(bu 5
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
X Portable Character Set
-.IP
+ </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:
-.IP
-.Ds 0
-.EQ
-delim DD
-.EN
-a..z A..Z 0..9
-!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
-<space>, <tab>, and <newline>
-.EQ
-delim %%
-.EN
-.De
-.IP
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a..z A..Z 0..9 !"#$%&amp;'()*+,-./:;&lt;=&gt;?@[\\]^_`{|}~ &lt;space&gt;, &lt;tab&gt;, and &lt;newline&gt;
+ </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.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Host Portable Character Encoding
-.IP
+ </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.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Latin-1
-.IP
+ </para>
+ </listitem>
+ <listitem>
+ <para>
The coded character set defined by the ISO8859-1 standard.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Latin Portable Character Encoding
-.IP
+ </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.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
STRING Encoding
-.IP
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Latin-1, plus tab and newline.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
POSIX Portable Filename Character Set
-.IP
+ </para>
+ </listitem>
+ <listitem>
+ <para>
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
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literallayout class="monospaced">
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
+</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
-.PN this
-.PN special
-.PN font .
+<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 \fIitalics\fP.
+function arguments are printed in <emphasis remap='I'>italics</emphasis>.
In the explanatory text that follows,
they usually are printed in regular type.
-.IP \(bu 5
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Each function is introduced by a general discussion that
distinguishes it from other functions.
The function declaration itself follows,
@@ -643,21 +794,32 @@ 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
+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
-\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP.
+<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 \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
+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 \fIspecifies and returns\^\fP.
-.IP \(bu 5
+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 \fI_return\fP suffix as part of its name.
+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 \fI_in_out\fP suffix.
-.bp
+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/specs/libX11/CH02 b/specs/libX11/CH02
deleted file mode 100644
index dbf0b485..00000000
--- a/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/specs/libX11/CH02.xml b/specs/libX11/CH02.xml
new file mode 100644
index 00000000..0d281067
--- /dev/null
+++ b/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>
+<!-- .IN "XOpenDisplay" "" "@DEF@" -->
+</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 POSIX-conformant system, if the display_name is NULL,
+it defaults to the value of the DISPLAY environment variable.
+<!-- .IN "Environment" "DISPLAY" -->
+ </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 POSIX-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 CPU can have more than one display.
+Multiple displays are usually numbered starting with zero.
+<!-- .IN "Screen" -->
+ </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 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,
+<function>XOpenDisplay</function>
+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,
+<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 -->
+<!-- .IN "Display" -->
+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 -->
+<!-- .IN "Display" "data structure" -->
+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 -->
+<!-- .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.
+</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 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 -->
+</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 -->
+<!-- .IN "BlackPixel" "" "@DEF@" -->
+<!-- .IN "XBlackPixel" "" "@DEF@" -->
+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 -->
+<!-- .IN "WhitePixel" "" "@DEF@" -->
+<!-- .IN "XWhitePixel" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .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.
+</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 -->
+<!-- .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
+<function>XMatchVisualInfo ).</function>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .IN "XListDepths" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "DefaultRootWindow" "" "@DEF@" -->
+<!-- .IN "XDefaultRootWindow" "" "@DEF@" -->
+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 -->
+<!-- .IN "DefaultScreenOfDisplay" "" "@DEF@" -->
+<!-- .IN "XDefaultScreenOfDisplay" "" "@DEF@" -->
+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 -->
+<!-- .IN "ScreenOfDisplay" "" "@DEF@" -->
+<!-- .IN "XScreenOfDisplay" "" "@DEF@" -->
+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 -->
+<!-- .IN "DefaultScreen" "" "@DEF@" -->
+<!-- .IN "XDefaultScreen" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "DisplayCells" "" "@DEF@" -->
+<!-- .IN "XDisplayCells" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "DisplayString" "" "@DEF@" -->
+<!-- .IN "XDisplayString" "" "@DEF@" -->
+Both return the string that was passed to
+<function>XOpenDisplay</function>
+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
+<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 -->
+<!-- .IN "XExtendedMaxRequestSize" "" "@DEF@" -->
+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 -->
+<!-- .IN "XMaxRequestSize" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "ProtocolVersion" "" "@DEF@" -->
+<!-- .IN "XProtocolVersion" "" "@DEF@" -->
+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 -->
+<!-- .IN "ProtocolRevision" "" "@DEF@" -->
+<!-- .IN "XProtocolRevision" "" "@DEF@" -->
+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 -->
+<!-- .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
+<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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "ScreenCount" "" "@DEF@" -->
+<!-- .IN "XScreenCount" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "VendorRelease" "" "@DEF@" -->
+<!-- .IN "XVendorRelease" "" "@DEF@" -->
+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>
+<!-- .IN "XListPixmapFormats" "" "@DEF@" -->
+<!-- .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 -->
+<!-- .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
+<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 -->
+<!-- .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.
+</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 -->
+<!-- .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
+<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 -->
+<!-- .IN "BitmapPad" "" "@DEF@" -->
+<!-- .IN "XBitmapPad" "" "@DEF@" -->
+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 -->
+<!-- .IN "DisplayHeight" "" "@DEF@" -->
+<!-- .IN "XDisplayHeight" "" "@DEF@" -->
+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 -->
+<!-- .IN "DisplayHeightMM" "" "@DEF@" -->
+<!-- .IN "XDisplayHeightMM" "" "@DEF@" -->
+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 -->
+<!-- .IN "DisplayWidth" "" "@DEF@" -->
+<!-- .IN "XDisplayWidth" "" "@DEF@" -->
+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 -->
+<!-- .IN "DisplayWidthMM" "" "@DEF@" -->
+<!-- .IN "XDisplayWidthMM" "" "@DEF@" -->
+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 -->
+<!-- .IN "BlackPixelOfScreen" "" "@DEF@" -->
+<!-- .IN "XBlackPixelOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "WhitePixelOfScreen" "" "@DEF@" -->
+<!-- .IN "XWhitePixelOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "CellsOfScreen" "" "@DEF@" -->
+<!-- .IN "XCellsOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "DefaultColormapOfScreen" "" "@DEF@" -->
+<!-- .IN "XDefaultColormapOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "DefaultDepthOfScreen" "" "@DEF@" -->
+<!-- .IN "XDefaultDepthOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .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.
+</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 -->
+<!-- .IN "DefaultVisualOfScreen" "" "@DEF@" -->
+<!-- .IN "XDefaultVisualOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "DoesBackingStore" "" "@DEF@" -->
+<!-- .IN "XDoesBackingStore" "" "@DEF@" -->
+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 -->
+<!-- .IN "DoesSaveUnders" "" "@DEF@" -->
+<!-- .IN "XDoesSaveUnders" "" "@DEF@" -->
+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 -->
+<!-- .IN "DisplayOfScreen" "" "@DEF@" -->
+<!-- .IN "XDisplayOfScreen" "" "@DEF@" -->
+Both return the display of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<!-- .IN "XScreenNumberOfScreen" "" "@DEF@" -->
+</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 -->
+<!-- .IN "EventMaskOfScreen" "" "@DEF@" -->
+<!-- .IN "XEventMaskOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "WidthOfScreen" "" "@DEF@" -->
+<!-- .IN "XWidthOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "HeightOfScreen" "" "@DEF@" -->
+<!-- .IN "XHeightOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "WidthMMOfScreen" "" "@DEF@" -->
+<!-- .IN "XWidthMMOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "HeightMMOfScreen" "" "@DEF@" -->
+<!-- .IN "XHeightMMOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "MaxCmapsOfScreen" "" "@DEF@" -->
+<!-- .IN "XMaxCmapsOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "MinCmapsOfScreen" "" "@DEF@" -->
+<!-- .IN "XMinCmapsOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "PlanesOfScreen" "" "@DEF@" -->
+<!-- .IN "XPlanesOfScreen" "" "@DEF@" -->
+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 -->
+<!-- .IN "RootWindowOfScreen" "" "@DEF@" -->
+<!-- .IN "XRootWindowOfScreen" "" "@DEF@" -->
+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>
+<!-- .IN "XNoOp" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XFree" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XCloseDisplay" "" "@DEF@" -->
+</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.
+<!-- .IN "Resource IDs" -->
+<!-- .IN "XCloseDisplay" -->
+</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>
+<!-- .IN "XSetCloseDownMode" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XInitThreads" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XLockDisplay" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XUnlockDisplay" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XRemoveConnectionWatch" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XProcessInternalConnection" "" "@DEF@" -->
+<!-- .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>
+<!-- .IN "XInternalConnectionNumbers" "" "@DEF@" -->
+<!-- .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/specs/libX11/CH03 b/specs/libX11/CH03
deleted file mode 100644
index f7eb2d4c..00000000
--- a/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